本文档列出了适用于 Merchant API 的配额。
Merchant API 使用配额来帮助确保为所有用户提供稳定、公平的环境。配额可防止任何单个 API 用户对系统造成过大负载，从而确保高性能。了解这些配额对于管理商品数据以及在 Google 上扩展业务规模至关重要。
一般概念
Merchant API 配额通过配额组进行管理。
API 方法会映射到配额组。此映射的结构可能会有所不同：
- 每组一个方法：某些配额组适用于单个 API 方法。例如，列出数据源的方法
accounts.dataSources.list有自己的专用配额组。 - 每个组有多个方法（捆绑）：相关方法通常会捆绑到单个配额组中。该组中的所有方法都具有相同的每日和每分钟限制。常见示例包括：
- 将相关方法和资源的所有读取操作分组，例如
merchant-accounts-read-methods。 - 对相关方法和资源的所有写入操作进行分组，例如
merchant-accounts-write-methods。
- 将相关方法和资源的所有读取操作分组，例如
每次方法调用都会计为一次，无论其类型如何。包含 250 项内容的 list 请求仅计为一次，而不是 250 次 get 请求。
内置 HTTP 批处理不会影响配额。一批请求中的每个单独请求都会计入配额。例如，包含 500 个 insert 请求的批量请求将按 500 个单独的 insert 方法请求收费。
专用区域批处理例外情况：专用区域批处理方法（batchCreate、batchUpdate、batchDelete）计为针对 merchant_regions 配额组的单个 API 调用，无论载荷中包含的区域操作数量如何。
为了有效管理集成，您应查看与您打算使用的每个 API 方法关联的特定配额组。您可以在配额列表方法中找到这些详细信息。如需了解详情，请参阅监控和可见性。
更新政策
Merchant API 在更新方面强制执行以下政策：
- 默认情况下，您每天最多可以更新两次商品。您应在一天中均匀分布调用，以符合每分钟配额。
- 默认情况下，您每天最多只能更新子账号两次。您的每日子账号更新配额是根据您允许的子账号总数计算得出的总限额。
- 默认情况下，您每天最多只能为每个子账号调用两次数据源方法（例如
list或create）。
速率配额
每个配额组都有两种类型的限制（和每日用量）：
- 每日限额 (
quotaLimit)：每天允许的最大请求数。每日配额限制会在世界协调时间 (UTC) 中午 12:00 重置。 - 每分钟限制 (
quotaMinuteLimit)：每分钟允许的最大请求数，用于控制请求速率。每分钟配额限制使用滚动窗口，其中强制执行期从对该方法和资源进行首次 API 调用的时刻开始。例如，如果您在上午 10:01:30 发出调用，则该方法的每分钟配额窗口将持续到上午 10:02:30。 - 每日用量 (
quotaUsage)：已发出并计入当天每日限额的请求数。如果缺少该字段，则表示此群组尚未消耗任何配额。
您可以在 quotas.list 方法的响应中找到前面所述的三个字段（quotaLimit、quotaMinuteLimit 和 quotaUsage）。
不同配额组之间的具体每日和每分钟限制差异很大。预期数量较高或系统费用较低的操作（例如读取商品数据）通常具有较高的限制。相反，更密集或更敏感的操作（例如账号修改）可能具有较低的限制。
配额分配和层次结构
本部分介绍了 Merchant API 代表谁跟踪和应用配额用量：
通常，配额是根据发出 API 请求的用户来扣减的。
- 独立账号：对于对 API 调用进行身份验证的独立账号，该请求会计入该账号的配额。
- 示例：商家鞋店 A（账号 ID：12345）使用自己的服务账号进行身份验证，以调用针对其自己账号 (
accounts/12345) 的products.insert。配额从鞋店 A 的配额池中消耗。
- 示例：商家鞋店 A（账号 ID：12345）使用自己的服务账号进行身份验证，以调用针对其自己账号 (
- 高级账号：以高级账号身份进行身份验证会消耗高级账号池中的配额，即使目标是子账号也是如此。
- 示例：某代理机构的零售管理账号（高级账号 ID：12345）管理着一个子账号服装店 B（账号 ID：11111）。
该代理机构使用自己的凭据进行身份验证，并调用
products.insert，目标是服装店 B (accounts/11111)。配额是从父级代理机构的池（高级账号 ID：12345）中消耗的，而不是从子账号的池中消耗的。
- 示例：某代理机构的零售管理账号（高级账号 ID：12345）管理着一个子账号服装店 B（账号 ID：11111）。
该代理机构使用自己的凭据进行身份验证，并调用
- 子账号：如果 API 调用使用子账号的凭证进行身份验证，则配额会从该子账号的单独配额池中扣除。其运作方式与独立账号相同，但由父级高级账号管理。
- 示例：沿用之前的设置，如果服装店 B（账号 ID：11111）使用专门为其子账号设置的凭据进行身份验证，以调用针对其自身账号 (
accounts/11111) 的products.insert，则配额将从服装店 B 的个人配额池中消耗，而父级代理机构的配额池不受影响。
- 示例：沿用之前的设置，如果服装店 B（账号 ID：11111）使用专门为其子账号设置的凭据进行身份验证，以调用针对其自身账号 (
一般规则的例外情况
配额分配一般规则有一些特定的例外情况：
- Accounts.list：此方法的配额是针对发出调用的经过身份验证的用户或服务账号（而非 Merchant Center 账号 ID）收取的。其配额用量不会显示在标准 Merchant Center API 诊断页面中。如果您拥有高级账号，我们建议您使用
accounts.listSubaccounts方法，该方法会计入您的高级账号配额。 - 问题解决方法：这些方法始终会占用所请求问题的账号的配额，即使是其他账号在对请求进行身份验证也是如此。
分配层次结构
购物比较服务 (CSS)：CSS 是汇总商品优惠信息并将用户引导至零售商网站进行购买的网站。进行 API 调用时，配额会应用于您进行身份验证的特定 CSS 组、CSS 网域、账号或子账号。
示例：
- 名为欧洲购物组（账号 ID：10001）的 CSS 组想要列出其关联的 CSS 网域。通过使用自己的凭证进行身份验证来发出此 API 调用，配额将直接从 Europe Shopping Group 配额池中消耗。
- CSS 网域 TopDeals CSS（账号 ID：20002）进行身份验证，以调用针对其关联商家账号 (
accounts/30003) 之一的方法来分配标签。配额是从 TopDeals CSS 的配额池中消耗的，而不是从商家账号的配额池中消耗的。
购物平台：购物平台是托管多个独立商家的在线平台。它们作为特殊的高级账号，可让您为每个卖家创建单独的子账号。
下图显示了 CSS 组、CSS、购物平台、高级账号、独立账号和子账号的层次结构。
自动配额调整
Merchant API 针对特定服务提供自动配额管理系统，该系统会根据您的用量、商品数量和账号规模，为不断发展的商家调整配额限制。Merchant API 每天都会重新计算这些配额。
自动配额调整中包含的配额组如下：
产品服务
- 与
products和productInputs资源相关的方法的所有配额组。 - 每日调用配额通常设置为商家优惠数量的 2 倍。这假设商家可能需要每天更新每件商品最多两次。
- 单个商品可以更新两次以上，但您的每日 API 调用总数不能超过每日调用总配额。
账号服务
- 与 Merchant API 中各种精细账号相关资源相关的方法的所有配额组。
- 每日调用配额设置为该账号允许的子账号数量上限。这样，每个子账号每天最多可进行两次读取调用。
数据源服务
- 高级账号对其子账号执行的 Merchant API 中与数据源相关资源（例如
list或create）相关的方法的所有配额组。 - 每日调用配额通常设置为高级账号所拥有的子账号数量的 2 倍。这假设商家每天最多可以更新两次每个子账号的数据源。
只有前面所述的服务才具有自动配额调整功能。其他服务具有默认配额，任何增加都必须手动申请。如需了解详情，请参阅配额增加流程部分。
超出配额后会出现什么情况
超出配额后，API 响应和 Merchant Center 账号中的诊断页面中会显示错误：
- 每分钟：
quota/request_rate_too_high
{
"error": {
"code": 429,
"message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "quotaExceeded",
"domain": "merchantapi.googleapis.com",
"metadata": {
"HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
"REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
}
}
]
}
}
- 每天：
quota/daily_limit_exceeded
{
"error": {
"code": 429,
"message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "quotaExceeded",
"domain": "merchantapi.googleapis.com",
"metadata": {
"HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
"REASON": "QUOTA_TOO_MANY_REQUESTS"
}
}
]
}
}
以下错误属于 Merchant Center 限制，与 Merchant API 配额无关。您可以尝试请求增加商品、Feed 或子账号的配额：
too_many_items：超出商家配额too_many_subaccounts：已达到子账号数量上限
监控和公开范围
如需查看账号的当前调用配额和用量，请使用账号名称调用 quotas.list。
POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}
替换以下内容：
ACCOUNT_ID：您的 Merchant Center IDACCESS_TOKEN：用于进行 API 调用的授权令牌
请求成功后，API 会返回一个 quotaGroups 资源列表，其中包含配额组的资源 name、不同的配额以及组配额适用的方法。
{
"quotaGroups": [
{
"name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
"quotaUsage": "2",
"quotaLimit": "1000",
"methodDetails": [
{
"method": "quotaservice.listquotagroups",
"version": "v1",
"subapi": "quota",
"path": "quota/v1/quotaservice.listquotagroups"
}
],
"quotaMinuteLimit": "10"
},
{
"name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
"quotaLimit": "10000",
"methodDetails": [
{
"method": "commissiongroupservice.listcommissiongroups",
"version": "v1",
"subapi": "youtube",
"path": "youtube/v1/commissiongroupservice.listcommissiongroups"
}
],
"quotaMinuteLimit": "60"
},
{
"name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
"quotaLimit": "20000000",
"methodDetails": [
{
"method": "merchantreviewsservice.listmerchantreviews",
"version": "v1",
"subapi": "reviews",
"path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
}
],
"quotaMinuteLimit": "60000"
}
]
}
配额增加流程
如需申请更多配额，请打开联系支持团队表单，在必填字段“问题/疑问是什么”中选择“配额增加申请”，然后填写所有必填字段，包括您的 Merchant Center ID、目标方法和业务理由。
- 对于具有自动配额的资源（
products、accounts和datasources[适用于高级账号]）：您只能针对特殊情况（例如在新市场推出或在流量高峰购物季期间）申请临时增加配额。我们不接受针对这些类型的资源永久增加配额。 - 对于没有自动配额的所有其他资源：根据需要申请增加配额。
我们建议您定期检查配额，确保您有足够的配额来满足实现需求，并了解配额是如何自动调整的。使用 quotas.list 方法可查看每个 API 方法组的当前每日配额限制、分钟限制和当前每日用量。
最佳做法
实施这些最佳实践有助于确保集成顺利运行、避免意外的配额错误，并高效利用 Merchant Center 资源。
优化请求分配
- 均匀分布请求：避免发送大量突发请求。将每日 API 调用均匀分布在一天中，以保持在每分钟配额限制 (
quotaMinuteLimit) 内。 - 主动限制：在应用中实现客户端速率限制（限制）。不要仅依赖 Google 服务器来拒绝多余的流量。从源头控制请求速率。
优雅的错误处理
- 处理 HTTP 429：您的应用必须准备好处理 429 请求过多错误 (
quota/request_rate_too_high)。 - 带抖动的指数退避算法：重试失败的请求（尤其是在收到 429 错误后）时，请使用指数退避算法（增加等待时间）并添加“抖动”（随机延迟）。抖动可防止“重试风暴”，即多个客户端实例在完全相同的时间重试，从而再次使服务器过载。
- 遵循重试提示：如果 API 响应包含重试详细信息或标头，请使用这些信息来确定何时恢复调用。
最大限度减少冗余调用
- 防止过时调用 (404 NOT_FOUND)：避免请求或删除不再存在的资源。即使调用失败，也会消耗 API 配额。在 Merchant Center API 诊断中监控
NOT_FOUND错误，以检测过时的状态跟踪或不必要的轮询。 - 更新前验证：在发送更新请求之前，请检查数据是否确实发生了变化。避免发送写入相同值的更新。
- 使用缓存：在适当情况下，在本地缓存读取响应（例如商品详情、设置），以避免针对未更改的数据重复调用
get或list。
浏览配额层次结构和例外情况
- 高级账号和子账号：如果您使用的是高级账号，并且希望调用次数计入高级账号共享池，请在高级账号级别进行身份验证。
- 使用
listSubaccounts：对于高级账号，请使用accounts.listSubaccounts，而不是accounts.list。accounts.list配额会向调用用户（而非 MC ID）收取，并且不会显示在标准诊断中。listSubaccounts会占用您的 MCA 配额。