新しい 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.

クエリの構造と句

クエリは、SELECT、FROM、WHERE、ORDER BY、LIMIT、PARAMETERS の複数の句で構成されます。

句では、フィールド名、リソース名、演算子、条件、並べ替えを使用して、1 つのクエリリクエストに結合します。

簡単に言うと、クエリを作成するには次の操作を行います。

データを取得するリソースを指定します。
フィールドと指標を追加して、返すデータを定義します。
セグメントを追加して結果をグループ化します。
属性付きリソースを追加して、関連するリソースデータを暗黙的に結合します。
結果をフィルタリング、並べ替え、制限します。

`SELECT` 句

SELECT 句:

クエリの必須句です。
リクエストで取得するフィールドのセットを指定します。
リソースフィールド、カスタム列、カスタム Floodlight 変数、セグメントフィールド、指標のカンマ区切りのリストを取得し、レスポンスの値を返します。

このクエリの例は、campaign リソースの属性を選択する方法を示しています。

SELECT
  campaign.id,
  campaign.name
FROM campaign

複数のフィールドタイプ

同じリクエストで異なるフィールドタイプをリクエストできます。

次のクエリの例は、次の組み合わせを含む単一のクエリを示しています。

リソースフィールド: campaign.id、campaign.name、bidding_strategy.id、bidding_strategy.name。
セグメントフィールド: segments.device と segments.date。
指標フィールド: metrics.impressions と metrics.clicks。

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

検索レポートのセグメント化について詳しくは、セグメント化をご覧ください。

メインリソースフィールド

通常、メインリソースフィールドは SELECT 句に含めますが、これは省略可能です（必須ではありません）。

このクエリの例では、メインリソースフィールド（ad_group.status）を使用して結果のみをフィルタしています。

SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

カスタム Floodlight 変数

カスタム Floodlight 変数は、ID を使用して SELECT 句に含めることができます。

この例では、クエリにキャンペーンリソースの ID 123454321 のカスタム変数を含めています。

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

カスタム列

カスタム列の ID を使用して、SELECT 句にカスタム列を含めることができます。

この例では、クエリにキャンペーンリソースの ID 12345678 のカスタム列が含まれています。

SELECT
  custom_columns.id[12345678]
FROM campaign

カスタム列の ID を取得する方法をご覧ください。

指標フィールド

SELECT 句にリソースの他のフィールドを含めずに、特定のリソースの指標フィールドを選択できます。

このクエリ例では、campaign リソースの impressions 指標と clicks 指標を選択します。

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

クエリで使用できる指標フィールドの一覧については、metrics をご覧ください。

セグメントフィールド

SELECT 句で付随するリソースフィールドや指標を指定せずに、セグメントフィールドを選択できます。

このクエリ例では、結果をデバイス別にセグメント化しています。

SELECT segments.device
FROM campaign

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

禁止されているフィールド

SELECT 句では、次のフィールドを使用できません。

選択できないフィールド（Selectable メタデータ属性が false としてマークされているフィールド）。
繰り返しフィールド（Repeated メタデータ属性が true としてマークされているフィールド）。
FROM 句の特定のリソースで使用できないフィールド。一部のリソースの属性は同時に選択できません。一部のリソースでは、すべての指標とセグメントのサブセットのみが利用可能です。
互換性のないセグメントまたは指標。詳しくは、セグメンテーションをご覧ください。

各リソースのこの情報の確認方法については、リファレンスドキュメントをご覧ください。

FROM 句

FROM 句:

SearchAds360Service（Search メソッドと SearchStream メソッドの両方）に対するクエリの必須句です。
SearchAds360FieldService へのクエリに not を含めるべきではありません。
クエリが返すメインリソースを指定します。
指定できるリソースは 1 つだけです。
クエリの他のすべての句で使用できるフィールドを定義します。

帰属リソース

帰属リソースが使用可能な場合、FROM 句で指定したリソースと無条件に結合されます。値を返すには、属性を SELECT 句に追加するだけです。

このクエリ例では、campaign は ad_group リソースの属性付きリソースであるため、広告グループ ID とキャンペーン ID の両方が返されます。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

`resource_name` フィールド

FROM 句のメインリソースの resource_name フィールドが常に返されます。

このクエリの例では、クエリで明示的に選択されていないにもかかわらず、ad_group.resource_name がレスポンスに含まれます。

SELECT ad_group.id
FROM ad_group

少なくとも 1 つのフィールドが選択されている場合、帰属リソースの resource_name フィールドが返されます。

このクエリ例では、campaign.id が選択されているため、campaign.resource_name がレスポンスに含まれます。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE 句

WHERE 句:

クエリの省略可能な句です。
リクエストのデータをフィルタリングしてセグメント化するための条件を指定します。条件は FIELD_NAME OPERATOR VALUE というパターンに従います（空白で区切られます）。
AND セパレータで区切られた複数の条件を含めることができます。

このクエリの例は、WHERE 句を使用して、特定の期間の impressions 指標を返す方法を示しています。

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

検索レポートのセグメント化について詳しくは、セグメント化をご覧ください。

クエリで期間を指定する方法について詳しくは、期間をご覧ください。

`resource_name` フィールドでフィルタ

resource_name フィールドを使用して、データをフィルタしたり並べ替えたりできます。

このクエリの例では、campaign.resource_name フィールドを使用して、指定されたキャンペーンで結果をフィルタしています。

SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'

複数の条件

複数の条件を組み合わせてデータをフィルタできます。

