本文档介绍了您可以用来提高应用性能的一些技巧。在某些情况下,我们会使用其他已实现的 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
和 generalConfigdomainUrl
的值。
处理部分响应
服务器处理完包含 fields
查询参数的有效请求之后,会发回 HTTP 200 OK
状态代码以及所请求的数据。如果 fields
查询参数出现错误或因其他原因而无效,服务器会返回 HTTP 400 Bad Request
状态代码以及一条错误消息,告知您字段选择出现了什么问题(例如 "Invalid field selection a/b"
)。