リソース、セグメント、指標のフィールドに対するクエリは、GoogleAdsService
の Search メソッドまたは SearchStream メソッドに送信できます。Google 広告クエリ言語でクエリを作成するには、言語の文法を使ってクエリを作成する必要があります。クエリはいくつかの句で構成されます。
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
正しいデータを選択できるように、句ではフィールド名、リソース名、演算子、条件、並べ替えを使用できます。1 つのクエリに統合すると、Google Ads API を使用してリクエストを作成できます。
句
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
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'