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 を取得すると、id フィールドと name フィールドが設定されたキャンペーン オブジェクトと、clicks フィールドが設定された metrics オブジェクトを含む SearchAds360Row が返されます。

検索方法

SearchStream

レポートのサイズに関係なく、1 つのリクエストを送信し、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 にある検索広告 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 句でリソースを使用している場合は、[Yes/No] プルダウンを使用して、使用できないセグメントを除外できます。

指標列

特定のリソースで選択できる指標フィールドは限られています。

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

リソースのセグメンテーション

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

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

選択可能な項目

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

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

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