Google Ads API には、Google 広告クエリ言語を使用してクエリを作成できる、属性取得と指標レポートの統合メカニズムがあります。これにより、個々の Google 広告アカウントに関する大量のデータを返す複雑なクエリが可能になります。
クエリは、Search メソッドまたは SearchStream メソッドを使用して作成できます。どちらの方法でも同じクエリがサポートされ、同等の結果が返されます。Search メソッドは、10,000 行の固定サイズのページでデータを返します。これにより、ページネーションを使用して結果セットを反復処理できます。たとえば、帯域幅が狭いネットワークや信頼性の低いネットワークで、大きな結果セットを小さなレスポンスに分割し、接続が切断された場合に再取得できるようにする場合に、この方法が有効です。一方、SearchStream メソッドは、結果セット全体を 1 つのレスポンスでストリーミングします。これは、バルクデータの取得に効率的です。
Search と SearchStream はどちらも同じベース URL を使用します。
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 メソッド（すべての結果を 1 つのストリーミング レスポンスで返す）を使用するには、URL のサービス メソッドを searchStream に変更します（SearchStream では 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'" }