Google Ads API 具有统一的属性检索和指标报告机制,让您可以使用 Google Ads 查询语言创建查询。这支持可返回大量 Google Ads 帐号相关数据的复杂查询。
您可以使用 Search
或 SearchStream
方法创建查询。这两种方法支持相同的查询并返回等效的结果。Search
方法可按可自定义的页面大小返回数据,让您能够使用分页功能遍历结果集。这在低带宽或不可靠的网络条件下非常有利,例如,将大型结果集细分为较小的响应(在连接丢失时可以重新获取)。另一方面,SearchStream
方法会在单个响应中流式传输整个结果集,这对于批量数据检索更为高效。
Search
和 SearchStream
使用相同的基础网址:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/googleAds
基于网页的搜索方法采用可选的 pageSize
参数,该参数会限制单个 API 响应中返回的结果数量。
POST /v17/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 /v17/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
方法(在单个流式响应中返回所有结果),只需将网址中的服务方法更改为 searchStream
(SearchStream
不需要 pageSize
和 pageToken
):
POST /v17/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'" }