API 限制和配额

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

请求类型、限制和错误代码
分页请求 每页 10,000 行 INVALID_PAGE_SIZE
具有基本访问权限的操作 每天 15,000 次 API 操作 RESOURCE_EXHAUSTED
Mutate 请求 每个请求 10,000 次操作 TOO_MANY_MUTATE_OPERATIONS
Planning 服务请求 QPS 为 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,但我们客户端库将消息大小上限设置为 64 MB,以提高效率。

响应不得超过此限制。例如,包含大量字段的搜索请求可能会生成大小超过 64 MB 的响应。为避免此限制,您可以减少所选字段的数量、缩减页面大小或使用流式传输。对于 mutate,请减少每个请求发送的操作。

超出此限制的请求不会生成 GoogleAdsError,但会生成 429 Resource Exhausted gRPC 错误。请参阅 gRPC 错误代码和消息列表

Mutate 请求

除了计入用户的每日操作配额之外,每个 mutate 请求包含的操作数量不能超过 10,000 次。

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

下文概述了特定服务和请求类型的其他限制和注意事项。

搜索请求

在用户的每日操作配额中,一个 SearchSearchStream 请求计为一次操作。无论批次数量是多少,一个 SearchStream 请求都计为一个 API 操作。

分页请求

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

分页的请求(例如搜索请求)也受 Page size cannot exceed 10,000 rows 限制的约束,如果违反此限制,则会被拒绝,并显示以下错误:INVALID_PAGE_SIZE

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

其他类型的请求

如果请求不是 GetMutateSearchSearchStream 请求,将计为一次操作,并计入用户的每日操作配额。

此类要求的示例包括:

返回 API 异常的请求

GoogleAdsFailure 拒绝的请求仍计入用户的每日操作配额。

失败但未返回 GoogleAdsFailure 的请求(例如因网络级错误导致的请求)不会计入用户的每日操作配额,因为此类请求永远不会到达服务。例如,网络连接失败。

规划服务

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

创建关键字方案时,请谨记这些限制。

关键字方案对象 数量上限
每个账号 KeywordPlan 10000
KeywordPlanAdGroup/KeywordPlan 200
KeywordPlanAdGroupKeyword/KeywordPlan 10000
KeywordPlanCampaignKeyword(否定关键字) 1,000
KeywordPlanCampaign/KeywordPlan 1

转化上传服务

转化调整项上传服务

结算和账号预算服务

  • 只能针对已配置为按月账单结算的账号执行 mutate 操作。

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

  • mutate 请求只允许执行1 项操作。

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

  • 您应该至少等待 12 小时,才能对同一帐号的预算订单再次做出更改。如果两次更改之间的时间不足 12 小时,那么可能导致无法恢复的失败,且这类失败只能由您的 Google Ads 客户代表解决。

客户账号邀请

可以通过 CustomerUserAccessService 邀请新用户访问现有客户帐号。由于此功能会向其他用户发送电子邮件邀请,因此它可能会被滥用,因此其行为存在一些限制:

用户数据

用户数据通过 UserDataServiceOfflineUserDataJobService 进行管理。在指定的创建/移除 UserData 操作中,每组 user_identifiers 应特定于单个用户。

为此,当 UserData 集中的 user_identifiers 超过 20 个时,系统会返回 OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERSUserDataError.TOO_MANY_USER_IDENTIFIERS 错误。

其他类型的限制

如果请求中包含的重复字段(例如操作列表)包含太多项,则可能会导致以下错误:REQUEST_SIZE_LIMIT_EXCEEDED。此错误信息也可能是由其他问题造成的。

如果您遇到此限制,并且正在发出使用重复字段的请求,请尝试在 mutate 请求中部署操作列表,以减少重复字段中的项目数。

在进行 GAQL 查询时,IN 子句中的项数上限为 20000。如果超过该限制,系统会返回 FILTER_HAS_TOO_MANY_VALUES 错误。