新しい Search Ads 360 Reporting API をご利用いただけるようになりました。Google グループ searchads-api-announcements に参加すると、今後の機能強化やリリースに関する最新情報を入手できます。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Search Ads 360 Reporting API で検索レポートを作成する

以下のセクションでは、Search Ads 360 Reporting API で検索レポートを作成する方法について説明します。

検索サービス

Search Ads 360 Reporting API は、検索とレポート作成のための特別なサービスを提供します。

SearchAds360Service は、SearchStream と Search の 2 つの検索メソッドを提供する、オブジェクト取得とレポートの統合サービスです。検索は、検索広告 360 クエリ言語で記述されたクエリ文字列で渡されます。クエリを定義して、次の操作を行うことができます。

オブジェクトの特定の属性を取得します。
期間に基づいてオブジェクトのパフォーマンス指標を取得します。
オブジェクトを属性に基づいて並べ替えます。
返すオブジェクトを指定する条件を使用して結果をフィルタする
返されるオブジェクトの数を制限します。

どちらの検索方法でも、クエリに一致するすべての行が返されます。たとえば、campaign.id、campaign.name、metrics.clicks を取得すると、API は id フィールドと name フィールドが設定されたキャンペーンオブジェクトと、clicks フィールドが設定された metrics オブジェクトを含む SearchAds360Row を返します。

検索方法

SearchStream

レポートのサイズに関係なく、単一のリクエストを送信して、検索広告 360 Reporting API との永続的な接続を開始します。

データパケットのダウンロードが直ちに開始され、結果全体がデータバッファにキャッシュ保存されます。
コードは、ストリーム全体が終了するのを待たずに、バッファリングされたデータの読み取りを開始できます。

Search

レポート全体をダウンロードするために、複数のページネーションリクエストを送信します。

SearchStream は、個々のページをリクエストするために必要なネットワークの往復時間を排除するため、通常はパフォーマンスが向上します。10,000 行を超えるすべてのレポートに SearchStream を使用することをおすすめします。行数が 10,000 未満の小規模なレポートでは、メソッド間のパフォーマンスに大きな違いはありません。

使用するメソッドは API の割り当てと上限に影響しません。結果がページングされるかストリーミングされるかにかかわらず、単一のクエリまたはレポートは 1 つのオペレーションとしてカウントされます。

検索クエリの例

このサンプルクエリは、過去 30 日間のアカウントのパフォーマンスデータをキャンペーン別に返し、デバイス別に分類します。

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

リクエストを作成する

リクエストを発行するには、SearchAds360Service.SearchStream または SearchAds360Service.Search インターフェースに customer_id と query の文字列を渡す必要があります。

リクエストは、次のいずれかの URL にある検索広告 360 Reporting API サーバーへの HTTP POST で構成されています。

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

以下に、HTTP POST リクエストに格納される searchStream のレポート定義のサンプルコードの全文を示します。

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

レスポンスを処理する

SearchAds360Service は、SearchAds360Row オブジェクトのリストを返します。

各 SearchAds360Row は、クエリによって返されたオブジェクトを表します。各オブジェクトは、クエリの SELECT 句でリクエストされたフィールドに基づいて入力される一連の属性で構成されます。SELECT 句に含まれていない属性は、レスポンスのオブジェクトに設定されません。

たとえば、次のクエリは、各 SearchAds360Row オブジェクトに campaign.id、campaign.name、campaign.status のみを入力します。campaign.engine_id や campaign.bidding_strategy_type などの他の属性は省略されています。

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

リファレンスドキュメント

リファレンスセクションには、各アーティファクトを正しく使用するために必要なすべての情報が含まれています。リソースごとに 1 つのページがあります（ad_group、campaign など）。segments ページと metrics ページには、利用可能なすべてのセグメントと指標フィールドが一覧表示されます。

一部のリソース、セグメント、指標は互換性がなく、一緒に使用できません。一方、完全に互換性があり、相互に補完し合うものもあります。各リソースページには、次の情報（利用可能で適切な場合）などが含まれています。

帰属リソース

