API 调用结构

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

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

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

首选：

  1. 将请求正文创建为 协议缓冲区。
  2. 使用 HTTP/2 将其发送到服务器。
  3. 将响应反序列化为协议缓冲区。
  4. 解读分析结果。

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

可选：

  1. 将请求正文创建为 JSON 对象。
  2. 使用 HTTP 1.1 将其发送到服务器。
  3. 将响应反序列化为 JSON 对象。
  4. 解读分析结果。

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

资源标识符

Google Ads API 中的对象使用结构化资源名称和复合标识符进行寻址。

资源名称

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

复合 ID

如果对象的 ID 不是全局唯一的，则通过在其父级 ID 前面加上波浪号 (~) 来构建该对象的复合 ID。

例如，AdGroupAd 的资源名称模式为 customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}。由于其复合标识符结合了父级广告组 ID (ad_group.id) 和底层广告 ID (ad_group_ad.ad.id)，因此我们在广告 ID 前面加上广告组 ID：

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

请求标头

这些是请求中随正文一起发送的 HTTP 标头（或 gRPC 元数据） ：

授权

您必须以 Authorization: Bearer YOUR_ACCESS_TOKEN 的形式添加 OAuth 2.0 访问令牌，以标识代表 客户执行操作的经理账号，或直接管理自己账号的广告客户。如需了解如何 检索访问令牌，请参阅 OAuth2 指南。访问令牌在获取后一小时内有效；过期后，请刷新访问令牌以检索新令牌。请注意，我们的客户端库会自动刷新过期的令牌。

如果您遇到授权错误，请确保您使用的是正确的凭据，并且拥有足够的权限。USER_PERMISSION_DENIED 错误表示经过身份验证的用户可能无权访问请求中指定的客户账号。如果您的 Google Cloud 项目仅获批 Test 访问权限，并且您发送的请求以生产账号为目标，则 API 会在 v25 及更高版本中返回 AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION（或在 v24 及更低版本中返回 AuthorizationError.ACTION_NOT_PERMITTED）。 如需详细了解如何管理 权限，请参阅Google Ads 访问权限级别。

login-customer-id

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

https://googleads.googleapis.com/v26/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：有权访问合作伙伴的用户所使用的 OAuth 2.0 访问令牌。
  • 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
login-customer-id: 2222222222
linked-customer-id: 1111111111

示例 2：经理关联

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

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

响应标头

以下标头（或 gRPC 尾部元数据）会随响应正文一起返回 。我们建议您记录这些值以进行调试。

request-id

request-id 是用于唯一标识此请求的字符串。在与支持团队联系时，请提供此值，以帮助排查失败或意外的 API 请求。

上一页
资源元数据