API 调用结构

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

如果您使用客户端库与 API 进行互动，则无需操心底层请求的详细信息；但在进行测试和调试时，对它们有所了解还是很有用的。

Google Ads API 是一个带有 REST 绑定的 gRPC API。这意味着有两种方法可以调用此 API。

  1. [首选] 以协议缓冲区的形式创建请求的正文，使用 HTTP/2 将其发送到服务器，然后将响应反序列化到协议缓冲区，并解读结果。我们的文档大部分内容都介绍了如何使用 gRPC。

  2. [可选]将请求正文创建为 JSON 对象，使用 HTTP 1.1 将其发送到服务器，将响应反序列化为 JSON 对象，并解析结果。如需详细了解如何使用 REST，请参阅 REST 接口指南。

资源名称

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

复合 ID

如果某个对象的 ID 不具有全局唯一性，则系统会通过添加其父级 ID 和波浪号 (~) 来构造该对象的复合 ID。

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

  • AdGroupId（共 123）+ ~ + AdGroupAdId（共 45678）= 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/v17/customers/1234567890/campaignBudgets:mutate

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

已关联的客户 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 是一个字符串，用于唯一标识此请求。

上一页
资源元数据