搜索和 SearchStream

视频:报告

Google Ads API 具有统一的属性检索和指标报告机制,可让您使用 Google Ads 查询语言创建查询。这样一来,您就可以执行复杂的查询,从而返回大量有关各个 Google Ads 账号的数据。

您可以使用 SearchSearchStream 方法创建查询。这两种方法支持相同的查询,并返回等效的结果。Search 方法以固定大小的页面(包含 10,000 行)返回数据,使您能够使用分页功能迭代结果集。在低带宽或不可靠的网络条件下,这可能很有优势,例如,将大型结果集分段为较小的响应,以便在连接丢失时重新提取。另一方面,SearchStream 方法会在单个响应中流式传输整个结果集,这对于批量数据检索可能更高效。

SearchSearchStream 都使用相同的基本网址:

    https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds
POST /v21/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}

如果结果中包含的行数超过 10,000,则响应中会返回 nextPageToken

{
  "results": [
    // ...
    // ...
    // ...
  ],
  "nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
  "fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}

重复执行同一查询,并添加 pageToken(其值为上一个请求中的值),即可提取下一页结果:

POST /v21/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'",
"pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"
}

如需使用 SearchStream 方法(该方法会在单个流式响应中返回所有结果),请将网址中的服务方法更改为 searchStreamSearchStream 不需要 pageToken):

POST /v21/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
    "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}