Google Ads API 对 API 操作施加了限制,例如限制可在单个 mutate 请求中发送的操作数量。下表总结了需要注意的一些重要限制和配额。
请求类型、限制和错误代码 | |||
---|---|---|---|
分页请求 | 每页 10,000 行 |
INVALID_PAGE_SIZE
|
|
具有基本访问权限的操作 | 每天 15,000 次 API 操作 |
RESOURCE_EXHAUSTED
|
|
Mutate 请求 | 每个请求 10,000 次操作 |
TOO_MANY_MUTATE_OPERATIONS
|
|
Planning Service 请求 | 1 QPS |
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
。
下面概述了特定服务和请求类型的其他限制和注意事项。
搜索请求
一个 Search
或 SearchStream
请求在用户的每日操作配额中计为一次操作。无论批次数量是多少,一个 SearchStream
请求都计为一个 API 操作。
分页请求
分页请求(例如,包含有效 next_page_token
的请求)不计入用户的每日操作配额。但是,包含过期或无效页面令牌的分页请求将产生异常,并将计入每日操作配额。
分页请求(例如搜索请求)也要遵守 Page size cannot exceed 10,000 rows
限制,如果违反此限制,则请求将被拒绝,并显示以下错误:INVALID_PAGE_SIZE
。
如需详细了解分页,请参阅将结果分页。
其他类型的请求
如果请求不是 Get
、Mutate
、Search
或 SearchStream
请求,则在用户的每日操作配额中计为一次操作。
此类要求的一些示例包括:
BatchJobService.ListMutateJobResults
ConversionUploadService.UploadCallConversions
ConversionUploadService.UploadClickConversions
OfflineUserDataJobService.AddOfflineUserDataJobOperations
OfflineUserDataJobService.CreateOfflineUserDataJob
UserDataService.UploadUserData
返回 API 异常的请求
使用 GoogleAdsFailure
拒绝的请求仍会计入用户的每日操作配额。
失败但未返回 GoogleAdsFailure
的请求(例如由于网络级错误引起的请求)不会计入用户的日常操作配额,因为这些请求永远不会到达服务。例如,网络连接失败。
规划服务
由于费用和复杂性较高,下列规划服务方法会受到不同于其他请求类型的限制。
限制为每个客户 ID 或开发者令牌每秒 1 个请求:
KeywordPlanService.GetKeywordPlan
KeywordPlanService.GenerateHistoricalMetrics
KeywordPlanService.GenerateForecastMetrics
违反这些限制的请求会被拒绝,并显示以下错误:
RESOURCE_EXHAUSTED
。1 QPS 按每 60 秒 60 次请求计算。
创建关键字方案时,请注意这些限制。
关键字方案对象 | 数量上限 |
---|---|
每个账号 KeywordPlan |
10000 |
每 KeywordPlan KeywordPlanAdGroup |
200 |
每 KeywordPlan KeywordPlanAdGroupKeyword |
10000 |
KeywordPlanCampaignKeyword (否定关键字) |
1,000 |
每 KeywordPlan KeywordPlanCampaign |
1 |
转化上传服务
每个请求不得超过 2,000 次致电或点击转化:
超出这些限制的请求会被拒绝,并显示以下错误:
TOO_MANY_CONVERSIONS_IN_REQUEST
。
转化调整项上传服务
每个请求最多可包含 2,000 项转化调整:
超出这些限制的请求会被拒绝,并显示以下错误:
TOO_MANY_ADJUSTMENTS_IN_REQUEST
。
结算和账号预算服务
只能针对已配置为按月账单结算的账号执行 mutate 操作。
超出此限制的请求会被拒绝,并显示以下错误:
MUTATE_NOT_ALLOWED
。mutate 请求仅允许 1 项操作。
超出此限制的请求会被拒绝,并显示以下错误:
TOO_MANY_MUTATE_OPERATIONS
。您应该至少等待 12 小时,才能对同一帐号的预算订单再次进行更改。如果两次更改之间的时间不足 12 小时,那么可能导致无法恢复的失败,且这类失败只能由您的 Google Ads 客户代表解决。
向客户账号发送的邀请
您可以通过 CustomerUserAccessService
邀请新用户加入现有的客户帐号。由于此功能会向其他用户发送邀请电子邮件,因此可能会被滥用,因此其行为存在限制:
对于同一客户账号,用户只能收到一个待处理的邀请。如果后续请求向已有待处理邀请的用户发送邀请,系统会返回以下错误:
ACCESS_INVITATION_ERROR_EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION
。客户帐号每次的待处理邀请不能超过 70 个。 如果发送的请求导致超出此值,则系统会返回以下错误:
ACCESS_INVITATION_ERROR_PENDING_INVITATIONS_LIMIT_EXCEEDED
。
用户数据
用户数据通过 UserDataService
和 OfflineUserDataJobService
进行管理。在指定的创建/移除 UserData
操作中,每组 user_identifiers
都应特定于单个用户。
如需强制执行此要求,当 UserData
集中的 user_identifiers
超过 20 个时,系统会返回 OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS
或 UserDataError.TOO_MANY_USER_IDENTIFIERS
错误。
其他类型的限制
如果一个重复字段(例如操作列表)在请求中的项目过多,就可能会导致以下错误:REQUEST_SIZE_LIMIT_EXCEEDED
。此错误消息也可能是由其他问题导致的。
如果您遇到此限制,并且正在发出的请求使用重复字段,请尝试在 mutate 请求中部署操作列表,以减少重复字段中的项数。
进行 GAQL 查询时,IN
子句中的条目数上限为 20,000。如果超出该限制,系统会返回 FILTER_HAS_TOO_MANY_VALUES
错误。