クエリの構造

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

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

正しいデータを選択できるように、句ではフィールド名、リソース名、演算子、条件、並べ替えを使用できます。1 つのクエリに結合すると、Google Ads API を使用してリクエストを行うことができます。

句

以降のセクションでは、Google Ads Query Language の各句の目的と構文について説明します。

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 です。これらのセグメントのいずれかを選択した場合は、WHERE 句で少なくとも 1 つを使用する必要があります。

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

フィルタリングを行う際は、演算子の大文字と小文字の区別を考慮することが重要です。詳しくは、大文字と小文字の区別をご覧ください。

演算子の一覧については、言語の文法をご覧ください。

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

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

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

その他の言語ルール

各句の例に加えて、Google 広告クエリ言語には次の動作を利用できます。

• クエリの 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'