此更新日志涉及 并发保护功能。
我们为多项库存和退款变更引入了幂等键。此项增强功能可帮助您在重试失败请求时防止重复操作,从而构建更可靠的集成。您通过使用一个 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:相同的幂等键使用了不同的参数。

