クエリの構造

リソース、セグメント、指標の各フィールドのクエリは、GoogleAdsService の Search メソッドまたは SearchStream メソッドに送信できます。Google 広告クエリ言語でクエリを作成するには、言語の文法を使用します。Google 広告クエリ言語の概要については、Google 広告クエリ言語の概要をご覧ください。クエリは、次のような複数の句で構成されます。

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

句では、フィールド名、リソース名、演算子、条件、順序を使用して、正しいデータを選択できます。1 つのクエリに結合すると、Google Ads API にリクエストを送信できます。

句

以下のセクションでは、Google 広告クエリ言語の各句の目的と構文について説明します。

SELECT

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

次のサンプルクエリは、特定のリソースの属性を選択する例を示しています。

SELECT
  campaign.id,
  campaign.name
FROM campaign

1 つのリクエストで、次のような異なるフィールド タイプをリクエストできます。

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
  • メインのリソース フィールド
    • campaign.id
    • campaign.name
  • 属性リソース フィールド
    • bidding_strategy.id
    • bidding_strategy.name
  • 区画の分割
    • segments.device
    • segments.date
  • 指標
    • metrics.impressions
    • metrics.clicks
  • 選択できないフィールドをクエリしている。これらのフィールドには、selectable メタデータ属性が false としてマークされています。
  • 繰り返しフィールドの属性を選択する場合。これらのフィールドには、is_repeated メタデータ属性が true としてマークされています。
  • FROM 句で、指定されたリソースで使用できないフィールドを選択している。一部のリソースの属性は同時に選択できません。また、FROM 句のリソースで使用できるのは、すべての指標とセグメントのサブセットのみです。
  • 互換性のないセグメントまたは指標を選択している。詳細については、セグメンテーションをご覧ください。

上記の条件に関連する情報は、リファレンス ドキュメントまたは GoogleAdsFieldService で確認できます。

FROM

FROM 句は、返すメインリソースを指定します。FROM 句のリソースは、指定されたクエリの他のすべての句で使用できるフィールドを定義します。FROM 句で指定できるリソースは 1 つだけです。GoogleAdsService Search または SearchStream メソッドへのクエリでは、FROM 句が必須です。ただし、GoogleAdsFieldService を使用する場合は、FROM 句を指定しないでください。

特定のクエリの FROM 句に存在できるリソースは 1 つだけですが、属性付きリソースのフィールドも使用できます。これらのリソースは FROM 句のリソースと暗黙的に結合されるため、値を返すには、その属性を SELECT 句に追加するだけで済みます。すべてのリソースに属性リソースがあるわけではありません。次の例では、広告グループから広告グループ ID とキャンペーン ID の両方をリクエストできます。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

メインリソースの resource_name フィールドは常に返されます。次の例では、クエリで明示的に選択されていないにもかかわらず、ad_group.resource_name がレスポンスに含まれています。

SELECT ad_group.id
FROM ad_group

少なくとも 1 つのフィールドが選択されている場合、属性リソースについても同様です。たとえば、次のクエリのレスポンスには campaign.resource_name が含まれています。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

WHERE 句は、リクエストのデータをフィルタリングするときに適用する条件を指定します。WHERE 句を使用する場合は、AND で区切って 1 つ以上の条件を指定します。条件は通常、field_name Operator value のパターンに従います（または BETWEEN value AND value、IS NULL、IS NOT NULL を使用します）。WHERE 句はクエリでは省略可能です。

次の例では、WHERE を使用して、特定の期間の指標を返します。

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

複数の条件を組み合わせてデータをフィルタできます。この例では、過去 30 日間にモバイルでインプレッションが発生したすべてのキャンペーンのクリック数をリクエストします。

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

WHERE 句のセグメントは、SELECT 句にも含まれている必要があります。ただし、コア日付セグメントと呼ばれる次の日付セグメントは例外です。

  • segments.date
  • segments.week
  • segments.month
  • segments.quarter
  • segments.year

次のクエリでは、segments.date が選択されています。このセグメントはコア日付セグメントであるため、コア日付セグメントで構成される WHERE 句に有限の期間を指定する必要があります。

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

上記の条件を満たすセグメントは、segments.date、segments.week、segments.month、segments.quarter、segments.year です。これらのセグメントのいずれかが選択されている場合は、そのうちの少なくとも 1 つを WHERE 句で使用する必要があります。

日付フィルタリングの詳細については、期間をご覧ください。

フィルタリングを行う際は、演算子の大文字と小文字の区別に注意してください。詳細については、大文字と小文字の区別をご覧ください。

演算子の完全なリストについては、言語の文法をご覧ください。

ORDER BY

ORDER BY 句は、結果が返される順序を指定します。これにより、フィールド名に基づいてデータを昇順または降順で並べ替えることができます。各順序は、field_name の後に ASC または DESC を指定します。ASC と DESC のどちらも指定されていない場合、デフォルトの順序は ASC です。ORDER BY 句はクエリで省略可能です。

次のクエリは、返されたキャンペーンをクリック数の多い順に並べ替えます。

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

LIMIT

LIMIT 句を使用すると、返す結果の数を指定できます。これは、結果のサブセットのみが必要な場合に便利です。

たとえば、LIMIT を使用すると、次のクエリの結果の合計数を制限できます。

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

PARAMETERS

PARAMETERS 句を使用すると、リクエストのメタ パラメータを指定できます。これらのパラメータは、返される行の種類に影響する可能性があります。

次のメタ パラメータがサポートされています。

include_drafts

include_drafts を true に設定して、ドラフト エンティティを返します。デフォルト値は false です。

たとえば、次のクエリは、通常のキャンペーンとともに下書きキャンペーンを取得します。

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts = true

omit_unselected_resource_names

omit_unselected_resource_names を true に設定すると、SELECT 句で明示的にリクエストされない限り、レスポンス内の各リソースタイプのリソース名が省略されます。デフォルトは false です。

クエリ 返されたリソース 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • campaign.resource_name
  • customer.resource_name

omit_unselected_resource_names のデフォルトは false であるため、すべての resource_name フィールドが返されます。

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

なし

omit_unselected_resource_names が true として指定され、campaign.resource_name と customer.resource_name のどちらも SELECT 句の一部ではありません。

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

omit_unselected_resource_names が true として指定され、campaign.resource_name が SELECT 句の一部としてリクエストされている。

その他の言語ルール

各句の例に加えて、Google 広告 Query Language では次の動作がサポートされています。

  • クエリの SELECT 句では、メインのリソース フィールドは必須ではありません。たとえば、1 つ以上のメインリソース フィールドを使用して、データを選択せずにフィルタできます。

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

  • メトリックは特定のリソースに対して排他的に選択できます。リソース内の他のフィールドはクエリに必要ありません。

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign

  • セグメント フィールドは、付随するリソース フィールドや指標なしで選択できます。

    SELECT segments.device FROM campaign

  • resource_name フィールド（campaign.resource_name など）は、データのフィルタリングや並べ替えに使用できます。

    SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
前へ
クエリ文法
次へ
期間