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,具体如下:

  • 123AdGroupId + ~ + 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/v11/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-idAuthorization 标头:用于识别有权访问帐号 B 的用户的值的组合。

响应标头

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

request-id

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