一部のリソースでは、FROM 句でリソースのフィールドとともにフィールドを選択することで、関連リソースを暗黙的に結合できます。たとえば、campaign リソースは ad_group リソースの属性付きリソースです。つまり、FROM 句で ad_group を使用する場合は、クエリに campaign.id や campaign.bidding_strategy_type などのフィールドを含めることができます。

[帰属リソース] セクションには、利用可能な帰属リソースが一覧表示されます。一部のリソースにはアトリビュートリソースがありません。

[リソースフィールド] 列

リソースのすべてのフィールドが [リソースフィールド] 列に含まれます。各リソースフィールドは、フィールドの説明、カテゴリ、データ型、タイプ URL、フィルタ可能、選択可能、並べ替え可能、繰り返し設定など、フィールドの詳細にリンクしています。

[セグメント] 列

特定のリソースで選択できるセグメントフィールドはすべてではありません。

[セグメント] 列には、リソースのフィールドと同じ SELECT 句で使用できる segments フィールドが一覧表示されます。各フィールドは、説明、カテゴリ、データ型、型 URL、フィルタ可能、選択可能、並べ替え可能、繰り返し設定など、フィールドの詳細情報にリンクしています。FROM 句でリソースを使用している場合は、[はい/いいえ] プルダウンを使用して、使用できないセグメントを除外できます。

指標列

特定の指標フィールドが、特定のリソースで選択できるとは限りません。

[指標] 列には、リソースのフィールドと同じ SELECT 句で使用できる metrics フィールドが一覧表示されます。各フィールドは、説明、カテゴリ、データ型、型 URL、フィルタ可能、選択可能、並べ替え可能、繰り返し設定など、フィールドの詳細情報にリンクしています。FROM 句でリソースを使用している場合は、[はい/いいえ] プルダウンを使用して、使用できない指標を除外します。

リソースのセグメント化

一部のリソースには、リソースが FROM 句にある場合に選択できるセグメント化リソースフィールドがあります。たとえば、FROM 句で campaign_budget を使用する場合に、campaign.name などの campaign リソースフィールドを選択すると、campaign.resource_name が自動的に返され、セグメント化されます。これは、campaign が campaign_budget のセグメント化リソースであるためです。

[リソースのセグメント化] セクションには、使用可能なセグメント化リソースが一覧表示されます。すべてのリソースにセグメント化リソースがあるわけではありません。

選択可能

一部の segments フィールドは、他のリソース、セグメント、指標と互換性がありません。

segments ページには、各 segments フィールドの [Selectable with] 展開可能リストが含まれています。このリストには、SELECT 句に含めることができる互換性のあるすべてのリソースフィールド、metrics フィールド、その他の segments フィールドが一覧表示されます。

セグメンテーション

検索結果をセグメント化するには、クエリの SELECT 句に segments.FIELD_NAME フィールドを追加します。

たとえば、次のクエリの segments.device は、FROM 句で指定されたリソースの各デバイスの impressions の行を含むレポートを生成します。

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

SearchAds360Service.SearchStream から返される結果は、次のような JSON 文字列になります。

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

使用できるセグメントフィールドの一覧については、segments をご覧ください。

複数のセグメント

クエリの SELECT 句で複数のセグメントを指定できます。レスポンスには、FROM 句で指定されたメインリソースのインスタンスと、選択された各 segment フィールドの値の組み合わせごとに 1 つの SearchAds360Row オブジェクトが含まれます。

たとえば、次のクエリは campaign、segments.ad_network_type、segments.date の組み合わせごとに 1 つの行を返します。

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

結果は、選択された個々のフィールドの値ではなく、メインリソースの各インスタンスごとに無条件にセグメント化されます。

次のクエリの例では、campaign.status フィールドの個別の値ごとに 1 行ではなく、キャンペーンごとに 1 行になります。

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

暗黙的セグメント分割

すべてのレポートは、最初に FROM 句で指定されたリソースでセグメント化されます。指標は、このリソースの resource_name フィールドでセグメント化されます

このクエリ例では、ad_group.resource_name が自動的に返され、暗黙的に使用されて ad_group レベルで指標がセグメント化されます。

SELECT metrics.impressions
FROM ad_group

