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 の管理画面にすべて表示されます。