クエリの構造

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

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

句では、フィールド名、リソース名、演算子、条件、並べ替えを使用して、正しいデータを選択します。1 つのクエリに結合すると、リクエストを Google 広告 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 つだけです。FROM 句は 必須 です。GoogleAdsServiceSearchSearchStreamただし、FROM 句を指定しないでください。 GoogleAdsFieldService

特定のクエリの 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
  • 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 広告クエリ言語では次の動作がサポートされています。

  • クエリの 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'
前へ
クエリ文法
次へ
期間