Google 広告クエリ言語を使って、Google Ads API に対して次の点をクエリできます。
- リソースとそれに関連する属性、セグメント、指標
GoogleAdsService
検索または SearchStream- GoogleAdsService クエリの結果は
GoogleAdsRow
インスタンスのリストとなり、各GoogleAdsRow
はリソースを表します。属性や指標がリクエストされた場合、行にはそれらのフィールドも含まれます。セグメントがリクエストされた場合、レスポンスにはセグメント リソースタプルごとに行が追加されます。 - 利用可能なフィールドとリソースに関するメタデータ
GoogleAdsFieldService
このサービスでは、クエリ可能フィールドのカタログに、その互換性とタイプに関する詳細が提供されます。
GoogleAdsFieldService
クエリの結果はGoogleAdsField
インスタンスのリストであり、各GoogleAdsField
にはリクエストされたフィールドの詳細が含まれています。
リソースの属性のクエリ
以下は、キャンペーン リソースの属性のうち、キャンペーン ID、名前、ステータスを返す方法を示す基本的なクエリです。
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
ORDER BY campaign.id
このクエリはキャンペーン ID で並べ替えます。生成される各 GoogleAdsRow
は、選択されたフィールド(特定のキャンペーンの resource_name
を含む)が入力された campaign
オブジェクトを表します。
キャンペーンのクエリに使用できる他のフィールドについては、Campaign
リファレンス ドキュメントをご覧ください。
指標のクエリ
特定のリソースに対して選択された属性に加えて、関連する指標をクエリすることもできます。
SELECT
campaign.id,
campaign.name,
campaign.status,
metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
AND metrics.impressions > 1000
ORDER BY campaign.id
このクエリは、キャンペーン ID で並べ替えながら、ステータスが PAUSED
で表示回数が 1, 000 回を超えるキャンペーンのみをフィルタします。結果の GoogleAdsRow
ごとに、選択した指標が入力された metrics
フィールドがあります。
クエリ可能な指標のリストについては、Metrics
のドキュメントをご覧ください。
セグメントのクエリ
特定のリソースに対して選択された属性に加えて、関連するセグメントに対してクエリを実行することもできます。
SELECT
campaign.id,
campaign.name,
campaign.status,
metrics.impressions,
segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
AND metrics.impressions > 1000
AND segments.date during LAST_30_DAYS
ORDER BY campaign.id
指標のクエリと同様に、このクエリでは、ステータスが PAUSED
でインプレッション数が 1,000 を超えるキャンペーンのみをフィルタリングします。このクエリでは、データが日付でセグメント化されます。これにより、結果の GoogleAdsRow
は、キャンペーンのタプルと日付 Segment
を表します。セグメンテーションでは、SELECT 句のセグメントごとに選択した指標が分割されることに注意してください。
クエリ可能なセグメントのリストについては、Segments
のドキュメントをご覧ください。
関連リソースの属性のクエリ
特定のリソースのクエリで、他の関連リソースが利用可能であれば結合できることもあります。これらの関連リソースは、「関連付けされたリソース」と呼ばれます。クエリで属性を選択すると、関連付けられたリソースに対して暗黙的に結合できます。
SELECT
campaign.id,
campaign.name,
campaign.status,
bidding_strategy.name
FROM campaign
ORDER BY campaign.id
このクエリでは、キャンペーン属性だけでなく、選択した各キャンペーンから関連属性も取得されます。結果として得られる GoogleAdsRow
はそれぞれ、選択したキャンペーン属性と選択された入札戦略属性 bidding_strategy.name
が入力された campaign
オブジェクトを表します。
キャンペーン クエリで使用可能なアトリビューション リソースについては、Campaign
リファレンス ドキュメントをご覧ください。
クエリ結果に基づく変更
特定のリソースをクエリするときに、返された結果をオブジェクトとしてすぐに取得し、変更して、そのリソースのサービスの mutate メソッドに返すことができます。ワークフローの例を次に示します。
- 現在
PAUSED
で、インプレッション数が 1,000 を超えるすべてのキャンペーンにクエリを実行します。 - レスポンス内の各
GoogleAdsRow
のcampaign
フィールドからCampaign
オブジェクトを取得します。 - 各キャンペーンのステータスを
PAUSED
からENABLED
に変更します。 - 変更したキャンペーンで
CampaignService.MutateCampaigns
を呼び出して、更新します。
フィールド メタデータ
GoogleAdsFieldService
に送信されたクエリは、フィールド メタデータを取得するためのものです。この情報は、クエリ内のフィールドの併用方法を理解するのに役立ちます。データは API から利用でき、クエリの検証や作成に必要なメタデータを提供するため、デベロッパーはプログラムでこれを実現できます。メタデータの一般的なクエリを次に示します。
SELECT
name,
category,
selectable,
filterable,
sortable,
selectable_with,
data_type,
is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"
このクエリの <INSERT_RESOURCE_OR_FIELD>
は、リソース(customer
、campaign
など)またはフィールド(campaign.id
、metrics.impressions
、ad_group.id
など)に置き換えることができます。
クエリ可能なフィールドのリストについては、GoogleAdsField
のドキュメントをご覧ください。
コードの例
Google 広告のクエリ言語を GoogleAdsService
で使用する際のクライアント ライブラリのサンプルをご確認ください。basic オペレーション フォルダには、GetCampaigns
、GetKeywords
、SearchForGoogleAdsFields
などの例があります。reporting フォルダには GetKeywordStats
のサンプルがあります。