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

API 限制和配额

Google Ads API 对 API 操作实施了限制,例如单个 mutate 请求中可发送的操作数量。下表总结了一些需要注意的重要限制和配额。

请求类型、限制和错误代码
分页请求 10,000 页 INVALID_PAGE_SIZE
使用基本访问权限的所有请求 每天 15,000 项 API 操作 RESOURCE_EXHAUSTED
Get 请求 每天 1,000 个请求 RESOURCE_EXHAUSTED
Mutate 请求 每个请求 5,000 项操作 TOO_MANY_MUTATE_OPERATIONS
规划服务请求 每秒 1 次查询 RESOURCE_EXHAUSTED
转化上传服务请求 每个请求 2,000 次转化 TOO_MANY_CONVERSIONS_IN_REQUEST
结算和帐号预算服务请求 每个 mutate 请求 1 项操作 TOO_MANY_MUTATE_OPERATIONS

API 的每天操作限制

API 的每天使用限制是根据每个开发者令牌执行的 API 操作数量确定的。API 操作是 get 请求和 mutate 操作的总和。API 的每天操作限制取决于开发者令牌的访问权限级别。有关每个访问权限级别的具体 API 操作限制的概要说明,请参见“访问权限级别和允许的用途”指南

超出这些限制的请求会被拒绝,并显示以下错误:RESOURCE_EXHAUSTED

gRPC 限制

所有 Google Ads API 客户端库均使用 gRPC 生成请求和响应。默认情况下,gRPC 的消息大小上限为 4 MB。此限制可能会被超越;例如,包含极多字段的搜索请求可能会生成大小超出 4 MB 的响应。要避免搜索请求超出此限制,您可以减少所选字段的数量或缩减页面大小。对于 mutate,请减少每个请求发送的操作数量。

超出此限制的请求不会生成 GoogleAdsError它们会在出现 gRPC 错误时生成错误,并显示 429 Resource Exhausted 错误。作为参考,请查看此 gRPC 错误代码和消息列表。

Get 请求

Get 请求(例如,对 CampaignService 使用 GetCampaigns() 方法)将每天使用限制与操作数量限制区分开来;“访问权限级别和允许的用途”指南中对操作数量限制进行了介绍。与每天操作不同,get 请求的限制不会因访问权限级别而异;所有开发者令牌(包括使用标准访问权限的开发者令牌)的限制均为每天 1,000 个 get 请求。与搜索请求不同,get 请求的开销很高,因为这种请求会检索所有属性数据。尽可能使用搜索请求,而不是 get 请求。

超出这些限制的请求会被拒绝,并显示以下错误:RESOURCE_EXHAUSTED

Mutate 请求

除了计入用户的每天操作配额外,mutate 请求还受到以下限制:

  • 每个 Mutate 请求不能超出 5,000 项操作。

返回 API 异常的请求

凡是被拒且显示 GoogleAdsFailure 的请求,均将计入用户的每天操作配额中。不过,虽已失败但未返回 GoogleAdsFailure 的请求可能是网络级错误导致的,所以不会计入用户的每天操作配额中,因为它们从未到达 API。例如,网络连接故障就会导致出现这样的请求。

搜索请求

搜索请求不会被视为与 get 请求相同,尽管两者都用于检索数据。因此,搜索请求仅受制于每天操作限制。

分页请求

分页请求(例如包含有效 next_page_token 的请求)不计入用户的每天操作配额。不过,包含过期或无效网页令牌的分页请求会生成异常,并计入每天操作配额。

已分页的请求(例如搜索请求)还受到以下限制:

  • 页面大小不能超过 10,000
    • 超出此限制的请求会被拒绝,并显示以下错误:INVALID_PAGE_SIZE

如需详细了解分页,请参阅将结果分页

规划服务

由于费用和复杂性较高,下列规划服务方法会受到不同于其他请求类型的限制。

转化上传服务

结算和帐号预算服务

  • 只能针对已配置为按月帐单结算的帐号执行 mutate 操作。
  • mutate 请求仅允许 1 项操作。
  • 您应该至少等待 12 小时,才能对同一帐号的预算订单再次做出更改。如果两次更改之间的时间不足 12 小时,那么可能导致无法恢复的失败,且这类失败只能由您的 Google Ads 客户代表解决。

其他类型的限制

在请求中使用一个包含太多项的重复字段(例如操作列表)可能会导致以下错误:REQUEST_SIZE_LIMIT_EXCEEDED。此错误消息也可能是由其他问题导致的。

如果您遇到此限制,又想在发出的请求中使用重复字段,最佳解决方案是尝试将操作列表部署在 mutate 请求中,以减少重复字段中的项的个数。