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'" }