Google Ads API - 调用 REST API

蒙哥卡恩就是我2023-11-06 15:28

要点 ：我们强烈建议您尽可能使用我们的官方客户端库。Google 提供的所有客户端库都是使用 gRPC 实现的，但使用 REST 接口的 Perl 库除外。除非您特别需要查找 REST 的详细信息，否则请查阅 gRPC 文档，以了解我们官方客户端库的参考文档。

您可以使用 gRPC 或 REST 调用 Google Ads API。这两个接口均采用与其他 Google Cloud API 共享的面向资源的设计。

我们建议您尽可能地使用 Google 的官方客户端库。它们提供了多种支持语言符合类型规范的代码，可处理与该 API 的许多沟通细节（例如超时设置、结果集分页和身份验证）。我们的客户端库还包含一套丰富的代码示例和一些实用程序，可帮助您完成任务名称和处理字段掩码等常见任务。

本指南介绍了特定于 REST 调用方式的详细信息，并说明了如何直接调用 REST 接口，而无需使用 Google 支持的客户端库。如果您要编写自己的自定义代码以直接使用 REST 或使用第三方 HTTP 客户端库，本指南可能对您很有帮助。

授权和 HTTP 标头

调用 Google Ads API 时，您需要 OAuth 2.0 应用凭据和开发者令牌。如果您使用 Google Ads 经理帐号进行 API 调用，则还需要为每个请求指定 login-customer-id 标头。本页面介绍了如何设置这些值，并记录了使用 REST 接口时发送和接收的另外几个特定于 API 的 HTTP 标头。

OAuth 2.0 凭据

Google Ads API 使用应用凭据识别 API 请求和为其授权。OAuth 2.0 客户端和服务帐号都可以配置。如需详细了解如何配置客户端授权，请参阅 Google Ads API 中的 OAuth2。

如果您刚开始接触 Google API，可以在为应用编写代码之前，使用 oauth2l 或 OAuth 2.0 Playground 尝试使用应用凭据和 Google Ads API。

使用桌面应用或 Web 应用流程

参考《为 Google Ads API 配置一个 Google API 控制台项目》一文中介绍的步骤，记录客户端 ID 和客户端密钥，然后返回此页面。

创建 OAuth 客户端后，请按照桌面应用流程说明或 Web 应用流程说明生成刷新令牌和访问令牌。

使用服务账号

按照服务帐号指南中的常用说明为 Google Ads API 设置服务帐号访问权限。

设置可访问 Google Ads 帐号的服务帐号后，请按照针对服务器到服务器应用使用 OAuth 2.0 指南操作，确保选择 HTTP/REST 标签页。用于访问 Google Ads API 的 scope 为 https://www.googleapis.com/auth/adwords。

生成新的访问令牌

在具备客户端 ID、客户端密钥和刷新令牌后，您可以生成新的访问令牌，用于通过 curl 命令行工具进行 API 调用：

注意 ：OAuth 端点网址中的版本 v3 与 Google Ads API 版本无关，在迁移到较新版本的 Google Ads API 时不应发生变化。

bash 复制代码 
$ curl --location 'https://www.googleapis.com/oauth2/v3/token' \
--header 'Content-Type: application/json' \
--data '{
    "grant_type": "refresh_token",
    "client_id": "210949292090-c6auhf4pvbqk25qj37nas6jit7mjurhf.apps.googleusercontent.com",
    "client_secret": "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",
    "refresh_token": "1//0eIO9yJdcQLRJCgYIARAAGA4SNwF-L9Irv9LTO3mxLY_03HcbdK8bJSr_Bw4UR4vLOcrZwNINBZPYap17MCCSjt6ZV1rIdhqRCEg"
}'

调用上述接口，将返回 access_token 字段。

json 复制代码 
{
    "access_token": "ya29.a0AfB_byBY9XzToW3j-3FZcRC8dfFLHUiJ4xDA1DnrmId5UwRz3LSLbx8VscTKCM5LFjOq6Cdd8wxkwiI9JhlGnepgfNVAIZGJIS7W1fs5vx_CaxoUzcK-cW-yEo3wq0ZgSRuH67rNm8k4ShaWkpjSJbukssCWWJ8uKmpTwQaCgYKARcSARASFQGOcNnC4VF0xxO9rjyU5rNlXKGSzg0173",
    "expires_in": 3599,
    "scope": "https://www.googleapis.com/auth/adwords",
    "token_type": "Bearer"
}

