リソース、セグメント、指標の各フィールドに対するクエリは、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
句で使用できない場合があります。
- 選択できないフィールドをクエリする場合。これらのフィールドの
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
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
です。
omit_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'