大数跨境

为库存调整和退款变更添加幂等性

为库存调整和退款变更添加幂等性 Shopify电商独立站
2025-12-12
7
导读:此更新日志涉及并发保护功能。

此更新日志涉及 并发保护功能。

我们为多项库存和退款变更引入了幂等键。此项增强功能可帮助您在重试失败请求时防止重复操作,从而构建更可靠的集成。您通过使用一个 idempotent 指令来传递幂等键。请参阅 幂等请求文档 以获取更多详细信息。

以下变更现在支持可选的 idempotent 指令:

  • refundCreate
  • inventoryShipmentReceive
  • inventoryAdjustQuantities
  • inventoryMoveQuantities
  • inventorySetQuantities
  • inventorySetOnHandQuantities
  • inventoryShipmentCreateInTransit
  • inventoryShipmentCreate
  • inventoryTransferCreate
  • inventoryTransferCreateAsReadyToShip
  • inventoryTransferDuplicate
  • inventoryTransferSetItems
  • inventorySetScheduledChanges
  • inventoryActivate
  • inventoryShipmentAddItems
  • locationActivate
  • locationDeactivate

注意: 目前,幂等指令是可选的,但我们计划在版本 2026-04 中使其成为这些变更的强制要求。 idempotent 指令目前为可选,我们计划将其设为版本 2026-04中这些变更的必填项。

如何使用该指令

幂等键是一个唯一标识符(建议使用 UUID),您在发起变更请求时会提供该标识符(通常,您会在页面加载后以及成功操作后重新生成此密钥)。如果因网络问题或超时而重试相同的请求并使用相同的幂等键,Shopify 会将其识别为重复请求,并确保库存仅调整一次(或退款仅创建一次),从而防止重复计数。系统将返回原始操作的结果,而不是创建新操作。

使用示例:

mutation { inventoryAdjustQuantities( input: { reason: "restock" name: "available" changes: [{ delta: 5 inventoryItemId: "gid://shopify/InventoryItem/123" locationId: "gid://shopify/Location/456" }] } ) @idempotent(key: "4f5b6ebf-143c-4da5-8d0f-fb8553bfd85d") { inventoryAdjustmentGroup { id } userErrors { code message } } }

为何进行此更改

幂等键对于构建健壮、面向生产环境的集成至关重要。网络故障和超时不可避免,若缺乏幂等保护,重试请求可能导致重复退款、库存数量错误或数据不一致等问题。将此功能公开可用,旨在为您提供安全处理此类场景的工具。

错误代码

如果您的幂等键使用出现问题,您将收到以下错误代码之一:

  • IDEMPOTENCY_CONCURRENT_REQUESTIDEMPOTENCY_CONCURRENT_REQUEST:当前正在处理具有相同幂等键的另一个请求。
  • IDEMPOTENCY_KEY_PARAMETER_MISMATCHIDEMPOTENCY_KEY_PARAMETER_MISMATCH:相同的幂等键使用了不同的参数。
【声明】内容源于网络
0
0
Shopify电商独立站
Shopify 是全球首屈一指的商务操作系统,致力于服务来自世界各地的数百万中小商户、大型零售贸易企业和国际知名品牌;其完善的软硬件及产品生态帮助用户简单便捷地,通过线上线下的多种渠道管理并销售自己的商品。
内容 7252
粉丝 1
Shopify电商独立站 Shopify 是全球首屈一指的商务操作系统,致力于服务来自世界各地的数百万中小商户、大型零售贸易企业和国际知名品牌;其完善的软硬件及产品生态帮助用户简单便捷地,通过线上线下的多种渠道管理并销售自己的商品。
总阅读127.3k
粉丝1
内容7.3k