然后，您可以在每次对 Google Ads API 进行 API 调用的时候，在 Authorization HTTP Header 中使用 curl 请求返回的访问令牌：

bash 复制代码 
$ curl --location 'https://googleads.googleapis.com/v15/customers:listAccessibleCustomers' \
--header 'Authorization: Bearer ya29.a0AfB_byBY9XzToW3j-3FZcRC8dfFLHUiJ4xDA1DnrmId5UwRz3LSLbx8VscTKCM5LFjOq6Cdd8wxkwiI9JhlGnepgfNVAIZGJIS7W1fs5vx_CaxoUzcK-cW-yEo3wq0ZgSRuH67rNm8k4ShaWkpjSJbukssCWWJ8uKmpTwQaCgYKARcSARASFQGOcNnC4VF0xxO9rjyU5rNlXKGSzg0173' \
--header 'developer-token: iYZ11wCweJg5ZW-nyIsr-Q'

请求标头

开发者令牌

Google Ads API 还需要开发者令牌才能调用 API。您可以直接在 Google Ads 界面中为您的经理帐号申请令牌。如需详细了解如何设置开发者令牌，请参阅获取开发者令牌。

您需要在每次对 Google Ads API 进行 API 调用的 developer-token HTTP 标头中添加您的开发者令牌值：

makefile 复制代码 
GET /v15/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ya29.a0AfB_byBY9XzToW3j-3FZcRC8dfFLHUiJ4xDA1DnrmId5UwRz3LSLbx8VscTKCM5LFjOq6Cdd8wxkwiI9JhlGnepgfNVAIZGJIS7W1fs5vx_CaxoUzcK-cW-yEo3wq0ZgSRuH67rNm8k4ShaWkpjSJbukssCWWJ8uKmpTwQaCgYKARcSARASFQGOcNnC4VF0xxO9rjyU5rNlXKGSzg0173
developer-token: iYZ11wCweJg5ZW-nyIsr-Q

登录客户 ID

当经理身份登录向其某个客户帐号进行 API 调用时，您还需要提供 login-customer-id HTTP 标头。此值表示调用 API 经理的 Google Ads 客户 ID。

添加这样的标题相当于在登录或点击页面右上角的个人资料图片后，在 Google Ads 界面中选择帐号的操作。指定客户 ID 时，请务必移除所有连字符 (-)，例如 8573484547，而不是 857-348-4547。

