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 接口 指南。

**注意**： 本指南介绍了 gRPC 和 REST 协议共有的结构和传输标头。

资源标识符

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

资源名称

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

要点： 如需了解所有 受支持的资源及其路径表示法 (resource_name)，请查看资源文档。其他服务也使用相同的 格式。

复合 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。

注意： 禁止在多个广告组之间共享 AdId。如果创建新的 AdGroupAd 来引用另一个广告组中的现有 AdId，则会失败并显示 AdGroupAdError.AD_SHARING_NOT_ALLOWED。

请求标头

这些是请求中随正文一起发送的 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 访问权限模型指南。

**关键术语**： **操作客户** 是指请求载荷中的客户 ID。 例如，在以下 CampaignBudgetService请求中，操作客户为1234567890:

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

设置 login-customer-id 相当于在登录后或点击右上角的用户头像后，在 Google Ads 界面中选择一个账号。 如果您不添加此标头，则默认使用操作客户 。

注意： 您可以通过发出 CustomerService.ListAccessibleCustomers 请求，检索可以使用 您的 OAuth 凭据 直接访问的账号列表。此请求类型不需要 login-customer-id，并且不会影响返回的客户列表。

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 请求。