使用计划和费率限制
了解使用方案以及如何在 SP-API 中使用速率限制。
为满足应用程序随着时间的推移而不断变化的需求,API 的可靠性取决于调整容量和资源的大小。因此,销售伙伴 API (SP-API) 定义了使用方案,以控制您在特定时间段内可以向某项操作发出的请求数量。
定义的使用方案取决于多个因素。这些因素可能包括销售伙伴账户、代表销售伙伴账户调用 SP-API 的应用程序、商城等。
本文档介绍了 SP-API 的速率限制算法、决定使用方案的因素、如何找到您的使用方案以及有关在速率限制范围内工作的常见问题。
For guidance on how to optimize your application workloads to leverage the rate limits for each SP-API operation efficiently, refer to Optimize rate limits for application workloads.
术语
以下术语与 SP-API 中的速率限制有关:
- 速率限制: SP-API 允许您每秒对特定操作发出的最大请求数。为避免节流,请保持在该限制以下。
- 突发限制: 您可以随着时间的推移积累并同时提交的对特定操作的最大请求数。
- Usage plan: The combination of rate limit and burst limit that applies to a specific operation. For more information, refer to Usage plan types and Factors that determine usage plans.
- Token bucket algorithm: The algorithm that the SP-API uses to rate-limit requests, based on an analogy of exchanging tokens for API requests. For a walkthrough of the algorithm, refer to Rate-limiting algorithm.
- 节流: 当您超过速率限制时,SP-API 会暂时拒绝您的请求的情况。受限制的请求会导致 429 HTTP 错误响应。您可以稍后重试受限制的请求。
- 账户: 开发者应用程序代表其调用 SP-API 的销售合作伙伴账户。您可以通过提供一个来指定账户
sellerId
当你调用某些 SP-API 操作时。 - 应用程序: 代表销售伙伴调用 SP-API 的开发者应用程序。在销售合作伙伴开发者控制台中,您可以在应用程序名称后面找到应用程序 ID。
- Grantless operations: Operations that don't require a
sellerId
as part of the request. For grantless operations, the selling partner isn't a factor in the usage plan for that operation. For a list of grantless operations, refer to Grantless Operations.
速率限制算法
SP-API 使用令牌存储桶算法来限制对 API 的请求速率。该算法可以比作一个存放令牌的存储桶,每个令牌可以交换为一次对 API 的请求。
在这个类比中,SP-API 会自动以设定的每秒速率将令牌添加到您的存储桶,直到达到存储桶的最大大小。最大大小也称为突发速率。
当您调用 SP-API 时,SP-API 会根据在请求标头中标识调用者身份的访问令牌检索该操作的使用方案(速率限制和突发限制)。您向 SP-API 发出的每个请求都会从存储桶中减去一个令牌。当您发出的请求由于存储桶已空而没有令牌可用时,就会受到限制。受限的请求会导致错误响应。
下图显示了速率限制如何基于令牌存储桶算法和存储桶分配标准工作。该示例列举了速率限制为 1 且突增限制为 2 的操作。
- 该存储桶最初已满,存放了两个令牌(突发限制)。在 01:00:100,一个应用程序代表在欧盟商城运营的销售伙伴调用 SP-API 的操作。请求成功。由于该请求耗尽了存储桶中的一个令牌,因此该存储桶现在只剩一个令牌。
- 100 毫秒后,在 01:00:200,同一个应用程序代表同一地区的同一个销售伙伴调用相同的操作。该请求成功并使用存储桶中的最后一个令牌。存储桶现在是空的。
- 再过 100 毫秒后,在 01:00:300,同一个应用程序代表同一地区的同一个销售伙伴调用相同的操作。这次,由于限额已用尽(存储桶为空),请求受到限制。
- 在此示例开始后一秒钟,即 01:01:000,SP-API 将令牌放入存储桶中,因为速率限制为每秒一个令牌。应用程序现在可以成功调用此操作而不会受到限制。
- 再过一秒钟,也就是 01:02:00,SP-API 将另一个令牌添加到存储桶中。
- 在 01:03:00,SP-API 不会向存储桶添加其他令牌,因为该存储桶已达到其最大大小(突发限制)。
决定速率和突发限制的因素意味着在某些情况下,会有一个单独的令牌存储桶。在此示例中,在以下情况下,01:00:200 时有两个令牌可用:
- 同一个应用程序触发相同的操作,但代表了另一个销售伙伴。
- 同一个应用程序代表同一个销售伙伴调用相同的操作,但使用的是来自不同区域账户的凭证。
- 不同的应用程序代表同一个销售伙伴触发相同的操作。
下图显示了这些备用场景。
决定使用方案的因素
每个 SP-API 操作的速率和突发限制取决于多个因素,多个使用方案可以适用于单个操作。请求的速率受首先达到的阈值限制。
SP-API 依赖以下因素来分配使用方案:
- API 操作: SP-API 的每项操作都有自己的默认速率和突发限制。您可以在每项操作的 API 参考文档中找到这些限制,也可以找到列出限制的文档的链接。
- 销售合作伙伴(账户)和应用程序对: 大多数操作的速率限制是根据销售合作伙伴和应用程序对进行的。该应用程序代表销售伙伴调用 SP-API。无授权操作是该规则的例外。应用程序可以在未经销售合作伙伴授权的情况下调用无赠款业务。对于无授权操作,使用计划是根据本节中的其他标准定义的。
- 地区和市场: 使用计划隐含地与销售合作伙伴运营的商城群组相关联,并已授权应用程序代表他们调用 SP-API。这种费率限制因素的隐含性质归结于不同的特定商城的销售合作伙伴账户。不同的商城特定销售合作伙伴账户具有不同的卖家 ID。
使用方案类型
Each SP-API operation is associated with a usage plan. A usage plan specifies a rate limit and a burst limit. For details about how to find your usage plan, refer to How to find your usage plan. There are two types of usage plans: standard and dynamic.
-
标准使用计划: 大多数 SP-API 受标准使用计划的约束。在标准使用计划中,速率限制根据每个操作的预期呼叫模式为所有调用者设定静态值。您可以在每项操作的 API 参考文档中找到使用计划或列出使用计划的文档的链接。
-
动态使用计划: 一些 SP-API 和操作具有动态使用计划。动态使用计划是根据每个销售合作伙伴的当前和历史业务需求自动调整的计划。由于动态使用计划的目的是随着时间的推移调整这些限制,因此费率可能会发生变化。销售合作伙伴的各种业务指标会影响费率调整。这些指标仅是业务指标,不包括 API 请求的历史数量。费率不会动态增加,因为应用程序发出 API 请求的频率更高。
动态使用方案仅适用于以下 SP-API 和操作。
销售伙伴 API Operations 订单 V0 所有操作 产品定价 v2022-05-01 getFeaturedOfferExpectedPriceBatch
如何找到你的使用计划
您可以通过以下方式找到您的使用方案(速率限制和突发限制):
-
SP-API 文档: 您可以在每项操作的 API 参考文档中找到这些限制,或列出限制的文档的链接。
-
响应标头: 当您调用 SP-API 操作时,
x-amzn-RateLimit-Limit
响应标头(如果有)指定每个账户与应用程序对的操作速率限制。但是,您不得依赖此标头的存在,原因如下:- 在某些情况下,尽管尽了最大努力,SP-API 仍无法检索速率限制。在这种情况下,SP-API 不会使本来有效的操作调用失败。取而代之的是,SP-API 返回的响应没有
x-amzn-RateLimit-Limit
标题。 - 这个
x-amzn-RateLimit-Limit
响应标头用于 HTTP 状态码 20x、400 和 404。未经授权或未经身份验证的请求不包含此标头。 - 这个
x-amzn-RateLimit-Limit
标题不包括其他使用计划速率限制。
这意味着您不能依赖于响应中是否存在
x-amzn-RateLimit-Limit
标头。相反,请在尝试使用速率限制值之前检查标头是否存在。 - 在某些情况下,尽管尽了最大努力,SP-API 仍无法检索速率限制。在这种情况下,SP-API 不会使本来有效的操作调用失败。取而代之的是,SP-API 返回的响应没有
常见问题
对于我的用例来说,一次操作的速率限制过低。可以提高限制吗?
We aim for right-sized limits, with the goal that efficient call patterns should, ideally, never be throttled. If your application is consistently throttled, it might mean that you can further optimize your call patterns. For more information, refer to What should I do if my application is consistently throttled. If you find that default rates aren't sufficient, refer to Strategies to optimize rate limits for your application workloads.
我的应用程序应如何处理 429 响应?
A 429 is a retry-able status code. You can try again, but repeated throttled requests require a back-off strategy. Use the x-amzn-RateLimit-Limit
response header, when available, to determine if the rate limits differ from your expectations. For details about when this header is available, refer to How to find your usage plan.
如何测试应用程序的使用方案?
You can test 429 error handling by using the Selling Partner API sandbox. However, you can't test rate limits with the sandbox because while operations in production can have various rates, all sandbox operations share the same rate. You can find your assigned usage rates in the x-amzn-RateLimit-Limit
response header for each operation, when available. For details about when this header is available, refer to How to find your usage plan.
我的应用程序可以完全避免受到限制吗?
没有。您无法控制的任意数量的因素都可能导致几个瞬态的 429 秒。您的应用程序代码应考虑到这种可能性。
如果我的应用程序一直受到限制,该怎么办?
如果您的应用程序持续受到限制,则可能需要进一步优化通话模式。例如:
-
减少通话频率并保持在速率限制之内。
-
依靠推送通知而不是轮询机制。
-
Use batch APIs where available or try to do more with fewer calls. For example, with the Feeds and Reports APIs, you can send or retrieve more information per call. Generally, examine your call patterns against the operations in an API to determine if you can get the same work done in fewer calls.
当我获得更多授权时,我应用程序的受限频率会增加吗?
没有。使用计划特定于应用程序和销售合作伙伴对,因此您的吞吐量会随着客户的增长而自然增长。
速率限制是否会改变?
我们可以随时提高速率限制。如果我们降低了 API 参考文档中发布的速率限制,我们会提前告知您,以便您在更改生效之前可以及时更新和测试您的应用程序。
动态使用计划的速率限制会根据业务环境自动调整到更高或更低。
如果我的应用程序一直受到限制,我的速率限制会增加吗?
Rates are based on a selling partner's business metrics. If your application is consistently throttled, your call patterns are likely not aligned with the rate limits assigned to that selling partner. Refer to What should I do if my application is consistently throttled? and The rate limits for one operation are too low for my use case. Can the limit be increased?.
动态使用方案的总体目标是什么?
根据历史使用情况,我们注意到同类使用方案在某些情况下负载过大,而且更糟糕的是,对于其他情况而言,却负载不足。动态使用方案的目标是利用给定调用的已知背景为任何情况设置适当限制。
影响动态使用方案的因素有哪些?
一般来说,速率限制由销售伙伴业务的类型、规模和行为所决定。
特定使用方案的相关限制会多久更改一次?
我们的目标是防止对限制频繁地进行破坏性更改。一般来说,一旦我们发现销售伙伴账户的业务指标发生了有意义的变化,就会立即更改限制。
我应该如何给我的应用程序编码以适应动态限制?
以下建议可以帮助您的应用程序处理动态速率限制:
-
Read the
x-amzn-RateLimit-Limit
header, when available. For details about when this header is available, refer to How to find your usage plan. -
不要对计时器进行硬编码。
-
自然地针对事件进行编码,而不是循环运行。如果您使用事件,则不需要计时器。例如,根据价格通知更新价格,而不是每隔一定秒钟更新价格。
2 个月前更新