Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

例

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

コード例について詳しくは、REST コード例の GitHub リポジトリをご覧ください。

各 API メソッドのリクエスト本文とレスポンス本文については、特定のサービスエンドポイントのリファレンスドキュメントをご覧ください。

たとえば、リファレンスページには、GoogleAdsService.Search Searchメソッドのリクエスト本文とレスポンス本文が記載されています。

前提条件

ここに示されているサンプルはすべて、 bash シェルにコピーして貼り付けることを想定しています。

また、Google Cloud プロジェクト（テストアカウントアクセスで構いません）と、少なくとも 1 つのクライアントアカウントを含む Google 広告のクライアントセンター（MCC）アカウントが必要です。

環境変数

アカウントの認証情報と ID を図のように入力し、ターミナルにコピーして貼り付けて、以降の例で使用する環境変数を構成します。認証ガイドでは、 OAuth 2.0 アクセストークンの生成方法について説明しています。

API_VERSION="25"
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 の例で、新しい予算とキャンペーンが作成されます。

検索

クエリクックブックガイドには、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'

変更

複数の変更オペレーション（create、update、remove）は、operations 配列に値を設定することで、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 の場合、リクエスト内のすべてのオペレーションが有効な場合にのみ、すべてのオペレーションが成功します。

次の例では、既存のキャンペーンを使用します。これは、作成の例の出力からコピーして貼り付けることができます。

CAMPAIGN_ID=CAMPAIGN_ID

次のリクエストには 2 つのオペレーションが含まれています。1 つ目は、指定されたキャンペーンの入札戦略を変更しようとし、もう 1 つは、無効な 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'
}
}"

アクセス可能なアカウントの一覧表示

シンプルな GET リクエストを listAccessibleCustomers メソッドに使用して、指定された 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 ペイロードははるかに大きくなります。

1 ピクセルの GIF 画像をエンコードするには、base64 コマンドラインユーティリティ（ GNU コアユーティリティの一部）を使用します。

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'
      }
    }
  }
]
}"

よくある間違い

試してみる

例 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

前提条件

環境変数

その他のオプション オブジェクト ID

検索

ページ分けあり

curl

GAQL

ストリーミング

curl

GAQL

変更

作成

アップデート

削除

部分的な失敗

グループ化されたオペレーション

アカウント管理

アカウントを作成

アクセス可能なアカウントの一覧表示

バイナリ アセットをアップロードする

例

その他のオプションオブジェクト ID

バイナリアセットをアップロードする