API 限制和配额

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

请求类型、限制和错误代码
使用测试访问权限级别的操作 每天针对测试账号执行 15,000 次 API 操作 RESOURCE_EXHAUSTED
具有 Explorer 访问权限级别的操作 每天针对生产账号执行 2,880 次 API 操作
每天针对测试账号执行 15,000 次 API 操作 		RESOURCE_EXHAUSTED
基本访问权限级别的操作 每天针对测试账号和生产账号执行 15,000 次 API 操作 RESOURCE_EXHAUSTED
具有标准访问权限级别的操作 每天对测试账号和生产账号执行的 API 操作次数不受限制 不适用
mutate 请求 每个请求 10,000 次 mutate 操作 TOO_MANY_MUTATE_OPERATIONS
规划服务约叫 每秒 1 次查询 RESOURCE_EXHAUSTED
转化上传服务请求 每个请求 2,000 次转化 TOO_MANY_CONVERSIONS_IN_REQUEST
Billing and Account Budget Service 请求 每个 mutate 请求 1 项操作 TOO_MANY_MUTATE_OPERATIONS

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/HTTP 429）错误。请参阅 gRPC 错误代码和消息列表。

Mutate 请求

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

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

搜索请求

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

分页请求

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

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

其他类型的请求

非 Mutate、Search 或 SearchStream 请求的请求会计为用户每日操作配额中的一项操作。

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

返回 API 异常的请求

被拒绝并返回 GoogleAdsFailure 的请求仍会计入用户的每日操作配额。

失败但未返回 GoogleAdsFailure 的请求（例如由于网络级错误而失败的请求）不会计入用户的每日操作配额，因为这些请求永远不会到达服务。例如，网络连接失败。

关键字规划工具服务

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

创建关键字方案时，请注意以下限制。

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

受众群体分析服务

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

转化上传服务

转化调整上传服务

转化价值规则

如果账号已存在 attachment_type 为 CUSTOMER 的 ConversionValueRuleSet，则您必须将所有新的转化价值规则添加到该集合中，这些规则才能生效。如果不存在此类转化价值规则集，您必须创建一个，并按照创建规则集中的说明向其中添加转化价值规则。

结算和账号预算服务

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

    违反此限制的请求会被拒绝，并显示错误：MUTATE_NOT_ALLOWED。

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

    违反此限制的请求会被拒绝，并显示错误：TOO_MANY_MUTATE_OPERATIONS。

  • 对同一账号进行账号预算（AccountBudget 或 AccountBudgetProposal）更改时，两次更改之间应至少间隔 12 小时。如果两次更改之间的时间不足 12 小时，那么可能导致无法恢复的失败，且这类失败只能由您的 Google Ads 客户代表解决。

客户账号邀请

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

用户数据

用户数据通过 UserDataService 和 OfflineUserDataJobService 进行管理。

create 或 remove 操作中的每个 UserData 对象都与单个最终用户相关。单个 UserData 对象中的 user_identifiers 字段最多只能包含 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 操作的信息关联并合并到正确的最终用户个人资料中。

如果您依赖经过哈希处理的邮箱或电话号码等个人身份信息，请确保这些信息已根据 Google Ads API 要求（SHA-256、小写、无空格）进行标准化和哈希处理，以防止关联失败。

例如，如果用户有 30 个邮箱，您可以发送两个共享一个 third_party_user_id 的 UserData 对象（将 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 项操作和 100 个 user_identifiers。

其他类型的限制

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

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

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

上一页
概览
下一页
系统限制