性能提示

本文档介绍一些您可以用来提高应用性能的方法。在某些情况下,我们会使用其他API或通用API中的示例来解释所给出的提示。不过,同样的概念也适用于AdSense Management API。

目录

  1. 使用GZip
  2. 使用部分资源
    1. 部分响应

使用GZip

要降低单个请求的带宽需求,您可以选择启用GZip压缩,这是一种既方便又简单的方法。虽然这种方法需要一些额外的CPU时间对结果进行解压缩,但考虑到它对节约网络费用的贡献,通常还是值得一用的。

要获得GZip编码的响应,您必须执行以下两项操作:设置Accept-Encoding标头,并修改您的用户代理以将字符串gzip包括在内。下面提供了一个用于启用GZip压缩的格式正确的HTTP标头示例:

Accept-Encoding: gzip
User-Agent: my program (gzip)

使用部分资源

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

部分响应

默认情况下,服务器在处理请求之后会发回资源的完整表示形式。为了提高性能,您可以要求服务器只发送您真正需要的字段,改为获取“部分响应”。

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

示例

以下示例显示的是将fields参数与通用(虚构的)“Demo”API结合使用的情况。

简单请求:下面的HTTP GET请求省略了fields参数,因而会返回完整资源。

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY

完整资源响应:完整资源数据包括以下字段(为了简便起见,此处省略了许多其他字段)。

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

部分响应请求:同样针对这项资源的以下请求使用了fields参数,大大减少了所返回的数据量。

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

部分响应:服务器为响应上述请求而发回的响应只包含类型信息和一个简化的items数组,该数组中的每个项目只包含HTML标题和长度特征信息。

200 OK

{
  "kind": "demo",
  "items": [
  {
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  },
  {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]

请注意,该响应是一个只包括所选字段及其所属父对象的JSON对象。

您可以在下面看到有关如何设置fields参数格式的详细信息,以及有关响应中会返回哪些确切内容的更多信息。

“fields”参数语法摘要

fields请求参数值的格式大致上基于XPath语法。支持的语法简述如下,另外下一节还将提供更多示例。

  • 使用以逗号分隔的列表来选择多个字段。
  • 使用a/b来选择嵌套在字段a中的字段b;使用a/b/c来选择嵌套在b中的字段c

    例外情况:在使用“data”包装程序的API响应中,即响应嵌套在data对象中(形如data: { ... }),则不要在fields规范内包含“data”。在fields规范中加入类似data/a/b的data对象会引发错误。所以,请使用a/b形式的fields规范。

  • 使用子选择器时,将表达式放在括号“( )”内可请求数组或对象的一组特定子字段。

    例如:fields=items(id,author/email)只会返回items数组中每个元素的项目ID和作者电子邮件。您也可以指定单个子字段,这种情况下fields=items(id)等同于fields=items/id

  • 如有需要,可在选择字段时使用通配符。

    例如:使用fields=items/pagemap/*可选择pagemap中的所有对象。

有关使用“fields”参数的更多示例

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

注意:与所有查询参数值一样,fields参数值也必须经过网址编码。为了便于阅读,本文档中的示例省略了编码。

确定您希望返回的字段,或者进行“字段选择”
fields请求参数值是一个以逗号分隔的字段列表,并且每个字段均是根据最终响应来指定。因此,如果您执行的是list操作,响应就是一个集合,其中通常包含一系列资源。如果您执行的是返回单一资源的操作,则字段是根据该资源来指定。如果您选择的字段是一个数组(或其一部分),服务器会返回数组中所有元素的选定部分。

下面提供了几个集合级的示例:
示例 效果
items 返回items数组中的所有元素,包括每个元素中的所有字段,但不包括其他字段。
etag,items 返回etag字段以及items数组中的所有元素。
items/title 仅返回items数组中所有元素的title字段。

每当返回嵌套字段时,响应中均包括该字段的父对象。父级字段不会包括其他任何子字段(除非已明确选择)。
context/facets/label 仅返回facets数组所有成员的label字段,而该数组本身嵌套在context对象下。
items/pagemap/*/title 对于items数组中的每个元素,仅返回pagemap的所有子对象的title字段(如果存在)。

下面提供了几个资源级的示例:
示例 效果
title 返回所请求资源的title字段。
author/uri 返回所请求资源中的author对象的uri子字段。
links/*/href
返回links的所有子对象的href字段。
使用“子选择”请求特定字段的某些部分
默认情况下,如果您的请求指定具体字段,则服务器会完整地返回对象或数组元素。您可以指定仅包含特定子字段的响应。如下所示,您可以使用“( )”子选择语法实现此目标。
示例 效果
items(title,author/uri) 仅返回items数组中每个元素的title值和作者uri

处理部分响应

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

以下是上文简介部分所提到的部分响应的示例。该请求使用fields参数来指定要返回的字段。

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

部分响应如下所示:

200 OK

{
  "kind": "demo",
  "items": [
  {
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  },
  {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]

注意:如果API支持用于数据分页的查询参数(例如maxResultsnextPageToken),请使用这些参数将每个查询的结果缩减为便于管理的大小。否则,可能无法实现本应通过部分响应获得的性能提升。

发送以下问题的反馈:

此网页
AdSense Management API
AdSense Management API