Google Ads API is returning to beta status. Please read our blog post for more details.

API 调用结构

本指南介绍了 API 调用的元素,并演示了如何使用 cURL 进行基本调用。

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

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

  1. [首选]协议缓冲区的形式创建请求的正文,使用 HTTP/2 将其发送到服务器,然后将响应反序列化到协议缓冲区,并解析结果。

  2. [可选]JSON 对象的形式创建请求的正文,使用 HTTP 1.1 将其发送到服务器,然后将响应反序列化为 JSON 对象,并解析结果。

端点

这指的是 Google Ads API 服务器端点,所有请求都发送到这里:

https://googleads.googleapis.com

请求网址

请求网址包含端点和网址后缀两个部分。为方法构建请求网址包括以下步骤:

  1. 获取服务协议文件中的 HTTP 方法名称和网址模板后缀。
  2. 将网址模板后缀附加到服务器端点。
  3. 对后缀进行必要的参数替换。

示例

要获取资源的网址,请参考使用其 resource_name。以 CampaignBudget 为例,resource_name 描述的路径为

customers/{customer_id}/campaignBudgets/{budget_id}

如果您想调用 CampaignBudgetService.MutateCampaignBudgets 方法(使用 HTTP POST),则可以将该网址转换为

/v1/customers/{customer_id}/campaignBudgets:mutate

再将其中的 {customer_id} 替换为 Google Ads 客户 ID,然后将替换完毕的网址附加到 Google Ads API 服务器端点之后,即可构建出此方法的完整网址端点。

综上,对于 ID 为 123-456-7890 的客户,完整的网址端点将如下所示:

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

复合 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/v1/customers/1234567890/campaignBudgets:mutate

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

响应标头

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

request-id

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