本指南包含直接调用 REST 端点（不使用客户端库）的示例。
前提条件
此处显示的所有示例均旨在通过 curl 命令复制并粘贴到 bash shell 中。
您还需要具备开发者令牌（测试账号访问权限即可）以及包含至少一个客户账号的 Google Ads 经理账号。
环境变量
按所示方式输入账号凭据和 ID，然后将其复制并粘贴到终端中，以配置后续示例中使用的环境变量。 授权指南提供了有关如何生成 OAuth 2.0 访问令牌的说明。
API_VERSION="20"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"其他可选对象 ID
以下部分示例适用于现有预算或广告系列。如果您有要用于这些示例的现有对象的 ID，请按所示方式输入这些 ID。
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID否则，这两个 Mutates - Creates examples 会创建新的预算和广告系列。
搜索
查询实用指南包含许多报告示例，这些示例与某些默认的 Google Ads 界面相对应，并且使用与本指南中相同的环境变量。我们的交互式查询构建器工具也是一个很好的资源，可用于以交互方式构建自定义查询。
分页
search 方法使用分页功能，页面大小固定为 10,000 个商品，并且 page_token 与 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 '{ "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'
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 数组，可以在单个 JSON 请求正文中发送多个 mutate 操作（create、update 或 remove）。
创建
此示例在一个请求中创建了两个共享广告系列预算。
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}' } ], }"
部分失败
如果单个请求中包含多项操作，可选择指定 partialFailure。如果值为 true，则会执行成功操作，而无效操作会返回错误。如果为 false，则当且仅当请求中的所有操作都有效时，这些操作才会全部成功。
下一个示例使用现有广告系列；您可以从 Creates 示例输出中复制并粘贴。
CAMPAIGN_ID=CAMPAIGN_ID以下请求包含两项操作。第一个尝试更改所提供广告系列的出价策略，第二个尝试移除 ID 无效的广告系列。由于第二个操作会导致错误（广告系列 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、-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 方法创建新账号。请注意，该网址需要经理账号 ID，而不是客户账号 ID。在经理账号下创建新的客户账号。
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 Ads 账号列表。此请求中不应使用任何经理账号或客户账号 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 编码进行编码，并以字符串形式表示。系统接受标准 base64 编码或网址安全 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' } } } ] }"