新增 API 以读取和写入配送资料中的运输选项

作为创建运输选项的增强型用户界面的一部分，现在运输选项可以包含多个分层的费率组合。

如果您的应用集成了配送配置文件，并使用DeliveryMethodDefinition和DeliveryMethodDefinitionInput来管理配送选项，请评估是否需要迁移到不稳定版本中的新API：

• 如果您的应用读取由商家管理的DeliveryProfile，则可能需要迁移到新的读取API。请参阅[读取API](#Read API)和向后兼容性部分。
• 如果您的应用写入由商家管理的DeliveryProfile，则必须迁移到新的写入API以避免意外行为。请参阅[写入API](#Write API)部分。
• 如果您的应用读取和/或写入由应用管理的DeliveryProfile，则无需采取任何操作。

术语表：

• 由商家管理的DeliveryProfile：商家在Shopify管理后台创建和编辑的配送配置文件。
• 由应用管理的DeliveryProfile：由应用创建和编辑的配送配置文件。

本指南概述了用于在运输配置文件中管理运输选项的新 GraphQL 字段和输入类型。

变更内容？

读取 API

我们正在引入DeliveryMethodDefinition.rateGroups和DeliveryRateDefinition.conditions字段。这些字段将取代旧的DeliveryMethodDefinition.rateProvider和DeliveryMethodDefinition.methodConditions字段。

为防止意外行为，请迁移到这些新字段。请参阅示例查询以了解如何使用这些字段来获取DeliveryMethodDefinition。

旧字段计划弃用。有关其当前行为的详细信息，请参阅查询的向后兼容性。

写入 API

以下新输入字段已添加到DeliveryMethodDefinitionInput： rateGroupsToCreate

• rateGroupsToUpdate
• freeConditions
• currencyCode

当商家开始使用多个分层费率时，以下旧版字段将变为过时：

• DeliveryMethodDefinitionInput.participant
• DeliveryMethodDefinitionInput.rateDefinition
• DeliveryMethodDefinitionInput.priceConditionsToCreate
• DeliveryMethodDefinitionInput.weightConditionsToCreate .

要了解如何使用新字段更新DeliveryMethodDefinition，请参阅示例变更

示例

如何查询运输选项

query DeliveryProfile { deliveryProfile(id: "gid://shopify/DeliveryProfile/123") { profileLocationGroups { locationGroup { id } locationGroupZones(first: 10) { edges { node { methodDefinitions(first: 10) { edges { node { id name description active currencyCode rateGroups(first: 10) { edges { node { id rateProviders(first: 10) { edges { node { ... on DeliveryRateDefinition { id price { amount currencyCode } minTransitTime maxTransitTime conditions { subject min { ... on MoneyV2 { amount currencyCode } ... on Weight { value unit } } max { ... on MoneyV2 { amount currencyCode } ... on Weight { value unit } } } } ... on DeliveryParticipant { id carrierService { id name } fixedFee { amount currencyCode } percentageOfRateFee } } } } } } } freeConditions { subject min { ... on MoneyV2 { amount currencyCode } ... on Weight { value unit } } max { ... on MoneyV2 { amount currencyCode } ... on Weight { value unit } } } } } } } } } } } }

如何创建和更新运输选项

对于deliveryProfileCreate和deliveryProfileUpdate变更，以下新输入字段已添加到DeliveryMethodDefinitionInput：

• rateGroupsToCreate
• rateGroupsToUpdate
• freeConditions
• currencyCode

以下是如何使用新的输入字段来更新运输选项：

mutation ProfileUpdate { deliveryProfileUpdate( id: "gid://shopify/DeliveryProfile/123" profile: { profileLocationGroups: [ { id: "gid://shopify/DeliveryProfileLocationGroup/456" zonesToUpdate: [ { id: "gid://shopify/DeliveryLocationGroupZone/789" methodDefinitionsToUpdate: [ { id: "gid://shopify/DeliveryMethodDefinition/321" rateGroupsToUpdate: [ { id: "gid://shopify/DeliveryRateGroup/555" rateDefinitionsToUpdate: [ { id: "gid://shopify/DeliveryRateDefinition/666" price: { amount: 7.50 currencyCode: USD } minTransitTime: 172800 } ] rateDefinitionsToDelete: [ "gid://shopify/DeliveryRateDefinition/777" ] rateDefinitionsToCreate: [ { price: { amount: 15.00 currencyCode: USD } conditions: [ { subject: PACKAGE_WEIGHT min: 20.0 unit: "kg" } ] } ] } ] } ] } ] } ] } ) { profile { id } userErrors { field message } } }

查询的后向兼容性

DeliveryMethodDefinition.rateProvider和DeliveryMethodDefinition.methodConditions字段将在一段时间内继续得到支持，以促进平稳过渡。

在使用旧版 API 时：

• 如果方法定义包含多个费率定义，则每个额外的费率都表示为具有其自身rateProvider和methodConditions的单独方法定义。
• 免费条件表示为单独的费率定义，其中零价格费率定义作为rateProvider。

例如，具有三个费率定义和一个免费条件的方法定义在新API和旧API中将产生不同的结果。activeMethodDefinitionsCount和methodDefinitionCounts将反映这些差异。

新 API 响应

{ "data": { "node": { "activeMethodDefinitionsCount": 1, "profileLocationGroups": [ { "locationGroupZones": { "nodes": [ { "methodDefinitionCounts": { "rateDefinitionsCount": 1, "participantDefinitionsCount": 0 }, "methodDefinitions": { "nodes": [ { "id": "gid://shopify/DeliveryMethodDefinition/825837944888", "name": "Standard", "rateGroups": { "nodes": [ { "rateProviders": { "nodes": [ { "id": "gid://shopify/DeliveryRateDefinition/760813584440", "price": { "amount": "10.0", "currencyCode": "CAD" }, "conditions": [ { "subject": "PACKAGE_WEIGHT", "min": { "value": 0, "unit": "KILOGRAMS" }, "max": { "value": 10, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryRateDefinition/760813617208", "price": { "amount": "20.0", "currencyCode": "CAD" }, "conditions": [ { "subject": "PACKAGE_WEIGHT", "min": { "value": 10.0001, "unit": "KILOGRAMS" }, "max": { "value": 20, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryRateDefinition/760813649976", "price": { "amount": "30.0", "currencyCode": "CAD" }, "conditions": [ { "subject": "PACKAGE_WEIGHT", "min": { "value": 20.0001, "unit": "KILOGRAMS" }, "max": null } ] } ] } } ] }, "freeShippingConditions": [ { "min": { "amount": "100.0", "currencyCode": "CAD" } } ] } ] } } ] } } ] } } }

旧版 API 响应

使用遗留 API 时，您会收到多个方法定义，每个费率定义对应一个方法，免费条件也对应一个方法：

{ "data": { "node": { "activeMethodDefinitionsCount": 4, "profileLocationGroups": [ { "locationGroupZones": { "nodes": [ { "methodDefinitionCounts": { "rateDefinitionsCount": 4, "participantDefinitionsCount": 0 }, "methodDefinitions": { "nodes": [ { "id": "gid://shopify/DeliveryMethodDefinition/825837944888", "name": "Standard", "rateProvider": { "__typename": "DeliveryRateDefinition", "id": "gid://shopify/DeliveryRateDefinition/760813584440", "price": { "amount": "10.0", "currencyCode": "CAD" } }, "methodConditions": [ { "id": "gid://shopify/DeliveryCondition/21530181688?operator=greater_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 0, "unit": "KILOGRAMS" } }, { "id": "gid://shopify/DeliveryCondition/21530181688?operator=less_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 10, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryMethodDefinition/825837944888?source=RateDefinition&source_id=760813617208", "name": "Standard", "rateProvider": { "__typename": "DeliveryRateDefinition", "id": "gid://shopify/DeliveryRateDefinition/760813617208", "price": { "amount": "20.0", "currencyCode": "CAD" } }, "methodConditions": [ { "id": "gid://shopify/DeliveryCondition/21530214456?operator=greater_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 10.0001, "unit": "KILOGRAMS" } }, { "id": "gid://shopify/DeliveryCondition/21530214456?operator=less_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 20, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryMethodDefinition/825837944888?source=RateDefinition&source_id=760813649976", "name": "Standard", "rateProvider": { "__typename": "DeliveryRateDefinition", "id": "gid://shopify/DeliveryRateDefinition/760813649976", "price": { "amount": "30.0", "currencyCode": "CAD" } }, "methodConditions": [ { "id": "gid://shopify/DeliveryCondition/21530247224?operator=greater_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 20.0001, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryMethodDefinition/825837944888?source=RateRangeCondition&source_id=21530279992", "name": "Standard", "rateProvider": { "__typename": "DeliveryRateDefinition", "id": "gid://shopify/DeliveryRateDefinition/0?source=RateRangeCondition&source_id=21530279992", "price": { "amount": "0.0", "currencyCode": "CAD" } }, "methodConditions": [ { "id": "gid://shopify/DeliveryCondition/21530279992?operator=greater_than_or_equal_to", "field": "TOTAL_PRICE", "conditionCriteria": { "amount": "100.0", "currencyCode": "CAD" } } ] } ] } } ] } } ] } } }