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

クエリの構造

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

SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS

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

句

動画: 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 句で使用できない場合があります。

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

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

FROM

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

1 つのクエリで FROM 句に存在できるリソースは 1 つだけですが、[Attributed Resources] のフィールドも使用可能です。これらのリソースは 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 のパターンに従う必要があります。クエリでは 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、segment.week、segments.month、segments.quarter、segment.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 です。

省略_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.costMicros
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'
```

クエリ文法

期間