検索と SearchStream

検索広告 360 Reporting API には、検索広告 360 クエリ言語を使用してクエリを作成できる、統合された属性取得と指標レポートのメカニズムがあります。これにより、個々の検索広告 360 アカウントに関する大量のデータを返す複雑なクエリが可能になります。

クエリは、Search メソッドまたは SearchStream メソッドを使用して作成できます。どちらの方法でも同じクエリがサポートされ、同等の結果が返されます。Search メソッドは、カスタマイズ可能なページサイズのデータを返します。これにより、ページネーションを使用して結果セットを反復処理できます。たとえば、帯域幅が狭いネットワークや信頼性の低いネットワークの状況で、大きな結果セットを小さなレスポンスに分割し、接続が切断された場合に再取得できるようにする場合に、この方法が有効です。一方、SearchStream メソッドは、結果セット全体を 1 つのレスポンスでストリーミングします。これは、バルクデータの取得に効率的です。

Search と SearchStream はどちらも同じベース URL を使用します。

    https://searchAds360.googleapis.com/v0/customers/CUSTOMER_ID/searchAds360

ページベースの検索メソッドは、1 つの API レスポンスで返される結果の数を制限するオプションの pageSize パラメータを受け取ります。

POST /v0/customers/CUSTOMER_ID/searchAds360:search HTTP/1.1
Host: searchAds360.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_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 /v0/customers/CUSTOMER_ID/searchAds360:search HTTP/1.1
Host: searchads360.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_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 メソッド（すべての結果を 1 つのストリーミング レスポンスで返す）を使用するには、URL のサービス メソッドを searchStream に変更します（pageSize と pageToken は SearchStream では必要ありません）。

POST /v0/customers/CUSTOMER_ID/searchAds360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_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'"
}