API 限制和配额

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

请求类型、限制和错误代码
测试访问权限级别的操作 每天针对测试账号执行 15,000 次 API 操作 RESOURCE_EXHAUSTED
具有“探索者”访问权限级别的操作 每天针对生产账号执行 2,880 次 API 操作
每天针对测试账号执行 15,000 次 API 操作 		RESOURCE_EXHAUSTED
具有基本访问权限级别的操作 每天针对测试账号和生产账号的 API 操作次数为 15,000 次 RESOURCE_EXHAUSTED
具有标准权限级别的操作 每天针对测试账号和生产账号的 API 操作次数不受限制 不适用
Mutate 请求 每个请求 10,000 次 mutate 操作 TOO_MANY_MUTATE_OPERATIONS
规划服务请求 每秒 1 次查询 RESOURCE_EXHAUSTED
转化上传服务请求 每个请求 2,000 次转化 TOO_MANY_CONVERSIONS_IN_REQUEST
结算和账号预算服务请求 每个 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 请求还不能包含超过 10,000 个 mutate 操作。超出此限制的请求会被拒绝，并显示以下错误：TOO_MANY_MUTATE_OPERATIONS。

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

搜索请求

Search 或 SearchStream 请求计为一次操作，并计入用户的每日操作配额。无论批次数量是多少，一个 SearchStream 请求都算作一次 API 操作。

分页请求

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

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

其他类型的请求

不是 Mutate、Search 或 SearchStream 请求的请求会作为一次操作计入用户的每日操作配额。

以下是一些此类请求的示例：

返回 API 异常的请求

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

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

关键字规划服务

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

创建关键字规划时，请注意这些限制。

关键字方案对象 数量上限
每个账号 KeywordPlan 10000
每 KeywordPlan KeywordPlanAdGroup 200
每 KeywordPlan KeywordPlanAdGroupKeyword 10000
每个KeywordPlan最多可添加 KeywordPlanCampaignKeyword 个否定关键字 1000
每 KeywordPlan KeywordPlanCampaign 1

受众群体分析服务

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

转化上传服务

转化调整上传服务

转化价值规则

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

结算和账号预算服务

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

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

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

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

  • 您应等待至少 12 小时，然后再对同一账号的账号预算（AccountBudget 或 AccountBudgetProposal）进行更改。如果两次更改之间的时间不足 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 总限额为 10 万（一个 OfflineUserDataJob 可以接受多个 AddOfflineUserDataJobOperationsRequest 调用，建议每个作业最多执行 100 万次操作）。对于使用 UploadUserDataRequest (UserDataService.UploadUserData) 的同步上传，每个请求最多只能包含 10 个操作，并且整个请求中的 user_identifiers 总数不得超过 100。

其他类型的限制

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

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

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

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