API 限制和配额

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

API 的每天操作限制

API 的每天用量限制取决于 Google Cloud 项目执行的 API 操作数 。API 操作是 Search 和 SearchStream 请求、单个 mutate 操作和其他服务 请求的总和。API 的每天操作限制取决于 Google Cloud 项目的 API 访问权限级别。访问权限级别和 允许的使用指南概述了每个访问权限级别的具体 API 操作限制 。

违反这些限制的请求会被拒绝，并显示以下错误： RESOURCE_EXHAUSTED.

gRPC 限制

所有 Google Ads API 客户端库都使用 gRPC 生成请求和响应。默认情况下，gRPC 的消息大小为 4 MB，但我们的客户端库将最大消息大小设置为 64 MB ，以提高效率。

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

违反此限制的请求不会生成 GoogleAdsError，但会生成 RESOURCE_EXHAUSTED（gRPC 代码8 / HTTP429）错误。请参阅 gRPC 错误代码和消息列表。

Mutate 请求

除了计入用户的每天操作配额外，mutate 请求还不能包含超过 10,000 次 mutate 操作。 违反此限制的请求会被拒绝，并显示以下错误： TOO_MANY_MUTATE_OPERATIONS。

接下来将概述针对特定服务和请求类型的其他限制和注意事项。

搜索请求

Search 或 SearchStream 请求会计入用户的 每天操作配额，算作一次操作。无论批次数量如何，一个 SearchStream 请求都算作一次 API 操作。

分页请求

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

如需详细了解分页，请参阅对结果进行分页。

其他类型的请求

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

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

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

返回 API 异常的请求

被拒绝并显示 GoogleAdsFailure 的请求仍会计入用户的每天操作配额。

失败但未返回 GoogleAdsFailure 的请求（例如网络级错误导致的请求）不会计入用户的每天操作配额，因为这些请求永远不会到达服务。网络连接失败就是这种情况的一个示例。

关键字规划工具服务

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

• 每个客户 ID 每秒最多只能发出 1 个请求：

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

  违反这些限制的请求会被拒绝，并显示以下错误： RESOURCE_EXHAUSTED.

• 1 QPS 的计算方式为每 60 秒 60 个请求。

• 每个客户 ID 每秒最多只能发出 2 个请求：

  • KeywordPlanIdeaService.GenerateAdGroupThemes

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

受众群体分析服务

以下方法在 AudienceInsightsService中受特定 配额限制。

• 每个客户 ID 每天最多只能发出大约 200 个请求：
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• 每个 Google Cloud 项目每秒最多只能发出 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 小时，才能对账号预算 （AccountBudget 或 AccountBudgetProposal）进行更改。如果两次更改之间的时间不足 12 小时，那么可能导致无法恢复的失败，且这类失败只能由您的 Google Ads 客户代表解决。

客户账号邀请

可以使用 CustomerUserAccessInvitationService邀请新用户加入现有客户账号。 由于此功能会向其他用户发送邮件邀请，因此可能会被滥用，并且其行为受到以下限制：

• 用户不能收到针对同一客户账号的多个待处理邀请。如果后续请求向已收到待处理邀请的用户 发送邀请，系统会返回以下错误： EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION。

• 客户账号一次最多只能有 70 个待处理的邀请。如果发送的请求导致超出此值，系统会返回以下错误 ： 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 对象，这两个对象共享一个通用 third_party_user_id（将 thirdPartyUserId 以及电子邮件地址 1 到 19 放在第一个对象中，以不超过 20 个标识符的限制；将 thirdPartyUserId 以及电子邮件地址 20 到 30 放在第二个对象中）：

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

单个 AddOfflineUserDataJobOperationsRequest中所有操作的user_identifiers总数限制为 100,000（一个 OfflineUserDataJob可以接受多个 AddOfflineUserDataJobOperationsRequest调用，建议每个作业最多执行 1,000,000 次操作）。对于使用 UploadUserDataRequest (UserDataService.UploadUserData) 进行的同步上传，每个请求最多只能执行 10 次操作，并且整个请求中的 user_identifiers 总数不得超过 100 个。

其他类型的限制

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

如果您遇到此限制，并且发出的请求使用了重复字段，请尝试减少重复字段中的项数，方法是将操作列表拆分到多个 mutate 请求中。

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