Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

このガイドでは、クライアント ライブラリを使用せずに REST エンドポイントを直接呼び出す例を示します。

Prerequisites

以下のすべてのサンプルは、curl コマンドを使用して bash シェルに簡単にコピーして貼り付けられるように設計されています。

また、開発者トークンテスト アカウント アクセスで十分)と、1 つ以上のクライアント アカウントを含む Google 広告クライアント センター(MCC)アカウントも必要です。

環境変数

以下のアカウントの認証情報と ID を入力し、コピーしてターミナルに貼り付けて、以下の例で使用する環境変数を構成します。

API_VERSION="11"
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 つの [変更 - 作成例] によって新しい予算とキャンペーンが作成されます。

ページ分けあり

search メソッドはページ設定を使用し、調整可能な pageSize パラメータを query とともに指定します。

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 '{
"pageSize": 10,
"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'

ストリーミング

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'

変更

複数の変更オペレーション(createupdateremove)を 1 つの JSON リクエスト本文で送信するには、operations 配列に値を設定します。

作成

この例では、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 つのオペレーションが含まれています。まず、指定したキャンペーンの入札戦略を変更しようとし、次のキャンペーンでは無効な ID のキャンペーンを削除しようとしました。2 番目のオペレーションはエラーになり(キャンペーン ID が無効です)、partialFailurefalse に設定されるため、最初のオペレーションも失敗し、既存のキャンペーンの入札戦略は更新されません。

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 つのオペレーションが失敗した場合、オペレーションのグループ全体が失敗します。

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': {
          'expandedTextAd': {
            'headlinePart1': 'An example headline1',
            'headlinePart2': 'An example headline2',
            'description': 'An example description'
          },
          '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 広告アカウントのリストを取得します。このリクエストでは、マネージャー 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 コマンドライン ユーティリティ(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'
      }
    }
  }
]
}"