このガイドでは、クライアント ライブラリを使用せずに REST エンドポイントを直接呼び出す例を示します。
前提条件
以下のサンプルはすべて、curl コマンドを使用して bash シェルにコピーして貼り付けることを前提としています。
また、開発者トークン(テスト アカウントのアクセス権でも可)と、少なくとも 1 つのクライアント アカウントを含む Google 広告クライアント センター(MCC)アカウントも必要です。
環境変数
アカウントの認証情報と ID を以下に入力し、コピーしてターミナルに貼り付け、後続の例で使用する環境変数を構成します。認可ガイドでは、OAuth 2.0 アクセス トークンの生成手順について説明しています。
API_VERSION="19"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"
追加のオプションのオブジェクト ID
以下の例の一部は、既存の予算またはキャンペーンで機能します。これらの例で使用する既存のオブジェクトの ID がある場合は、以下に入力します。
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
それ以外の場合は、2 つのMutates - Creates examples によって新しい予算とキャンペーンが作成されます。
検索
クエリ クックブック ガイドには、Google 広告のデフォルト画面の一部に対応し、このガイドで使用されている環境変数で動作するレポートのサンプルが多数含まれています。インタラクティブ クエリビルダー ツールは、カスタムクエリをインタラクティブに作成するための優れたリソースです。
ページ分けあり
search
メソッドは、固定ページサイズ 10,000 アイテムのページネーションを使用し、query
とともに page_token
を指定します。
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' ", "page_token":"${PAGE_TOKEN}" }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
ストリーミング
searchStream
メソッドは、すべての結果を 1 つのレスポンスでストリーミングするため、pageSize
フィールドはサポートされていません。
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
変更
operations
配列にデータを入力すると、複数の変更オペレーション(create
、update
、remove
)を 1 つの JSON リクエスト本文で送信できます。
作成
この例では、1 つのリクエストで 2 つの共有キャンペーン予算を作成します。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } }, { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } } ] }"
次の例では、既存のキャンペーン予算の BUDGET_ID
を使用します。これは、前の手順の出力からコピーして貼り付けることができます。
BUDGET_ID=BUDGET_ID
他のリソースを参照するリソースは、リソース名で参照します。以下で作成するキャンペーンは、文字列値のリソース名で campaignBudget
を参照します。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}', 'targetSpend': {} } } ] }"
アップデート
update
オペレーションを使用して、既存オブジェクトの属性を更新します。次の例では既存のキャンペーンを使用します。前の手順の出力からコピーして貼り付けることができます。
CAMPAIGN_ID=CAMPAIGN_ID
すべての更新には、updateMask
フィールドが必要です。これは、更新として適用するリクエストに含める JSON 属性のカンマ区切りのリストです。updateMask
にリストされているがリクエスト本文に存在しない属性は、オブジェクトで消去されます。updateMask
にリストされていないが、リクエスト本文に存在する属性は無視されます。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'name': 'A changed campaign name #${RANDOM}', }, 'updateMask': 'name' } ], }"
削除
オブジェクトは、リソース名を remove
オペレーションとして指定することで削除されます。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}' } ], }"
部分的な失敗
1 つのリクエストに複数のオペレーションがある場合は、必要に応じて partialFailure
を指定します。true
の場合、成功したオペレーションは実行され、無効なオペレーションはエラーを返します。false
の場合、リクエスト内のすべてのオペレーションが有効な場合にのみ、すべてのオペレーションが成功します。
次の例では既存のキャンペーンを使用します。Creates の例の出力からコピーして貼り付けることができます。
CAMPAIGN_ID=CAMPAIGN_ID
次のリクエストには 2 つのオペレーションが含まれています。最初の呼び出しは、指定されたキャンペーンの入札戦略の変更を試みます。2 番目の呼び出しは、無効な ID のキャンペーンの削除を試みます。2 番目のオペレーションでエラーが発生し(キャンペーン ID が無効)、partialFailure
が false
に設定されているため、最初のオペレーションも失敗し、既存のキャンペーンの入札戦略は更新されません。
curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'partialFailure': false, 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'manualCpc': { 'enhancedCpcEnabled': false } }, 'updateMask': 'manual_cpc.enhanced_cpc_enabled' }, { 'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID' } ] }"
グループ化されたオペレーション
googleAds:mutate
メソッドは、複数のタイプのリソースを含むオペレーションのグループの送信をサポートしています。さまざまなタイプのオペレーションを送信して、グループとして実行する一連のオペレーションを連結できます。オペレーションのセットは一連のオペレーションがすべて成功した場合に成功し、1 つのオペレーションが失敗した場合はすべて失敗します。
この例では、キャンペーンの予算、キャンペーン、広告グループ、広告を 1 つのアクション セットとして作成します。後続のオペレーションは、前のオペレーションに依存します。1 つが失敗すると、オペレーションのグループ全体が失敗します。
負の整数(-1
、-2
、-3
)はリソース名のプレースホルダとして使用され、ランタイムでオペレーションのシーケンスの結果で動的に入力されます。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'mutateOperations': [ { 'campaignBudgetOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'name': 'My Campaign Budget #${RANDOM}', 'deliveryMethod': 'STANDARD', 'amountMicros': 500000, 'explicitlyShared': false } } }, { 'campaignOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2', 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'targetSpend': {} } } }, { 'adGroupOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3', 'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2', 'name': 'My ad group #${RANDOM}', 'status': 'PAUSED', 'type': 'SEARCH_STANDARD' } } }, { 'adGroupAdOperation': { 'create': { 'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3', 'status': 'PAUSED', 'ad': { 'responsiveSearchAd': { 'headlines': [ { 'pinned_field': 'HEADLINE_1', 'text': 'An example headline' }, { 'text': 'Another example headline' }, { 'text': 'Yet another headline' } ], 'descriptions': [ { 'text': 'An example description' }, { 'text': 'Another example description' } ], 'path1': 'all-inclusive', 'path2': 'deals' }, 'finalUrls': ['https://www.example.com'] } } } } ] }"
アカウント管理
アカウントの作成
createCustomerClient
メソッドを使用して新しいアカウントを作成します。URL には、クライアント アカウント ID ではなくクライアント センター(MCC)アカウント ID が必要です。クライアント センター(MCC)アカウントの配下に新しいクライアント アカウントが作成されます。
curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'customerClient': { 'descriptiveName': 'My Client #${RANDOM}', 'currencyCode': 'USD', 'timeZone': 'America/New_York' } }"
アクセス可能なアカウントの一覧表示
listAccessibleCustomers
メソッドに対する単純な GET
リクエストを使用して、指定された OAuth 2.0 アクセス トークンでアクセスできる Google 広告アカウントのリストを取得します。このリクエストでは、クライアント センター(MCC)アカウント ID またはクライアント アカウント ID を使用しないでください。
curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
バイナリ アセットのアップロード
assets:mutate
メソッドは、アセットのアップロードと管理に使用されます。画像などのバイナリデータは、パディング付きの標準 Base64 エンコードを使用して文字列としてエンコードされます。パディングありまたはパディングなしの標準または URL セーフの Base64 エンコードが使用できます。
この例では、サンプルを簡潔にするために 1 ピクセルの GIF をエンコードしています。実際には、data
ペイロードははるかに大きくなります。
base64
コマンドライン ユーティリティ(GNU コア ユーティリティの一部)を使用して、1 ピクセルの GIF 画像をエンコードします。
base64 1pixel.gif
base64 でエンコードされた値は、API リクエストの data
属性として指定されます。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My image asset #${RANDOM}', 'type': 'IMAGE', 'imageAsset': { 'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA' } } } ] }"