Google Ads API には、統合された属性の取得と指標の報告メカニズムがあり、Google 広告クエリ言語を使用してクエリを作成できます。これにより、個々の Google 広告アカウントに関する大量のデータを返すことができる複雑なクエリが可能になります。
クエリは、Search メソッドまたは SearchStream メソッドのいずれかを使用して作成できます。どちらのメソッドも同じクエリをサポートし、同等の結果を返します。Search メソッドは、カスタマイズ可能なページサイズでデータを返すため、ページ分けを使用して結果セットを反復処理できます。これは、低帯域幅または信頼性の低いネットワーク条件下で有用である可能性があります。たとえば、大きな結果セットを小さなレスポンスに分割し、接続が失われた場合に再取得できるようにする場合などです。一方、SearchStream メソッドは結果セット全体を単一のレスポンスにストリーミングし戻します。この方法を使用すると、データの一括取得をより効率的に行うことができます。
Search と SearchStream はどちらも同じベース URL を使用します。
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/googleAds
ページベースの検索メソッドは、オプションの pageSize パラメータを受け取ります。このパラメータは、1 つの 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 メソッドを使用するには、URL のサービス メソッドを searchStream に変更します（pageSize と pageToken は SearchStream では必要ありません）。
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'"
}