API 限制和配额

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

请求类型、限制和错误代码
具有 Explorer 访问权限级别的操作	针对生产账号每天 2,880 项 API 操作 针对测试账号每天 15,000 项 API 操作	RESOURCE_EXHAUSTED
具有基本访问权限级别的操作	针对测试账号和生产账号每天 15,000 项 API 操作	RESOURCE_EXHAUSTED
Mutate 请求	每个请求 10,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，但我们的客户端库将消息大小上限设置为 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 的请求）不计入用户的每天操作配额。 不过，包含过期或无效网页令牌的分页请求会生成异常，并计入每天操作配额。

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

其他类型的请求

如果请求不是 Get、Mutate、Search 或 SearchStream 请求 ，则计入用户的每天操作配额时，算作一项操作。

此类请求的一些示例包括：

• BatchJobService.ListMutateJobResults
• ConversionUploadService.UploadCallConversions
• ConversionUploadService.UploadClickConversions
• OfflineUserDataJobService.AddOfflineUserDataJobOperations
• OfflineUserDataJobService.CreateOfflineUserDataJob
• UserDataService.UploadUserData

返回 API 异常的请求

凡是被拒且显示 GoogleAdsFailure 的请求，仍将计入用户的每天操作配额中。

不过，虽已失败但未返回 GoogleAdsFailure 的请求（例如网络级错误导致的请求）不会计入用户的每天操作配额中，因为这些请求从未到达服务。例如，网络连接故障就会导致出现这样的请求。

关键字规划服务

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

• 限制为每个客户 ID 每秒 1 个请求：

  • KeywordPlanIdeaService.GenerateKeywordIdeas
  • KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • KeywordPlanIdeaService.GenerateKeywordForecastMetrics

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

• 每秒 1 次查询的计算方式为每 60 秒 60 个请求。

• 限制为每个客户 ID 每秒 2 个请求：

  • KeywordPlanIdeaService.GenerateAdGroupTheme

创建关键字方案时，请注意这些限制。

关键字方案对象	数量上限
KeywordPlan 每个账号	10,000
KeywordPlanAdGroup 每 KeywordPlan	200
KeywordPlanAdGroupKeyword 每个 KeywordPlan	10,000
KeywordPlanCampaignKeyword （否定关键字）	1,000
KeywordPlanCampaign 每个 KeywordPlan	1

受众群体分析服务

AudienceInsightsService 中的以下方法会受到特定的配额限制。

• 限制为每个客户 ID 每天大约 200 个请求：
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• 限制为每个开发者令牌每秒 2 个请求：
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

转化上传服务

• 限制为每个请求 2,000 次通话或点击转化：

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

  超出这些限制的请求会被拒绝，并显示以下错误： TOO_MANY_CONVERSIONS_IN_REQUEST。

转化调整上传服务

• 限制为每个请求 2,000 次转化调整：

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  超出这些限制的请求会被拒绝，并显示以下错误： TOO_MANY_ADJUSTMENTS_IN_REQUEST。

转化价值规则

• 限制为每个账号 100,000 条转化价值规则。

  超出此限制的请求会被拒绝，并显示以下错误： ResourceCountLimitExceededError.ACCOUNT_LIMIT。

如果账号已存在 ConversionValueRuleSet 且 attachment_type 为 CUSTOMER，您必须将 所有新的转化价值规则添加到该规则集中，这些规则才会生效。如果不存在此类转化价值规则集，您必须创建一个，然后将您的转化价值规则添加到其中，如 创建规则集中所述。

结算和账号预算服务

• 只能针对已配置为按月账单结算的账号执行 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 对象在 create 或 remove 操作中与 单个最终用户相关。user_identifiers 字段在单个 UserData 对象中最多只能包含 20 个标识符。如果单个 UserData 对象超出此 限制，则会导致 OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS 或 UserDataError.TOO_MANY_USER_IDENTIFIERS 错误。

处理具有超过 20 个标识符的用户

如果单个最终用户拥有超过 20 个需要上传的标识符，您应将这些标识符分布在多个 UserData 对象中。为确保 Google 可以将所有这些标识符与同一最终用户相关联，该用户的每个 UserData 对象都必须至少包含一个通用 user_identifier，例如相同的 hashed_email、hashed_phone_number 或 third_party_user_id。Google 会使用这些共享标识符将来自单独 UserData 操作的信息关联并合并到正确的最终用户个人资料中。

如果您依赖于 PII（例如经过哈希处理的电子邮件地址或电话号码），请确保它们已按照 Google Ads API 要求（SHA-256、小写、无空格）进行规范化和哈希处理，以防止关联失败。

例如，如果用户有 30 个电子邮件地址，您可以发送两个 UserData 对象。

• UserData 1：{third_party_user_id: "user123", hashed_email: "email1@...", ... hashed_email: "email19@..."}
• UserData 2: {third_party_user_id: "user123", hashed_email: "email20@...", ... hashed_email: "email30@..."}

单个 OfflineUserDataJob 中所有操作的 user_identifiers 总数限制仍为 100,000。

其他类型的限制

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

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

执行 GAQL 查询时，IN 子句中的项数上限为 20,000。如果您超出此限制，系统会返回 FILTER_HAS_TOO_MANY_VALUES 错误。