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

クエリの構造

リソース、セグメント、指標の各フィールドのクエリの送信先 GoogleAdsService [検索] または [SearchStream] あります。Google 広告クエリ言語でクエリを作成するには、言語文法。クエリは複数の句:

SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS

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

句

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

SELECT

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

以下のサンプルクエリは、特定のオブジェクトの属性を選択する例を示しています。 resource:

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 句のリソースは、他のすべてのテーブルで使用できるフィールドを定義します。句を使用します。Deployment では 1 つのリソースのみ FROM 句。FROM 句は、テーブルに対するクエリでは必須です。 GoogleAdsService [検索] または [SearchStream] ただし、 GoogleAdsFieldService を選択します。

特定のクエリの FROM 句に存在できるリソースは 1 つだけですが、アトリビューションリソースから取得することもできます。これらのリソースは FROM 句でリソースと暗黙的に結合されるため、必要なのはその属性を SELECT 句に追加して、それらの値を返します。すべてではありませんリソースに帰属リソースがあります。次の例では、Cloud Storage バケットに広告グループ 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 句を使用する場合は、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 句で使用する必要があります。

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

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

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

Simply_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'
```

クエリ文法

期間