返される JSON 文字列は次のようになります。

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

中核となる日付セグメント

WHERE 句でコア日付セグメントを使用して、日付または期間を指定できます。

次のセグメントフィールドは、コア日付セグメントと呼ばれます。segments.date、segments.week、segments.month、segments.quarter、segments.year。

このサンプルクエリは、過去 30 日間のキャンペーンのclicks指標を返します。

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

コア日付セグメントフィールドは、SELECT 句にもフィールドを含めない限り、WHERE 句でセグメントフィールドを使用できないという一般的なルールの例外です。詳細については、禁止されているフィルタリングをご覧ください。

中核となる日付セグメントのルール:

SELECT 句に含めずに、WHERE 句でコア日付フィールドを使用できます。必要に応じて、両方の句にフィールドを含めることもできます。

このクエリの例では、指定した期間のキャンペーン名別に clicks 指標を返します。segments.date は SELECT 句に含まれていません。
```
SELECT
    campaign.name,
    metrics.clicks
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'
```
SELECT 句にコア日付フィールドを含める場合は、WHERE 句で有限の日付または期間を指定する必要があります。SELECT 句と WHERE 句で指定されたフィールドは一致している必要はありません。

このクエリの例では、期間内のすべての日について、キャンペーン名別の clicks 指標が月別に分類されて返されます。
```
SELECT
  campaign.name,
  metrics.clicks,
  segments.month
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'
```

ISO 8601 の日付

YYYY-MM-DD（ISO 8601）形式を使用して、日付と日付の範囲を指定できます。例:

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

期間を必要とするコア日付セグメント（segments.week、segments.month、segments.quarter）では、期間の初日とともに = 演算子を使用できます。例:

WHERE segments.month = '2022-06-01'

事前定義された日付

次の事前定義された日付と期間を使用することもできます。

事前定義された日付
`TODAY`	本日のみ。
`YESTERDAY`	昨日のみ。
`LAST_7_DAYS`	過去 7 日間（本日を除く）。
`LAST_BUSINESS_WEEK`	前の 5 営業日（月曜日～金曜日）。
`THIS_MONTH`	今月のすべての日。
`LAST_MONTH`	先月のすべての日。
`LAST_14_DAYS`	過去 14 日間（本日を除く）。
`LAST_30_DAYS`	今日を除く過去 30 日間。
`THIS_WEEK_SUN_TODAY`	前の日曜日から今日までの期間
`THIS_WEEK_MON_TODAY`	前の月曜日から今日までの期間
`LAST_WEEK_SUN_SAT`	前の日曜日から始まる 7 日間。
`LAST_WEEK_MON_SUN`	前の月曜日から始まる 7 日間。

例:

WHERE segments.date DURING LAST_30_DAYS

ゼロ指標

クエリを実行すると、一部のエンティティで値がゼロの指標が取得されることがあります。クエリでゼロの指標を処理する方法について学習します。

UNKNOWN 列挙型

UNKNOWN 列挙型データ型でリソースが返された場合、その型は API バージョンで完全にサポートされていないことを意味します。これらのリソースは、他のインターフェースで作成された可能性があります。たとえば、検索広告 360 の UI で新しいキャンペーンや広告が導入されたものの、クエリを実行している API バージョンではまだサポートされていない場合などです。

リソースのタイプが UNKNOWN の場合でも指標を選択できますが、次の点に注意する必要があります。

UNKNOWN タイプのリソースは後でサポートされる可能性がありますが、無期限に UNKNOWN のままになる可能性もあります。
型 UNKNOWN の新しいオブジェクトはいつでも表示される可能性があります。列挙型の値はすでに使用可能であるため、これらのオブジェクトには下位互換性があります。この変更に伴い、アカウントを正確に把握できるように、リソースが利用可能になった時点でリソースを導入します。UNKNOWN リソースが表示されるのは、他のインターフェースを通じてアカウントで新しいアクティビティが発生したか、リソースが正式にサポートされなくなったためです。
UNKNOWN リソースには、クエリ可能な詳細な指標が関連付けられている場合があります。
通常、UNKNOWN リソースは検索広告 360 の管理画面に完全に表示されます。