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

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

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

ページ分けされた複数のリクエストを送信して、レポート全体をダウンロードします。

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

使用するメソッドは、API の割り当てと上限に影響しません。結果がページングかストリーミングかにかかわらず、1 つのクエリまたはレポートは 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

リクエストを作成する

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

リクエストは、次のいずれかの URL にある Search Ads 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 句でリソースを使用している場合は、[Yes/No] プルダウンを使用して、使用できない指標を除外します。

リソースのセグメント化

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

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

選択可能な要素

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

segments ページには、segments フィールドごとに展開可能な「選択可能」があり、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

ゼロ指標

クエリを実行すると、一部のエンティティで値が 0 の指標が発生することがあります。クエリで指標がゼロの場合の処理方法を確認する。

UNKNOWN 列挙型

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

リソースのタイプが UNKNOWN の場合でも指標を選択できますが、次の点に注意してください。

  • UNKNOWN タイプのリソースは後でサポートされる可能性がありますが、無期限に UNKNOWN のままになる可能性があります。
  • UNKNOWN タイプの新しいオブジェクトはいつでも表示される可能性があります。これらのオブジェクトには列挙値がすでに利用できるため、下位互換性があります。この変更に関する情報は、利用可能になった時点で追加し、アカウントを正確に把握できるようにしています。UNKNOWN リソースは、他のインターフェースを通じてアカウントで新しいアクティビティが行われた場合や、リソースが正式にサポートが終了した場合に表示されることがあります。
  • UNKNOWN リソースには、クエリ可能な詳細な指標が添付されている場合があります。
  • UNKNOWN リソースは通常、検索広告 360 の管理画面にすべて表示されます。