提升性能

本文档介绍了您可以用来提高应用性能的一些技巧。在某些情况下，我们会使用其他已实现的 API 中的示例来说明所给出的提示。不过，同样的概念 同样适用于 Display & Video 360 API。

使用部分资源

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

部分响应

默认情况下，服务器在处理请求后会发回资源的完整表示形式。为了提高性能，您可以要求服务器仅发送您真正需要的字段，从而只接收部分响应。

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

示例

以下示例展示了如何将 fields 参数与 Display & 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 数组中每个元素的广告客户 ID 和网域网址。您也可以指定单个子字段，其中 fields=advertisers(advertiserId) 等同于 fields=advertisers/advertiserId。

使用 fields 参数的更多示例

以下示例包含有关 fields 参数值如何影响响应的说明。

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

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

下面提供了几个集合级别的示例：

示例 影响
advertisers 返回 advertisers 数组中的所有元素，包括每个元素中的所有字段，但不包括其他字段。
advertisers,nextPageToken 返回 nextPageToken 字段以及 advertisers 数组中的所有元素。
advertisers/advertiserId 仅返回 advertisers 数组中所有元素的 advertiserId。

每当返回嵌套字段时，响应都会包含所属父级对象。除非也明确选择，否则父字段不会包含任何其他子字段。
advertisers/generalConfig/domainUrl 返回 generalConfig 对象的 domainUrl 字段，该字段本身嵌套在 advertisers 数组下。

以下是一些资源级示例：

示例 影响
advertiserId 返回所请求资源的 advertiserId 字段。
generalConfig/domainUrl 返回所请求资源中 generalConfig 对象的 domainUrl 字段。
使用“子选择”仅请求特定字段的某些部分。

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

示例 影响
advertisers(advertiserId,generalConfig/domainUrl) 对于 advertisers 数组中的每个元素，仅返回 advertiserId 和 generalConfig domainUrl 的值。
处理部分响应

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