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

検索広告で検索レポートを作成する方法については、以下のセクションをご覧ください。 360 Reporting API

検索サービス

Search Ads 360 Reporting API は、検索広告 360 内でキャンペーンや レポート

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

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

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

検索方法

SearchStream

単一のリクエストを送信して永続的な接続を開始する Search Ads 360 Reporting API と併用できます。

  • 結果とともにデータパケットのダウンロードがすぐに開始されます データ バッファに格納されます。
  • バッファ内のデータの読み取りをコードで開始できます。 最後まで配信する必要があります。
Search

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

SearchStream を使用すると、次のような問題が発生するため、通常、パフォーマンスが向上します。 各ページのリクエストに必要なネットワークのラウンドトリップ時間です。Google Cloud コンソールの 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

リクエストを作成する

リクエストを発行するには、customer_id と query の文字列を渡す必要があります。 SearchAds360Service.SearchStream または SearchAds360Service.Search まで 行うことができます。

リクエストは、Search Ads 360 Reporting API への HTTP POST で構成されます。 次のいずれかの URL にアクセスしてください。

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

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

searchStream へのレポート定義の完全な例は、 HTTP POST リクエスト:

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

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

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

一部のリソース、セグメント、指標に互換性がないため、使用できません 完全な互換性があり互いに補完し合うものもあれば、各 リソースページには、次の情報が表示されます。 など）が含まれます。

関連付けられたリソース

リソースによっては、関連するフィールドを暗黙的に結合するオプションが そのリソースのフィールドとともに選択することで、 FROM 句を使用します。たとえば、campaign リソースは、 ad_group リソースの属性済みリソース。つまり campaign.id や campaign.bidding_strategy_type などのフィールドを （FROM 句で ad_group を使用する場合）

[貢献度の割り当てられたリソース] セクションには、利用可能なリソースの一覧が表示されます。× 割り当てられているリソースがあります。

リソース フィールド列

リソースのすべてのフィールドが [リソース フィールド] 列に含まれます。 各リソース フィールドは、そのフィールドの詳細情報（ description、category、data type、type URL、および filterable、selectable、 繰り返し設定が可能です。

セグメント列

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

[セグメント] 列には、segments リソースのフィールドと同じ SELECT 句を使用します。各フィールドのリンク先は フィールドの詳細（説明、カテゴリ、データ型、型など） URL、フィルタ可能、選択可能、並べ替え可能、反復的な設定です。もし FROM 句でリソースを使用する場合、Yes/No プルダウンを使用できます。 利用できないセグメントを除外できます

指標列

特定のリソースですべての指標フィールドを選択できるわけではありません。

[Metrics] 列には、metrics リソースのフィールドと同じ SELECT 句を使用します。各フィールドのリンク先は フィールドの詳細（説明、カテゴリ、データ型、型など） URL、フィルタ可能、選択可能、並べ替え可能、反復的な設定です。もし FROM 句でリソースを使用する場合は、[Yes/No] プルダウンを使用して、 使用できない指標を除外できます。

で確認できます。
リソースのセグメント化

一部のリソースでは、リソース フィールドをセグメント化して、 リソースが FROM 句に含まれている。たとえば、次のような campaign リソース フィールドを選択した場合、 campaign.name、日時 FROM 句で campaign_budget を使用する（campaign.resource_name） 自動的に返され、セグメント化されます。これは、campaign が campaign_budget のセグメント化リソース。

[セグメンテーション リソース] セクションには、利用可能なセグメント リソースが一覧表示されます。× リソースはすべてセグメント化リソースを持ちます。

以下で選択可能:

一部の segments フィールドが、他のリソース、セグメント、 できます。

segments ページ 各 segments フィールドの Selectable with 展開式フィールドがあり、 互換性のあるすべてのリソース フィールド、metrics フィールド、その他の segments がリストされます。 SELECT 句に含めることができるフィールド群です。

で確認できます。

セグメンテーション

カスタム ディメンションを追加して検索結果を分類するには、 segments.FIELD_NAME フィールドをクエリの SELECT 句に追加します。

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

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

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

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

結果は、暗黙的にメインのインスタンス（インスタンス）ごとに分割されます。 選択した各フィールドの値では使用されません。

次のクエリ例では、キャンペーンごとに 1 行ではなく 1 行が表示される campaign.status フィールドの個別の値。

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

コア日付セグメント フィールドは、ここで設定する一般的なルールの例外です。 WHERE 句でセグメント フィールドを使用することはできません。ただし、 SELECT 句に追加します。詳細については、禁止されているフィルタリングをご覧ください。 情報です。

日付区分の基本ルール:

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

    このクエリ例では、期間中にキャンペーン名ごとに 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 タイプの新しいオブジェクトはいつでも表示される可能性があります。これらのオブジェクトは、 下位互換性があります。列挙値はすでに利用できるからです。Google の この変更によるリソースが利用可能になれば、正確な 確認できます。UNKNOWN リソースは、 他のインターフェースを介して、またはリソースの サポートされなくなります。
  • UNKNOWN 個のリソースに詳細な指標が関連付けられている場合があります。 なります。
  • 通常、UNKNOWN リソースは検索広告 360 の UI に完全に表示されます。