此页面由 Cloud Translation API 翻译。

示例

本指南包含直接调用 REST 端点（不使用客户端库）的示例。

如需查看更详细的代码示例，请参阅 REST 代码示例 GitHub 代码库。

如需查看每种 API 方法的请求和响应正文，请参阅特定服务端点的参考文档。

例如，GoogleAdsService.Search 的参考页面显示了 Search 方法的请求和响应正文。

前提条件

此处显示的所有示例均可使用 curl 命令复制并粘贴到 bash shell 中。

您还需要具备开发者令牌（测试账号访问权限即可）以及包含至少一个客户账号的 Google Ads 经理账号。

环境变量

按所示方式输入账号凭据和 ID，然后复制并粘贴到终端中，以配置后续示例中使用的环境变量。授权指南提供了有关如何生成 OAuth 2.0 访问令牌的说明。

API_VERSION="22"
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'

流式

searchStream 方法会在单个响应中流式传输所有结果，因此不支持 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 数组，可以在单个 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'
      }
    }
  }
]
}"

常见错误

试试看！

示例 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

前提条件

环境变量

其他可选对象 ID

搜索

分页

curl

GAQL

流式

curl

GAQL

转变

创建

更新

移除

部分失败

分组操作

账号管理

创建账号

列出可访问的账号

上传二进制资源

示例