このサンプルクエリでは、過去 30 日間にモバイルで impressions 指標が発生したすべてのキャンペーンの clicks 指標の数をリクエストしています。

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

レポートのセグメント化について詳しくは、セグメンテーションをご覧ください。

大文字と小文字の区別

文字列値でフィルタリングする場合、各演算子のデフォルトの大文字と小文字の区別は、結果を正しくフィルタリングするうえで重要な役割を果たします。

次の表に、各演算子のデフォルトの大文字と小文字の区別を示します。

デフォルトの大文字と小文字の区別
`=/!=`	`Case sensitive`
`IN/NOT IN`	`Case sensitive`
`LIKE/NOT LIKE`	`Case insensitive`
`CONTAINS (...)`	`Case sensitive`
`REGEXP_MATCH/NOT REGEXP_MATCH`	`Case sensitive`

(?i) 修飾子を使用すると、REGEXP_MATCH と NOT REGEXP_MATCH のデフォルトの感度を大文字と小文字を区別しないように変更できます。次に例を示します。

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

データをフィルタリングするために使用できる演算子の完全なリストについては、クエリ文法のリファレンスをご覧ください。

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

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

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

このクエリの例では、WHERE 句の segments.date フィールドに DURING LAST_30_DAYS を指定しています。

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

コア日付セグメントの使用について詳しくは、[セグメンテーション] > [コア日付セグメント] をご覧ください。

禁止されているフィルタリング

次のフィルタは許可されていません。

選択していないセグメントフィールド。中核となる日付セグメントは例外です。
メッセージタイプのフィールド。プリミティブ（Int64Value、StringValue など）は例外です。
プリミティブ（Int64Value、StringValue など）を除く、メッセージタイプの繰り返しフィールドの属性。

ORDER BY 句

ORDER BY 句:

クエリの省略可能な句です。
結果が返される順序を指定します。順序は FIELD_NAME ORDERING_OPTION（空白文字で区切る）のパターンに従います。
ASC（昇順）または DESC（降順）の 2 つのオプションを使用できます。デフォルトは昇順です。

次のサンプルクエリは、キャンペーンをクリック数で降順（多い順）に並べ替えます。

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

複数の順序付け

ORDER BY 句では、複数のフィールドをカンマで区切って指定できます。結果は、クエリで指定したのと同じ順序で並べ替えられます。

このクエリの例では、広告グループのデータを選択し、キャンペーン名で昇順、インプレッション数で降順、クリック数で降順に結果を並べ替えます。

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

並べ替えと制限を組み合わせる

ORDER BY 句と LIMIT 句を組み合わせて使用すると、結果を絞り込むことができます。

このサンプルクエリは、過去 30 日間で最もインプレッションが多い 5 つのキャンペーンを返します。

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

禁止されている注文

次の条件での並べ替えは許可されていません。

選択されていないリソースの属性別。
選択されていない指標別。
選択されていないセグメント別。
次のフィールドタイプの場合:
- MESSAGE
- 繰り返しフィールド
- 繰り返しフィールドの属性。

LIMIT 句

LIMIT 句:

クエリの省略可能な句です。
クエリが返す結果の数を制限できます。

この句は、たとえば、結果のサンプルや概要のみが必要な場合に便利です。

このクエリの例では、結果の総数を 50 に制限しています。

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

PARAMETERS 句

PARAMETERS 句を使用すると、リクエストのメタパラメータを指定できます。

下書きを含める

include_drafts パラメータは、下書きエンティティを結果に含めるかどうかを制御します。デフォルトは false です。ドラフトエンティティを含めるには、true に設定します。

このサンプルクエリは、下書き用キャンペーンと通常のキャンペーンの両方を返します。

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

選択されていない `resource_name` を省略

omit_unselected_resource_names パラメータを使用すると、SELECT 句で明示的にリクエストされていないすべてのリソースの resource_name フィールドを除外できます。デフォルト値は false です。このパラメータを true に設定する場合は、SELECT 句でプライマリリソースと関連付けられたリソースのリソース名を明示的にリクエストすることをおすすめします。

このクエリの例では、campaign.resource_name フィールドと customer.resource_name フィールドは SELECT 句に含まれていないため、どちらも返されません。

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

次のクエリ例では、SELECT 句で明示的にリクエストされているため、campaign.resource_name フィールドが返されます。

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

指標で使用する通貨を変更する

metrics_currency パラメータを使用すると、SELECT 句に含まれる指標の計算に使用する通貨を指定できます。デフォルトでは、customer_id で指定されたアカウントの通貨が使用されます。このパラメータを設定する場合は、ISO 4217 の 3 文字の通貨コードを使用する必要があります。例: USD、EUR。

このクエリ例では、customer_id で指定されたアカウントの通貨で cost_micros 指標が返されます。

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

このクエリの例では、cost_micros 指標がチリペソ（CLP）で返されます。

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

MCC の拡張を有効にする

enable_mcc_expansion パラメータを true に設定すると、FROM 句のリソースについて、customer_id をルートとするすべてのアカウントの指標、フィールド、セグメントを含めることができます。metrics_currency パラメータで明示的に指定されていない限り、レスポンスでは customer_id の通貨が使用されます。

このクエリ例では、enable_mcc_expansion パラメータが true に設定されているため、customer_id をルートとするアカウント階層内のすべてのアカウントから bidding_strategy.name、bidding_strategy.type、metrics.cost_micros が返されます。

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

詳細

クエリ文法