クエリの構造

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

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

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

キーポイント: GoogleAdsFieldService は、Google 広告クエリ言語クライアントのカタログに、すべてのリソース フィールド、セグメント フィールド、指標に関するメタデータに加え、以下に定義する各句の相互関係や可用性についての情報を提供します。詳細については、GoogleAdsField のドキュメントをご覧ください。

句

動画: GAQL フィールドの互換性

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

次の制限により、一部のフィールドは SELECT 句で使用できない場合があります。

• 選択できないフィールドをクエリする場合。これらのフィールドの Selectable メタデータ属性は false としてマークされます。
• 繰り返しフィールドの属性を選択する場合。これらのフィールドの isRepeated メタデータ属性は true としてマークされます。
• FROM 句で特定のリソースで使用できないフィールドを選択する。一部のリソースの属性は一緒に選択できません。また、FROM 句のリソースでは、すべての指標とセグメントのサブセットのみを使用できます。
• 互換性のないセグメントまたは指標を選択している。詳細については、セグメンテーションのセクションをご覧ください。

上記の条件に関する情報については、リファレンス ドキュメントまたは GoogleAdsFieldService をご覧ください。

FROM

FROM 句は、返されるメインリソースを指定します。FROM 句のリソースは、指定されたクエリの他のすべての句で使用できるフィールドを定義します。FROM 句に指定できるリソースは 1 つだけです。GoogleAdsService の Search メソッドまたは SearchStream メソッドに対するクエリでは 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

キーポイント: FROM 句のリソースに別のリソースが segment としてリストされている場合、そのリソースの属性を選択すると、セグメントとして機能します。

WHERE

WHERE 句は、リクエストのデータをフィルタするときに適用する条件を指定します。WHERE 句を使用する場合、1 つ以上の条件を AND で区切って指定することができます。各条件は、field_name Operator value のパターンに従う必要があります。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 句で使用する必要があります。

キーポイント: 区切り文字 AND は演算子条件（WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"）の間でのみ使用できます。単一の演算子条件（WHERE segments.device != "DESKTOP" AND "MOBILE"）内では使用できません。

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

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

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

キーポイント: LIMIT を使用すると、結果を切り捨てることができます。長い結果リストを処理するには、GoogleAdsService.Search の page_size フィールドを使用します。

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 です。

注: 返されたオブジェクトを更新オペレーションまたは削除オペレーションで使用する場合は、このオプションを false に設定することをおすすめします。リソース名のないリソースは、変更オペレーションで使用できないためです。このオプションを true に設定する場合は、プライマリ リソースと、クエリを使用してフェッチする属性リソースの両方のリソース名を明示的にリクエストしてください。

omit_unselected_resource_names の例
SELECT campaign.name, customer.id FROM campaign	Returned resources: 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	Returned resources: なし。 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	Returned resource: 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'