API 调用结构

本指南介绍了所有 API 调用的常见结构。

如果您使用客户端库与 API 进行互动，则无需了解底层请求的详细信息。不过，在进行测试和调试时，了解一些 API 调用结构还是很有用的。

Google Ads API 是一个带有 REST 绑定的 gRPC API。这意味着，您可以通过两种方式调用该 API。

首选：

  1. 将请求正文创建为 协议缓冲区。

  2. 使用 HTTP/2 将其发送到服务器。

  3. 将响应反序列化为协议缓冲区。

  4. 解析结果。

我们的大部分文档都介绍了如何使用 gRPC。

可选：

  1. 将请求正文创建为 JSON 对象。

  2. 使用 HTTP 1.1 将其发送到服务器。

  3. 将响应反序列化为 JSON 对象。

  4. 解析结果。

如需详细了解如何使用 REST，请参阅 REST 接口指南 。

资源名称

API 中的大多数对象都由其资源名称字符串标识。在使用 REST 接口时，这些字符串也充当网址。如需了解其 结构，请参阅 REST 接口的 资源名称。

复合 ID

如果对象的 ID 不具有全局唯一性，则在构建该对象的复合 ID 时，要在前面加上其父级的 ID 和波浪号 (~)。

例如，某个广告组广告 ID 不具有全局唯一性，我们需要在前面加上其父级对象（即广告组）的 ID，从而形成具有唯一性的复合 ID，具体如下：

  • 123 的 AdGroupId + ~ + 45678 的 AdGroupAdId = 123~45678 的复合广告 组广告 ID。

请求标头

这指的是请求中伴随正文的 HTTP 标头（或 grpc 元数据）：

授权

您必须以 Authorization: Bearer YOUR_ACCESS_TOKEN 格式添加 OAuth2 访问令牌，以标识代表 客户操作的经理账号或直接管理自己账号的广告客户。有关如何获取访问令牌的说明，请阅读 OAuth2 指南。访问令牌在获得后一小时之内有效；过期后，您可以刷新访问令牌来获取新令牌。 请注意，我们的客户端库会自动刷新过期令牌。

如果您遇到授权错误，请确保您使用的是正确的凭据，并且拥有足够的权限。USER_PERMISSION_DENIED 错误表示经过身份验证的用户可能无权访问请求中指定的客户账号。如需详细了解如何管理 权限，请参阅 Google Ads 访问 权限级别。

developer-token

开发者令牌是由 22 个字符组成的字符串，用于唯一标识 Google Ads API 开发者。开发者令牌字符串的示例为 ABcdeFGH93KL-NOPQ_STUv。开发者令牌应以 developer-token : ABcdeFGH93KL-NOPQ_STUv 格式添加。

login-customer-id

这是在请求中使用的授权客户的客户 ID，它不带连字符 (-)。如果您通过经理账号访问客户账号，则此标头是必填字段，且必须设置为经理账号的客户 ID。 如果您通过经理账号进行身份验证时未能添加 login-customer-id，则会导致 AuthorizationError.USER_PERMISSION_DENIED 错误。如需详细了解此类错误 ，请查看常见错误。如需详细了解如何解决账号访问权限问题，请参阅 OAuth 访问权限模型指南。

https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate

设置 login-customer-id 的作用就相当于在登录或点击右上角的个人资料图片后选择 Google Ads 界面中的账号。如果您未添加此标头，则它默认为执行操作的客户 。

linked-customer-id

此标头是必填字段，合作伙伴（例如第三方应用分析提供商或数据合作伙伴）在对关联的 Google Ads 账号执行操作时会使用此标头。此标头 必须指定具有 产品关联的 Google Ads 账号的客户 ID。

假设合作伙伴需要根据产品关联对 Google Ads 账号进行 API 调用。

  • 广告客户：由 API 调用管理或更新的 Google Ads 账号。广告客户账号的 ID 在请求中指定。在 REST 中，这是 customerId 路径参数（例如 customers/1111111111/...），而在 gRPC 中，这是请求中的 customer_id 字段。
  • 合作伙伴：合作伙伴账号（例如第三方应用分析 提供商或数据合作伙伴）。
  • 关联的账号：与合作伙伴建立了 产品关联的 Google Ads 账号，授予合作伙伴对广告客户的访问权限。

有权访问合作伙伴的用户会进行 API 调用，以对广告客户中的实体执行操作（例如，上传转化或管理用户名单）。关联的账号可以是广告客户本身，也可以是广告客户的经理账号。

请求标头必须按如下方式设置：

  • Authorization：有权访问合作伙伴的用户的 OAuth2 令牌。
  • developer-token：API 应用的开发者令牌，通常与合作伙伴相关联。
  • login-customer-id：合作伙伴的客户 ID。经过身份验证的用户必须有权访问此账号。
  • linked-customer-id：关联的账号的客户 ID。此标头表示此请求的授权依赖于关联的账号与合作伙伴的产品关联。

关联场景有两种：

  • 如果广告客户与合作伙伴有直接的产品关联，则关联的账号是广告客户，并且 linked-customer-id 必须设置为广告客户的客户 ID。
  • 如果广告客户由与合作伙伴有产品关联的经理账号管理，则关联的账号是经理账号，并且 linked-customer-id 必须设置为经理的客户 ID。

示例 1：直接关联

如果广告客户 1111111111 与合作伙伴 2222222222 有直接关联，并且 API 调用以 customers/1111111111/... 为目标：

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

示例 2：经理关联

如果广告客户 1111111111 由经理 3333333333 管理，经理 3333333333 与合作伙伴 2222222222 有关联，并且 API 调用以 customers/1111111111/... 为目标：

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

响应标头

以下标头（或 grpc trailing-metadata）随响应正文一起返回。出于调试目的考虑，我们建议您记录这些值。

request-id

request-id 是对请求进行唯一标识的字符串。

上一页
资源元数据