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 指南。访问令牌在获得后一小时之内有效；过期后，您可以刷新访问令牌来获取新令牌。请注意，我们的客户端库会自动刷新过期令牌。

developer-token

开发者令牌是由 22 个字符组成的字符串，用于唯一标识 Google Ads API 开发者。开发者令牌字符串示例如下：ABcdeFGH93KL-NOPQ_STUv。开发者令牌应采用 developer-token : ABcdeFGH93KL-NOPQ_STUv 的形式。

login-customer-id

这是在请求中使用的授权客户的客户 ID，它不带连字符 (-)。如果您通过经理账号访问客户账号，则此标头是必填字段，且必须设置为经理账号的客户 ID。

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

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

linked-customer-id

此标头仅供 [第三方应用分析工具提供商将转化数据上传到关联的 Google Ads 账号时使用。

假设账号 A 的用户通过 ThirdPartyAppAnalyticsLink 向账号 B 授予对其实体的读取和修改权限。关联后，账号 B 的用户可以针对账号 A 进行 API 调用，具体取决于关联提供的权限。在这种情况下，对账号 A 的 API 调用权限由指向账号 B 的第三方关联决定，而不是由其他 API 调用中使用的经理账号关系决定。

第三方应用分析工具提供商会按如下方式进行 API 调用：

  • linked-customer-id：上传数据的第三方应用分析账号（账号 B）。
  • customer-id：上传数据到的 Google Ads 账号（账号 A）。
  • login-customer-id 和 Authorization 标头：用于标识有权访问账号 B 的用户的值组合。

响应标头

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

request-id

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

上一页
资源元数据