bash 复制代码 
$ curl --location 'https://googleads.googleapis.com/v15/customers/3111469290/googleAds:searchStream' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ya29.a0AfB_byBY9XzToW3j-3FZcRC8dfFLHUiJ4xDA1DnrmId5UwRz3LSLbx8VscTKCM5LFjOq6Cdd8wxkwiI9JhlGnepgfNVAIZGJIS7W1fs5vx_CaxoUzcK-cW-yEo3wq0ZgSRuH67rNm8k4ShaWkpjSJbukssCWWJ8uKmpTwQaCgYKARcSARASFQGOcNnC4VF0xxO9rjyU5rNlXKGSzg0173' \
--header 'developer-token: iYZ11wCweJg5ZW-nyIsr-Q' \
--header 'login-customer-id: 8573484547' \
--data '{
    "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}'

要点 ：如果您并非以经理帐号的身份授权；也就是说，如果您的 OAuth 2.0 凭据直接面向目标 Google Ads 客户帐号的用户，则无需提供 login-customer-id 标头。

关联的客户 ID

此标头仅供第三方应用分析工具在将转化数据上传到关联的 Google Ads 帐号时使用。如需了解详情，请参阅 API 调用结构指南。

bash 复制代码 
... 
Authorization: Bearer ya29.a0AfB_byBY9XzToW3j-3FZcRC8dfFLHUiJ4xDA1DnrmId5UwRz3LSLbx8VscTKCM5LFjOq6Cdd8wxkwiI9JhlGnepgfNVAIZGJIS7W1fs5vx_CaxoUzcK-cW-yEo3wq0ZgSRuH67rNm8k4ShaWkpjSJbukssCWWJ8uKmpTwQaCgYKARcSARASFQGOcNnC4VF0xxO9rjyU5rNlXKGSzg0173
developer-token: iYZ11wCweJg5ZW-nyIsr-Q 
login-customer-id: 8573484547 
linked-customer-id: $(LINKED_CUSTOMER_ID)

响应标头

从 API 发出的 HTTP 响应中会返回以下标头。

请求 ID

request-id 是用于唯一标识 API 请求的字符串。在调试或排查特定 API 调用的问题时，request-id 是一个重要的标识符，您在与 Google 开发者支持团队联系时可以派上用场。

设计

概览

本页面假定您熟悉面向资源的设计和资源名称开发者指南，对 Google Ads API 的具体实现细节进行补充。

要点 ：本指南中的示例使用 HTTP 协议来演示如何调用该 API。如需了解如何使用 curl 命令行实用程序进行相同的 API 调用，请参阅示例页面。

面向资源的设计

通常，Google Ads API 遵循以资源为导向的设计，建模为可单独寻址的资源（API 中的"名词"）的集合。资源通过资源名称进行引用，并使用一小部分方法（也称为动词或操作）来操纵资源。

这些资源名称和方法与特定 API 版本前缀相结合，构成 REST 接口的网址。例如，根据下表，以下网址可以细分为下面这些单独的组成部分：

googleads.googleapis.com/v15/custome...

API 版本前缀 资源名称（相对名称） 方法
googleads.googleapis.com/v15 customers/1234567890 mutate

特定 API 版本的所有 REST 网址共用一个通用的 API 版本前缀（例如：v15）。资源名称和方法共同标识正在调用哪个 API 服务。

Google Ads API 大量使用"自定义方法"，而大多数传统 REST API 则使用标准 REST 方法（如 list、get、create、update 和 delete）。Google Ads API 中的自定义方法示例包括 search、searchStream 和 mutate。

以下页面详细介绍了 Google Ads API 的资源名称、服务方法和 JSON 命名惯例，以说明它们如何一起定义 REST 接口端点。

资源名称

名称层次结构

Google Ads API 中使用的资源名称采用分层形式，反映了 Google Ads 中实体的组织方式。几乎所有资源都是 Customer 资源的子资源，以反映几乎所有 API 调用都必须以特定的 Google Ads 帐号为目标。例如，广告系列、广告组、广告和关键字都是根客户资源的子资源。

资源 资源名称
客户 customers/1234567890
广告系列 customers/1234567890/campaigns/8765432109
广告组 customers/1234567890/adGroups/54321098765
广告组 customers/1234567890/adGroupAds/54321098765~2109876543210

要点 ：Google Ads API 使用的是相对资源名称（而不是像其他一些 Google API 那样拥有完整资源名称）。

资源 ID

Google Ads 实体（客户、广告系列等）由其在整个 API 中的资源名称来引用。但请务必注意，资源名称本身可能具有唯一的数字资源 ID，用于标识层次结构中的每个对象。在这些情况下，解析资源名称以提取这些资源 ID 并构建一个新资源 ID 可能会很有帮助。

例如，请查看上表中的 AdGroupAd 资源名称：

customers/1234567890/adGroupAds/54321098765~2109876543210

可将其细分为单独的资源 ID（由集合 ID 分隔），如下图所示：

通过解析单个 ID，您可以派生新的资源名称来引用广告组广告的客户 (customers/1234567890) 或其广告组 (customers/1234567890/adGroupAds/54321098765)。

要点 ：JSON 请求和响应正文中的资源名称由 resourceName 字段引用，而不是像其他一些 Google Cloud API 一样由 name 字段引用。许多 Google Ads 实体本身就有名称属性（campaign.Name、adGroup.Name 等），因此使用 resourceName 以避免与现有对象名称发生冲突。

共享对象的标识符

API 中的大多数对象都与一个特定的 Google Ads 客户相关联。不过，有些对象类型可以在多个帐号之间共享。在实践中，这些都是否定关键字列表或跨帐号转化操作等，通常由经理创建，然后与许多客户帐号共享。

这些对象的资源名称会因您向哪个 API 调用发送 API 而异。

示例：跨帐号转化操作

假设我们的经理帐号 987-654-3210 与其某个客户帐号 123-456-7890 共享跨帐号转化操作：

例如，如果对经理帐号进行 API 调用以更新转化操作的回溯期，则会使用资源名称引用共享对象：customers/9876543210/conversionActions/257733534。

调用客户帐号以选择启用此共享转化操作时，系统会使用以下资源名称引用该转化操作：customers/1234567890/conversionActions/257733534。

此方式与底层转化操作相同，但其资源名称与用于访问该操作的帐号相关。

服务方法

Google Ads API 的设计与传统的 REST 架构不同，因为它主要使用自定义方法（例如 search 和 mutate），而不是更传统的 list、get、create、update 和 delete 方法。这些操作在 REST 网址中表示，使用 : 的 HTTP 映射惯例将自定义动词与网址的其余部分分开。

例如，广告系列转变 API 调用使用以下网址：

googleads.googleapis.com/v15/custome...

该 API 使用自定义方法的一个原因是允许将多个操作批量处理到单个 API 请求中。严格的 REST 语义仅允许一次更新一个广告系列。例如，对于广告系列的传统 REST update，则需要为每个广告系列资源发送一个 HTTP PATCH 请求。

为了使许多操作捆绑到一个请求正文中，Google Ads API 改为定义了大多数资源的一个自定义 mutate 方法。同样，如需启用 API 的批量读取（一次提取许多对象），该 API 会使用自定义 search 方法和 SQL 形式的 Google Ads 查询语言。

常用方法中详细介绍了 Google Ads API 中最常用的方法。

JSON 映射

使用 Google Ads API 的 REST 接口时，您使用的 JSON 表示法与 Google Ads API 的 .proto Descriptor 文件中定义的资源和类型相同。JSON 编码方案遵循协议缓冲区语言指南的 JSON 映射部分中所述的规范编码方案。

一般来说，进出服务的所有顶级消息都是单个 JSON 对象。大多数转变请求都包含一个 operations 数组，该数组本身包含许多 create、update 或 delete 操作。同样，search 响应是 JSON 对象，其中包含一个 results 数组，其中包含查询结果。

在 JSON 中，标识符从 snake_case （在协议缓冲区中）转换为 lowerCamelCase 。此规则的一个重要注意事项是，使用 search 或 searchStream 发送 Google Ads 查询语言查询时。无论您使用哪个接口，查询语言本身都会使用蛇形结构。但是，REST 中的查询结果会以普通 JSON 对象的形式返回，并且其标识符采用驼峰式大小写形式。

例如，如果查询要获取帐号中有效关键字列表的列表，则会在查询本身内使用蛇形大小写（ad_group_criterion，而不是 adGroupCriterion）：

bash 复制代码 
POST /v15/customers/3111469290/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: iYZ11wCweJg5ZW-nyIsr-Q

{
   "query": "SELECT ad_group_criterion.keyword.text
            FROM ad_group_criterion
            WHERE ad_group_criterion.type = 'KEYWORD'
            AND ad_group_criterion.status = 'ENABLED'" 
}

不过，响应是对象的 JSON 表示法（封装在 JSON 数组中，因为此请求使用 searchStream），而改为使用驼峰式大小写标识符 adGroupCriterion：

json 复制代码 
[
  {
    "results": [
      {
        "adGroupCriterion": {
          "resourceName": "customers/1842689525/adGroupCriteria/55771861891~10003060",
          "keyword": {
            "text": "pay per click"
          }
        }
      },
      ...
    ]
  }
]

常用方法

概览

接下来的几页介绍整个 Google Ads API 中最常用的 REST 方法：Search（和 SearchStream）和 Mutate 方法。

其他方法中介绍了如何查找其他服务方法的相关信息。

搜索和搜索信息流

注意 ：如需查看更完整的示例，请参阅相关示例的搜索部分。

Google Ads API 具有统一的属性检索和指标报告机制，让您可以使用 Google Ads 查询语言创建查询。这样可以实现复杂的查询，可以返回大量有关各个 Google Ads 帐号的数据。

您可以使用 Search 或 SearchStream 方法创建查询。这两种方法支持相同的查询，并返回等效结果。Search 方法会返回可自定义的页面大小的数据，使您能够使用分页遍历结果集。这在带宽低或不可靠的网络条件下可能十分有用，例如，可将大型结果集细分为较小的响应，在连接丢失时可以重新获取。另一方面，SearchStream 方法可将整个结果集流式传输到单个响应中，这对于批量数据检索效率更高。

Search 和 SearchStream 使用相同的 base URL：

googleads.googleapis.com/v15/custome...

基于网页的搜索方法接受可选的 pageSize 参数，该参数可以限制单个 API 响应中返回的结果数量。

注意 ：pageSize 参数是可选的，如果未明确设置，默认值为 10,000。

bash 复制代码 
POST /v15/customers/3111469290/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: iYZ11wCweJg5ZW-nyIsr-Q

{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}

如果结果中的行数超过 pageSize，响应中将返回 nextPageToken：

json 复制代码 
{
  "results": [
    // ...
    // ...
    // ...
  ],
   "nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B" ,
  "fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}

使用添加了上述值的 pageToken 重复执行相同的查询，以获取下一页结果：

bash 复制代码 
POST /v15/customers/3111469290/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: iYZ11wCweJg5ZW-nyIsr-Q

{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'",
 "pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B" 
}

如需使用 SearchStream 方法（该方法会在单次流式响应中返回所有结果），只需将网址中的服务方法更改为 searchStream，请注意 SearchStream 无需使用 pageSize 和 pageToken：

bash 复制代码 
POST /v15/customers/3111469290/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: iYZ11wCweJg5ZW-nyIsr-Q

{
    "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}

注意 ：SearchStream API 调用的结果封装在 JSON 数组中，而大多数其他 API 调用都会返回单个 JSON 对象作为响应消息。如需了解详情，请参阅 [JSON 映射](#JSON 映射 "#JSON%E6%98%A0%E5%B0%84")部分。

Mutate

注意 ：如需查看更完整的示例，请参阅随附的转变部分。

大多数资源都使用 Mutate 方法进行修改（创建、更新或移除）。系统会以 HTTP POST 的形式调用 Mutate 方法，提供给与资源名称模式匹配的资源专用网址，不含尾随资源 ID。需要更改的资源的 ID 会改为在 JSON 请求正文中发送。这样，您就可以发送一个包含不同资源的多项操作的 API 调用。

例如，广告系列的资源名称采用以下格式：

customers/3111469290/campaigns/CAMPAIGN_ID

如需派生用于更改广告系列的网址，请省略末尾的资源 ID 并附加 :mutate：

googleads.googleapis.com/v15/custome...

Mutate 消息包含一个顶级 JSON 对象（带有一个可包含多个 operation 对象的 operations 数组）。反过来，每项操作都可以是 create、update 或 remove 之一。这些是唯一可能的转变操作。

bash 复制代码 
POST /v15/customers/3111469290/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: iYZ11wCweJg5ZW-nyIsr-Q

{
  "operations": [
    ...
  ]
}

大多数服务在一次 API 调用中支持数千项操作。系统限制指南记录了请求大小的限制。

默认情况下，单个 API 请求中的操作以一组操作的形式执行，这意味着如果任一操作失败，所有操作可以一起成功，或者整个批次将会失败。某些服务支持使用 partialFailure 属性来更改此行为。如需详细了解转变操作语义，请参阅转变资源。

创建

创建操作会生成新实体，并且必须包含要创建的资源的完整 JSON 表示法。

要点 ：创建操作未指定 resourceName 或 ID。API 调用成功后，响应中会包含为新创建的对象生成的 resourceName。

bash 复制代码 
POST /v15/customers/3111469290/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: iYZ11wCweJg5ZW-nyIsr-Q

{
  "operations": [
    {
    "create": {
        "name": "An example campaign",
        "status": "PAUSED",
        "campaignBudget": "customers/3111469290/campaignBudgets/CAMPAIGN_BUDGET_ID",
        "advertisingChannelType": "SEARCH",
        "networkSettings": {
          "targetGoogleSearch": true,
          "targetSearchNetwork": true,
          "targetContentNetwork": true,
          "targetPartnerSearchNetwork": false
        },
        "target_spend": {}
      }
    }
  ]
}

更新

更新操作对现有资源执行稀疏更新。您只需要指定要修改的字段。

如需指定要更新的字段，请将 updateMask 属性设置为一个以英文逗号分隔的字段名称列表。如果您已具有对象的完整格式 JSON 表示法（例如，如之前的 API 调用所返回），但只想更改某些字段，这种方法特别有用。您只需在 updateMask 中列出要修改的字段名称并发送整个 JSON 对象，而无需修改 JSON 对象。

要点 ：update_mask 是一个在 Google API 中使用的标准字段，有助于对给定资源执行部分更新。如需了解完整详情，请参阅 FieldMask 参考文档。

以下示例会更改具有给定 resourceName 的现有广告系列的 name 和 status。

bash 复制代码 
POST /v15/customers/3111469290/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: iYZ11wCweJg5ZW-nyIsr-Q

{
  "operations": [
    {
      "updateMask": "name,status",
      "update": {
        "resourceName": "customers/3111469290/campaigns/CAMPAIGN_ID",
        "name": "My renamed campaign",
        "status": "PAUSED",
      }
    }
  ]
}

移除

移除操作会有效地删除一个对象，并将其 Google Ads 状态设置为 REMOVED。只需移除要移除的 resourceName。

bash 复制代码 
POST /v15/customers/3111469290/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: iYZ11wCweJg5ZW-nyIsr-Q

{
  "operations": [
    {
      "remove": "customers/3111469290/campaigns/CAMPAIGN_ID"
    }
  ]
}

其他方法

虽然 Mutate、Search 和 SearchStream 是 Google Ads API 中最常见的方法，但还有许多特定方法可用于实现特定目的。REST 参考文档中介绍了所有服务及其 API。

协议缓冲区 RPC 到 REST 映射

所有服务端点（无论是使用 REST 还是 gRPC）最终都使用 proto3 接口定义语言在服务软件包的 .proto 文件中定义。

示例：ListAccessibleCustomers

例如，customer_service.proto 文件除了定义标准 Mutate 之外，还定义了 ListAccessibleCustomers 方法。它的 google.api.http 注释描述了该方法如何映射到 HTTP。它使用带自定义动词 listAccessibleCustomers 的 HTTP GET：

proto 复制代码 
rpc ListAccessibleCustomers(ListAccessibleCustomersRequest)
 returns (ListAccessibleCustomersResponse) { 
 option (google.api.http) = { 
 get: "/v15/customers:listAccessibleCustomers" 
  };
}

这将映射到 customers.listAccessibleCustomers REST 方法。

示例：CreateCustomerClient

customer_service.proto 中的另一个示例是 CreateCustomerClient 方法。其 google.api.http 注解采用自定义动词 createCustomerClient 来描述 HTTP POST：

proto 复制代码 
rpc CreateCustomerClient(CreateCustomerClientRequest)
 returns (CreateCustomerClientResponse) { 
 option (google.api.http) = { 
 post: "/v15/customers/{customer_id=*}:createCustomerClient" 
 body: "*" 
  };
  option (google.api.method_signature) = "customer_id,customer_client";
}

这将映射到 customers.createCustomerClient REST 方法。

示例

本指南包含一些在不使用客户端库的情况下直接调用 REST 端点的示例。

前提条件

以下示例应使用 curl 命令复制并粘贴到 bash shell 中。

您还需要开发者令牌、测试帐号访问权限以及至少包含一个客户帐号的 Google Ads 经理帐号。

重要提示 ：在这些示例中，我们假设您正在访问客户帐号 (CUSTOMER_ID)，该用户对直接管理客户帐号的经理帐号 (MANAGER_CUSTOMER_ID) 拥有管理员权限。如果您要直接访问单个客户帐号，请省略 login-customer-id 标头或将其设置为与 CUSTOMER_ID 相同的值。请注意，某些示例（如创建帐号）需要经理帐号。

环境变量

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

bash 复制代码 
$ API_VERSION="15"
DEVELOPER_TOKEN="iYZ11wCweJg5ZW-nyIsr-Q"
OAUTH2_ACCESS_TOKEN="ya29.a0AfB_byCM9Y7YQ6gvY61noDx0HR3wl_fZpwqxgpdj3bonWXY3KYZM1IqEp9P75DEKUHr6wMa_OoiaO85EvQc4NiUiithPyuELdkTxS8bJ82Jrrbhf3PXFp8arlAnWpP35gPK0ED2zFzpVqnIVxEsNZJMtroBY2KU1b3XeaCgYKAf0SARASFQGOcNnCaNe58rTu3-lfZviu_iLO6w0171"
MANAGER_CUSTOMER_ID="8573484547"
CUSTOMER_ID="3111469290"

其他可选对象 ID

下文中的部分示例适用于已存在的预算或广告系列。如果您有要用于这些示例的现有对象的 ID，请采用同样的方法配置。

bash 复制代码 
$ BUDGET_ID=BUDGET_ID
 CAMPAIGN_ID=CAMPAIGN_ID

否则，两个 Mutates - Createsexamples 会创建新的预算和广告系列。

搜索

查询实战宝典指南包含的许多报告示例对应于一些默认 Google Ads 屏幕，并且使用与本指南中相同的环境变量。我们的交互式查询构建器工具也是以交互方式构建自定义查询的绝佳资源。

分页

search 方法使用分页，在 query 旁边指定可调整的 pageSize 参数。

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'
"
}'
Google 复制代码 
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'
"
}'
Google 复制代码 
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）。

创建

此示例在单个请求中创建两项共享的广告系列预算。

bash 复制代码 
$ 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，您可以从上一步的输出中复制并粘贴。

bash 复制代码 
$ BUDGET_ID=BUDGET_ID

引用其他资源的资源是通过资源名称来实现的。下面制作的广告系列通过采用字符串值的资源名称来引用 campaignBudget。

bash 复制代码 
$ 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 操作更新现有对象的属性。下一个示例使用的是现有广告系列；您可以从上一步的输出中复制并粘贴。

bash 复制代码 
$ CAMPAIGN_ID=CAMPAIGN_ID

所有更新都需要 updateMask 字段，该字段是请求中应包含的 JSON 属性的逗号分隔列表，该字段应作为更新应用。系统会清除对象上 updateMask 中列出的但不存在于请求正文中的属性。updateMask 中未列出但请求正文中存在的属性都将被忽略。

bash 复制代码 
$ 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 操作指定对象的资源名称来移除对象。

bash 复制代码 
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，则当且仅当请求中的所有操作均有效时，请求中的所有操作才会成功。

下一个示例使用的是现有广告系列；您可以从创建示例输出结果中复制并粘贴。

bash 复制代码 
$ CAMPAIGN_ID=CAMPAIGN_ID

以下请求包含两个操作。第一个函数会尝试更改所提供的广告系列的出价策略，第二次尝试移除具有无效 ID 的广告系列。由于第二个操作会导致错误（广告系列 ID 无效），而且 partialFailure 设为 false，因此第一个操作也会失败，现有广告系列的出价策略也不会更新。

bash 复制代码 
$ 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）用作资源名称中的占位符，并在运行时用操作序列的结果动态填充。

bash 复制代码 
$ 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。系统会在经理帐号下创建新的客户帐号。

bash 复制代码 
$ 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 或客户帐号 ID。

bash 复制代码 
$ 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 编码（无论是否有内边距）。

此示例对 1 像素的 GIF 进行编码，以保持示例简洁。实际上，data 载荷要大得多。

您可以使用 base64 命令行实用程序（GNU 核心实用程序的一部分）对 1 像素的 GIF 图片进行编码。

bash 复制代码 
$ base64 1pixel.gif

在 API 请求中，以 data 属性的形式指定 base64 编码的值。

bash 复制代码 
$ 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'
      }
    }
  }
]
}"
相关推荐
Bruce_Liuxiaowei2 天前
谷歌量子计算机：开启计算新时代
google·量子计算
wuhanwhite3 天前
谷歌发布Gemini 2.0 Flash Thinking，全面超越o1-preview？
人工智能·google·gemini 2.0
黑马王子1312 天前
谷歌史上最强大模型-Gemini2.0震撼发布！以后世界都属于智能体？
人工智能·google
给自己做减法1 个月前
解决登录Google账号遇到手机上Google账号无法验证的问题
google
玄明Hanko1 个月前
Rust 为何能以 83% 的得分成为最受推崇的编程语言？
android·google·rust
阿达_优阅达1 个月前
用 Google Sheets 表格增强 Tableau 数据分析的 3 种玩法
google·数据分析·企业数字化转型·tableau·googlesheets
众乐认证1 个月前
Android Auto 不再用于旧手机
android·google·智能手机·android auto
黑心萝卜三条杠1 个月前
【Go语言】深入理解Go语言：并发、内存管理和垃圾回收
google·程序员·go
Just_Paranoid2 个月前
Android 虚拟化框架（AVF）指南
android·google·虚拟化·aosp·avf
Just_Paranoid2 个月前
虚拟化环境中的精简版 Android 操作系统 Microdroid
android·google·avf·microdroid
热门推荐
01〔AI 绘画〕Stable Diffusion 之 解决绘制多人或面部很小的人物时面部崩坏问题 篇02ARM学习（31）编译器对overlay方式的支持03玄机平台应急响应—webshell查杀04DisplayPort AltMode On Type-c协议_Ver2.0(学习笔记)05校验 GPT-4 真实性的三个经典问题：快速区分 GPT-3.5 与 GPT-4，并提供免费测试网站06Docker 夺命连环 15 问076个主流的工业3D管道设计软件08基于大语言模型（LLM）的合成数据生成、策展和评估的综述09(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明10树莓派 5 AI 套件（Hailo-8L）使用教程