搜索和 SearchStream

视频:报表

Google Ads API 具有统一的属性检索和指标报告机制,可让您使用 Google Ads 查询语言创建查询。这一解决方案支持能够返回大量关于各个 Google Ads 帐号的数据的复杂查询。

您可以使用 SearchSearchStream 方法创建查询。这两种方法支持相同的查询并返回等效的结果。Search 方法以可自定义的页面大小返回数据,让您可以使用分页功能遍历结果集。这在低带宽或不可靠的网络条件下尤为有利,例如,将较大的结果集分割为可在连接丢失时重新获取的较小响应。另一方面,SearchStream 方法会在单个响应中流式传输整个结果集,这对于批量数据检索更为高效。

SearchSearchStream 使用相同的基准网址:

    https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/googleAds

基于网页的搜索方法采用可选的 pageSize 参数,该参数会限制单个 API 响应中返回的结果数。

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

{
"pageSize": 10000,
"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'"
}

如果结果中的行数多于 pageSize,响应中会返回 nextPageToken

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

通过添加带有上述值的 pageToken 重复同一查询,即可获取下一页结果:

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

{
"pageSize": 10000,
"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 不需要 pageSizepageToken):

POST /v16/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'"
}