提升性能

本文档介绍了一些技巧，可以帮助您提高部署应用在某些情况下，会使用其他已实现的 API 中的示例来阐释所提出的观点不过，其中的概念同样适用于添加到展示广告和Video 360 API。

使用部分资源

提高 API 调用性能的另一种方法是您感兴趣的那部分数据。这样，您的应用避免传输、解析和存储不需要的字段，网络、CPU 和内存等资源。

部分响应

默认情况下，在发生以下事件后，服务器会发回处理请求为了获得更好的性能，您可以要求服务器将只会返回您真正需要的字段，从而只会得到部分响应。

如需请求部分响应，请使用 fields 请求参数来指定您想要返回的字段。您可以在任何请求中使用此参数返回响应数据的。

示例

以下示例展示了如何将 fields 参数与展示广告与Video 360 API。

简单请求：此 HTTP GET 请求省略了 fields 参数和返回完整资源。

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1

完整资源响应：完整资源数据包括以下内容字段，以及为简洁起见而省略的许多其他字段。

200 OK

{
 "advertisers": [
  {
   "name": "advertisers/1",
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  {
   "name": "advertisers/2",
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  ...
 ],
 "nextPageToken": "..."
}

部分响应请求：同一资源的以下请求使用 fields 参数显著减少返回的数据量。

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)

部分响应：为响应上述请求，服务器会发回包含经过简化的 advertiser 数组（该数组中仅包含每个广告客户的广告客户 ID、显示名称和合作伙伴 ID 属性（如果存在。

200 OK

{
 "advertisers": [
  {
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1"
  },
  {
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2"
  },
  ...
 ]
}

请注意，该响应是一个仅包含所选字段的 JSON 对象及其所属的父对象。

接下来会详细介绍如何设置 fields 参数的格式，然后是详细了解响应中具体返回了什么内容。

“fields”参数语法摘要

fields 请求参数值的格式大体上基于 XPath 语法。受支持的语法总结如下，其他示例如下：。

使用以逗号分隔的列表来选择多个字段。
使用 a/b 选择嵌套在字段 a 内的字段 b；使用a/b/c 选择嵌套在 b 内的字段 c。
使用子选择器请求数组的一组特定子字段，或者将表达式放在括号“( )”中来实现。

例如：fields=advertisers(advertiserId,generalConfig/domainUrl) 仅返回 advertiser 数组。您也可以指定单个子字段，其中 fields=advertisers(advertiserId) 相当于 fields=advertisers/advertiserId。

使用 fields 参数的更多示例

下面的示例说明了 fields 参数值如何影响响应。

确定您希望返回的字段，或者进行字段选择。

fields 请求参数值是一个以英文逗号分隔的字段列表，以及每个字段均相对于响应的根来指定。因此，如果您执行 list 操作时，响应是一个集合，并且它通常包含一系列资源如果您要执行一项操作返回单个资源的字段，那么指定字段时会相对于该资源资源。如果您选择的字段是（或属于）数组，则服务器返回数组中所有元素的选定部分。

以下是一些集合级别的示例：

示例	效果
`advertisers`	返回 `advertisers` 数组，包括每个元素中的所有字段没有其他字段
`advertisers,nextPageToken`	返回 `nextPageToken` 字段和 `advertisers` 数组。
`advertisers/advertiserId`	仅返回 `advertiserId` 所有元素的 `advertisers` 数组。每当嵌套字段响应包括所属的父对象。父字段不包括子字段，除非它们也被选中。
`advertisers/generalConfig/domainUrl`	返回 `domainUrl` 字段对于 `generalConfig` 对象，它本身嵌套在 `advertisers` 数组。

以下是一些资源级别的示例：

示例	效果
`advertiserId`	返回 `advertiserId` 字段所请求资源的状态
`generalConfig/domainUrl`	返回 `domainUrl` 字段对于 `generalConfig` 对象请求的资源

使用“子选择”仅请求特定字段的某些部分。

默认情况下，如果您的请求指定特定字段，则服务器会返回整个对象或数组元素。您可以指定响应仅包含某些子字段为此，您可以使用“( )” 子选择语法，如下例所示。

示例	效果
`advertisers(advertiserId,generalConfig/domainUrl)`	仅返回值 `advertiserId` 和 generalConfig `domainUrl`：每个元素 `advertisers` 数组。

处理部分响应

服务器处理完包含 fields 查询的有效请求后参数，它会发回 HTTP 200 OK 状态代码以及请求的数据。如果 fields 查询参数存在错误或因其他原因而无效，服务器将返回 HTTP 400 Bad Request 状态代码，以及一个错误消息，告知您字段选择出现了什么问题（例如， "Invalid field selection a/b"）。