例如：fields=advertisers(advertiserId,generalConfig/domainUrl) 只会返回 advertisers 数组中每个元素的广告客户 ID 和网域网址。您还可以指定单个子字段，其中 fields=advertisers(advertiserId) 等同于 fields=advertisers/advertiserId。
使用 fields 参数的更多示例
以下示例说明了 fields 参数值对响应有何影响。
确定您希望返回的字段，或者进行字段选择。
fields 请求参数值是一个以英文逗号分隔的字段列表，并且每个字段均是相对于响应的根来指定的。因此，如果您执行的是 list 操作，响应就是一个集合，其中通常包含一组资源。如果您执行的是返回单个资源的操作，则字段是相对于该资源指定的。如果您选择的字段是（或属于）一个数组，则服务器会返回该数组中所有元素的选定部分。
[null,null,["最后更新时间 (UTC)：2025-07-25。"],[[["\u003cp\u003eThis document explains how to improve your application's performance by fetching only the necessary data using partial responses.\u003c/p\u003e\n"],["\u003cp\u003ePartial responses are achieved using the \u003ccode\u003efields\u003c/code\u003e parameter in your API requests, letting you specify the desired fields to be returned.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efields\u003c/code\u003e parameter utilizes a syntax similar to XPath, allowing you to select specific fields, nested fields, and sub-fields within objects and arrays.\u003c/p\u003e\n"],["\u003cp\u003eWhen using the \u003ccode\u003efields\u003c/code\u003e parameter, the server returns a 200 OK status with the requested data or a 400 Bad Request if the parameter is invalid.\u003c/p\u003e\n"],["\u003cp\u003eFor APIs with pagination, combine the \u003ccode\u003efields\u003c/code\u003e parameter with \u003ccode\u003emaxResults\u003c/code\u003e and \u003ccode\u003enextPageToken\u003c/code\u003e to further optimize data retrieval and enhance performance.\u003c/p\u003e\n"]]],["To enhance API call performance, request only necessary data using the `fields` parameter for a partial response. This reduces data transfer, parsing, and storage, optimizing network, CPU, and memory usage. The `fields` parameter specifies desired fields in a comma-separated list, supporting nested field selection with `a/b` and sub-selections using `( )`. The server returns an HTTP 200 OK status with the specified data or 400 Bad Request if there is an error with the parameter.\n"],null,["# Improve Performance\n\nThis document covers some techniques you can use to improve the performance of\nyour application. In some cases, examples from other implemented APIs are used\nto illustrate the ideas presented. However, the same concepts are applicable\nto the Display \\& Video 360 API.\n\nWorking with partial resources\n------------------------------\n\nAnother way to improve the performance of your API calls is to request only\nthe portion of the data that you're interested in. This lets your application\navoid transferring, parsing, and storing unneeded fields, so it can use\nresources such as network, CPU, and memory more efficiently.\n\n### Partial response\n\nBy default, the server sends back the full representation of a resource after\nprocessing requests. For better performance, you can ask the server to send\nonly the fields you really need and get a *partial response* instead.\n\nTo request a partial response, use the `fields` request parameter to specify\nthe fields you want returned. You can use this parameter with any request\nthat returns response data.\n\n#### Example\n\nThe following example shows the use of the `fields` parameter with the\nDisplay \\& Video 360 API.\n\n**Simple request:** This HTTP `GET` request omits the `fields` parameter and\nreturns the full resource. \n\n GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1\n\n**Full resource response:** The full resource data includes the following\nfields, along with many others that have been omitted for brevity. \n\n 200 OK\n\n {\n \"advertisers\": [\n {\n \"name\": \"advertisers/1\",\n \"advertiserId\": \"1\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 1\",\n \"entityStatus\": \"ENTITY_STATUS_ACTIVE\",\n \"updateTime\": \"2019-01-01T00:00:00.000000Z\",\n \"generalConfig\": {\n \"domainUrl\": \"http://example.com\",\n \"timeZone\": \"America/New_York\",\n \"currencyCode\": \"USD\",\n \"address\": {\n }\n },\n \"adServerConfig\": {\n \"thirdPartyOnlyConfig\": {\n }\n },\n \"creativeConfig\": {\n },\n \"dataAccessConfig\": {\n \"sdfConfig\": {\n \"sdfConfig\": {\n \"version\": \"VERSION_3_1\"\n }\n }\n },\n \"integrationDetails\": {\n }\n },\n {\n \"name\": \"advertisers/2\",\n \"advertiserId\": \"2\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 2\",\n \"entityStatus\": \"ENTITY_STATUS_ACTIVE\",\n \"updateTime\": \"2019-01-01T00:00:00.000000Z\",\n \"generalConfig\": {\n \"domainUrl\": \"http://example.com\",\n \"timeZone\": \"America/New_York\",\n \"currencyCode\": \"USD\",\n \"address\": {\n }\n },\n \"adServerConfig\": {\n \"thirdPartyOnlyConfig\": {\n }\n },\n \"creativeConfig\": {\n },\n \"dataAccessConfig\": {\n \"sdfConfig\": {\n \"sdfConfig\": {\n \"version\": \"VERSION_3_1\"\n }\n }\n },\n \"integrationDetails\": {\n }\n },\n ...\n ],\n \"nextPageToken\": \"...\"\n }\n\n**Request for a partial response:** The following request for this same resource\nuses the `fields` parameter to significantly reduce the amount of data returned. \n\n```text\nGET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)\n```\n\n**Partial response:** In response to the request above, the server sends back a\nresponse that contains a pared-down advertisers array that includes only the\nadvertiser ID, display name, and partner ID property of each advertiser, if\npresent. \n\n 200 OK\n\n {\n \"advertisers\": [\n {\n \"advertiserId\": \"1\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 1\"\n },\n {\n \"advertiserId\": \"2\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 2\"\n },\n ...\n ]\n }\n\nNote that the response is a JSON object that includes only the selected fields\nand their enclosing parent objects.\n\nDetails on how to format the `fields` parameter is covered next, followed by\nmore details about what exactly gets returned in the response.\n\n##### Fields parameter syntax summary\n\nThe format of the `fields` request parameter value is loosely based on XPath\nsyntax. The supported syntax is summarized below, and additional examples are\nprovided in the following section.\n\n- Use a comma-separated list to select multiple fields.\n\n- Use `a/b` to select a field `b` that is nested within field `a`; use `a/b/c`\n to select a field `c` nested within `b`.\n\n- Use a sub-selector to request a set of specific sub-fields of arrays or\n objects by placing expressions in parentheses \"`( )`\".\n\n For example: `fields=advertisers(advertiserId,generalConfig/domainUrl)`\n returns only the advertiser ID and domain URL for each element in the\n advertisers array. You can also specify a single sub-field, where\n `fields=advertisers(advertiserId)` is equivalent to\n `fields=advertisers/advertiserId`.\n\n##### More examples of using the fields parameter\n\nThe examples below include descriptions of how the `fields` parameter value\naffects the response.\n| **Note:** As with all query parameter values, the `fields` parameter value must be URL encoded. For better readability, the examples in this document omit the encoding.\n\nIdentify the fields you want returned, or make *field selections*.\n\n: The `fields` request parameter value is a comma-separated list of fields, and\n each field is specified relative to the root of the response. Thus, if you\n are performing a `list` operation, the response is a collection, and it\n generally includes an array of resources. If you are performing an operation\n that returns a single resource, fields are specified relative to that\n resource. If the field you select is (or is part of) an array, the server\n returns the selected portion of all elements in the array.\n\n Here are some collection-level examples:\n\n | Example | Effect |\n |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n | `advertisers` | Returns all elements in the `advertisers` array, including all fields in each element, but no other fields. |\n | `advertisers,nextPageToken` | Returns both the `nextPageToken` field and all elements in the `advertisers` array. |\n | `advertisers/advertiserId` | Returns only the `advertiserId` for all elements in the `advertisers` array. Whenever a nested field is returned, the response includes the enclosing parent objects. The parent fields do not include any other child fields unless they are also selected explicitly. |\n | `advertisers/generalConfig/domainUrl` | Returns the `domainUrl` field for the `generalConfig` object, which itself is nested under the `advertisers` array. |\n\n Here are some resource-level examples:\n\n | Example | Effect |\n |---------------------------|-----------------------------------------------------------------------------------------|\n | `advertiserId` | Returns the `advertiserId` field of the requested resource. |\n | `generalConfig/domainUrl` | Returns the `domainUrl` field for the `generalConfig` object in the requested resource. |\n\nRequest only parts of specific fields using *sub-selections*.\n\n: By default, if your request specifies particular fields, the server returns\n the objects or array elements in their entirety. You can specify a response\n that includes only certain sub-fields. You do this using \"`( )`\"\n sub-selection syntax, as in the example below.\n\n | Example | Effect |\n |-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|\n | `advertisers(advertiserId,generalConfig/domainUrl)` | Returns only the values of `advertiserId` and generalConfig `domainUrl` for each element in the `advertisers` array. |\n\n##### Handling partial responses\n\nAfter a server processes a valid request that includes the `fields` query\nparameter, it sends back an HTTP `200 OK` status code, along with the requested\ndata. If the `fields` query parameter has an error or is otherwise invalid, the\nserver returns an HTTP `400 Bad Request` status code, along with an error\nmessage telling you what was wrong with the fields selection (for example,\n`\"Invalid field selection a/b\"`).\n| **Note:** For APIs that support query parameters for data pagination (`maxResults` and `nextPageToken`, for example), use those parameters to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with partial response might not be realized."]]
