新しい Search Ads 360 Reporting API をご利用いただけるようになりました。Google グループ searchads-api-announcements に参加すると、今後の機能強化やリリースに関する最新情報を入手できます。

このページは Cloud Translation API によって翻訳されました。

クエリの構造と句

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

句では、フィールド名、リソース名、演算子、条件、並べ替えを使用して、単一のクエリリクエストを作成します。

クエリを作成するには、次の手順を行います。

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

`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 へのクエリには含めないでください。
クエリが返すメインリソースを指定します。
指定できるリソースは 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 句に含まれる指標の計算に使用する通貨を指定できます。デフォルトでは、アカウントの現地通貨が使用されます。このパラメータを設定する場合は、ISO 4217 の 3 文字の通貨コードを使用する必要があります。例: USD、EUR。

このサンプルクエリは、アカウントの現地通貨で 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"

その他の情報

クエリ文法