自 2019 年 8 月 7 日起,Orders v2 API 已被弃用,取而代之的是 Orders 版本 3。如果您在 请按照本指南将您的 Action 更新为使用 Orders v3。
API 变更
与版本 2 相比,版本 3 的 Orders API 包含以下主要更改:
- 请求结构 - 版本 3 订单结构包含 订单详情,而不仅仅是包含购物车内的商品。
- 订单更新 - 版本 3 Orders API 在
因此您的端点不需要
使用 Actions API 向用户发送有关其订单的更新。您还发送了
以 PATCH 请求的形式更新至 Orders API,更新现有
order
对象,而不是发送状态更新的 POST 请求。 - 付款便利 - 使用 Google Pay 版本 3 的操作 Orders API 将支付网关详细信息嵌套在新的 JSON 结构中, 进一步扩展并遵守欧盟法律。
将 Node.JS 迁移到 v3
请按照以下步骤迁移使用 Node.JS 客户端库的 Action。
1. 添加 Orders v3 标志
您用于处理事务的客户端库函数会更新 对于订单版本 3,您只需在履单代码中添加标志即可 更新函数以发送版本 3 JSON。
将以下代码添加到您的执行方式中:
<ph type="x-smartling-placeholder">const {dialogflow} = require('actions-on-google'); const app = dialogflow({ordersv3: true});
2. 更新购物车组件
ProposedOrder
类型已替换为更详细的 Order
对象。请参阅 JSON 参考文档,将您的 ProposedOrder
购物车转换为
Order
购物车。
3. 更新付款参数
订单提案步骤中付款信息的结构 因 API 版本而异
在 actions.intent.TRANSACTION_DECISION
intent 请求中,替换旧的 intent
将 paymentOptions
对象与新的 paymentParameters
对象结合使用。大部分
包含的字段相同,但 JSON 对象的某些更改除外,
结构。
以下代码段显示了一个示例 actions.intent.TRANSACTION_DECISION
使用版本 3 的 Google Pay 发出旧版 intent 请求,而使用版本 2 的旧版本
比较。
conv.ask(new TransactionDecision({ orderOptions: { requestDeliveryAddress: false, userInfoOptions: { userInfoProperties: [ 'EMAIL', ], }, }, paymentParameters: { googlePaymentOption: { // facilitationSpec is expected to be a serialized JSON string facilitationSpec: JSON.stringify({ apiVersion: 2, apiVersionMinor: 0, merchantInfo: { merchantName: 'Example Merchant', }, allowedPaymentMethods: [ { type: 'CARD', parameters: { allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'], allowedCardNetworks: [ 'AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA'], }, tokenizationSpecification: { type: 'PAYMENT_GATEWAY', parameters: { gateway: 'example', gatewayMerchantId: 'exampleGatewayMerchantId', }, }, }, ], transactionInfo: { totalPriceStatus: 'FINAL', totalPrice: '10.00', currencyCode: 'USD', }, }), }, }, presentationOptions: { actionDisplayName: 'PLACE_ORDER', }, order: order, }));
conv.ask(new TransactionDecision({ orderOptions: { requestDeliveryAddress: false, }, paymentOptions: { googleProvidedOptions: { prepaidCardDisallowed: false, supportedCardNetworks: ['VISA', 'AMEX', 'DISCOVER', 'MASTERCARD'], tokenizationParameters: { tokenizationType: 'PAYMENT_GATEWAY', // These will be provided by payment processor, // like Stripe, Braintree, Vantiv, Ayden, etc. parameters: { 'gateway': 'stripe', 'stripe:publishableKey': (conv.sandbox ? 'pk_test_key' : 'pk_live_key'), 'stripe:version': '2018-11-08' }, }, }, }, proposedOrder: order, }));
请注意,下面的 Dialogflow JSON 描述了一个 webhook 响应。
{ "payload": { "google": { "expectUserResponse": true, "systemIntent": { "intent": "actions.intent.TRANSACTION_DECISION", "data": { "@type": "type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec", "orderOptions": { "requestDeliveryAddress": "false" }, "paymentParameters": { "googlePaymentOption": { "facilitationSpec": "{\"apiVersion\":2,\"apiVersionMinor\":0,\"merchantInfo\":{\"merchantName\":\"Example Merchant\"},\"allowedPaymentMethods\":[{\"type\":\"CARD\",\"parameters\":{\"allowedAuthMethods\":[\"PAN_ONLY\",\"CRYPTOGRAM_3DS\"],\"allowedCardNetworks\":[\"AMEX\",\"DISCOVER\",\"JCB\",\"MASTERCARD\",\"VISA\"]},\"tokenizationSpecification\":{\"type\":\"PAYMENT_GATEWAY\",\"parameters\":{\"gateway\":\"example\",\"gatewayMerchantId\":\"exampleGatewayMerchantId\"}}}],\"transactionInfo\":{\"totalPriceStatus\":\"FINAL\",\"totalPrice\":\"10.00\",\"currencyCode\":\"USD\"}}" } }, "presentationOptions": { "actionDisplayName": "PLACE_ORDER" }, "order": { "createTime": "2019-08-01T17:12:13.765Z", "lastUpdateTime": "2019-08-01T17:12:13.765Z", "merchantOrderId": "UNIQUE_ORDER_ID", "userVisibleOrderId": "USER_VISIBLE_ORDER_ID", "transactionMerchant": { "id": "http://www.example.com", "name": "Example Merchant" }, "contents": { "lineItems": [ { "id": "LINE_ITEM_ID", "name": "Pizza", "description": "A four cheese pizza.", "priceAttributes": [ { "type": "REGULAR", "name": "Line Item Price", "state": "ACTUAL", "amount": { "currencyCode": "USD", "amountInMicros": 8990000 }, "taxIncluded": true } ], "notes": [ "Extra cheese." ], "purchase": { "quantity": 1, "unitMeasure": { "measure": 1, "unit": "POUND" }, "itemOptions": [ { "id": "ITEM_OPTION_ID", "name": "Pepperoni", "prices": [ { "type": "REGULAR", "state": "ACTUAL", "name": "Item Price", "amount": { "currencyCode": "USD", "amountInMicros": 1000000 }, "taxIncluded": true } ], "note": "Extra pepperoni", "quantity": 1, "subOptions": [] } ] } } ] }, "buyerInfo": { "email": "janedoe@gmail.com", "firstName": "Jane", "lastName": "Doe", "displayName": "Jane Doe" }, "priceAttributes": [ { "type": "TOTAL", "name": "Total Price", "state": "ESTIMATE", "amount": { "currencyCode": "USD", "amountInMicros": 15770000 }, "taxIncluded": true }, { "type": "TAX", "name": "Tax", "state": "ESTIMATE", "amount": { "currencyCode": "USD", "amountInMicros": 3780000 }, "taxIncluded": true }, { "type": "SUBTOTAL", "name": "Subtotal", "state": "ESTIMATE", "amount": { "currencyCode": "USD", "amountInMicros": 9990000 }, "taxIncluded": true }, { "type": "DELIVERY", "name": "Delivery", "state": "ACTUAL", "amount": { "currencyCode": "USD", "amountInMicros": 2000000 }, "taxIncluded": true } ], "followUpActions": [ { "type": "VIEW_DETAILS", "title": "View details", "openUrlAction": { "url": "http://example.com" } }, { "type": "CALL", "title": "Call us", "openUrlAction": { "url": "tel:+16501112222" } }, { "type": "EMAIL", "title": "Email us", "openUrlAction": { "url": "mailto:person@example.com" } } ], "termsOfServiceUrl": "www.example.com", "note": "Sale event", "promotions": [ { "coupon": "COUPON_CODE" } ], "purchase": { "status": "CREATED", "userVisibleStatusLabel": "CREATED", "type": "FOOD", "returnsInfo": { "isReturnable": false, "daysToReturn": 1, "policyUrl": "http://www.example.com" }, "fulfillmentInfo": { "id": "FULFILLMENT_SERVICE_ID", "fulfillmentType": "DELIVERY", "expectedFulfillmentTime": { "timeIso8601": "2017-01-16T01:30:15.01Z" }, "location": { "zipCode": "94086", "city": "Sunnyvale", "postalAddress": { "regionCode": "US", "postalCode": "94086", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "222, Some other Street" ] } }, "price": { "type": "REGULAR", "name": "Delivery Price", "state": "ACTUAL", "amount": { "currencyCode": "USD", "amountInMicros": 2000000 }, "taxIncluded": true }, "fulfillmentContact": { "email": "johnjohnson@gmail.com", "firstName": "John", "lastName": "Johnson", "displayName": "John Johnson" } }, "purchaseLocationType": "ONLINE_PURCHASE" } } } } } } }
请注意,下面的 Dialogflow JSON 描述了一个 webhook 响应。
{ "payload": { "google": { "expectUserResponse": true, "systemIntent": { "intent": "actions.intent.TRANSACTION_DECISION", "data": { "@type": "type.googleapis.com/google.actions.v2.TransactionDecisionValueSpec", "orderOptions": { "requestDeliveryAddress": false }, "paymentOptions": { "googleProvidedOptions": { "prepaidCardDisallowed": false, "supportedCardNetworks": [ "VISA", "AMEX", "DISCOVER", "MASTERCARD" ], "tokenizationParameters": { "tokenizationType": "PAYMENT_GATEWAY", "parameters": { "gateway": "stripe", "stripe:publishableKey": "pk_test_key", "stripe:version": "2018-11-08" } } } }, "proposedOrder": { "id": "UNIQUE_ORDER_ID222", "cart": { "merchant": { "id": "book_store_id", "name": "A Book Store" }, "lineItems": [ { "name": "My Memoirs", "id": "mymemoirs_id", "price": { "amount": { "currencyCode": "USD", "nanos": 990000000, "units": 8 }, "type": "ACTUAL" }, "quantity": 1, "subLines": [ { "note": "By Bestselling Novelist" } ], "type": "REGULAR" }, { "name": "Biography", "id": "biography_id", "price": { "amount": { "currencyCode": "USD", "nanos": 990000000, "units": 10 }, "type": "ACTUAL" }, "quantity": 1, "subLines": [ { "note": "Signed copy" } ], "type": "REGULAR" } ], "notes": "Sale event", "otherItems": [] }, "otherItems": [ { "name": "Subtotal", "id": "subtotal", "price": { "amount": { "currencyCode": "USD", "nanos": 980000000, "units": 19 }, "type": "ESTIMATE" }, "type": "SUBTOTAL" }, { "name": "Tax", "id": "tax", "price": { "amount": { "currencyCode": "USD", "nanos": 780000000, "units": 2 }, "type": "ESTIMATE" }, "type": "TAX" } ], "totalPrice": { "amount": { "currencyCode": "USD", "nanos": 760000000, "units": 22 }, "type": "ESTIMATE" } } } } } } }
4. 使用 Orders API 发送更新
Orders API 版本 3 可处理订单更新,因此你不再需要
向 Actions API 发送 POST 请求。您可以改为发送 PATCH 请求
有助于更新 Order
对象内容的 Orders API。
检索新的不记名令牌
您可以使用检索 不记名令牌,您需要请求一个新的不记名令牌, Orders API将您的服务密钥交换为不记名令牌 使用 Google API 客户端库和 "https://www.googleapis.com/auth/actions.order.developer" 范围。
您可以在 API 客户端库 GitHub 页面上找到安装步骤和示例。
如需查看 Orders API 密钥交换示例,您还可以在我们的 Node.js 示例中引用更新后的 order-update.js
。
发送更新
使用 Orders API 发送订单更新的过程与发送 使用 Actions API 进行更新,尽管您发送 PATCH 请求 而不是 POST 请求。PATCH 请求应采用 以下格式:
{ "orderUpdate": OrderUpdate" }
OrderUpdate
格式在版本 3 中也有所不同。请参阅 PATCH 请求参考文档
并相应地更新 OrderUpdate
字段。以下代码段
显示了一个将订单状态更新为“DELIVERED
”的 PATCH 请求示例:
// Import the 'googleapis' module for authorizing the request. const {google} = require('googleapis'); // Import the 'request' module for sending an HTTP POST request. const request = require('request'); // Import the OrderUpdate class from the Actions on Google client library. const {OrderUpdate} = require('actions-on-google'); // Import the service account key used to authorize the request. Replace the string path with a path to your service account key. const key = require('./service-account.json'); // Create a new JWT client for the Actions API using credentials from the service account key. let jwtClient = new google.auth.JWT( key.client_email, null, key.private_key, ['https://www.googleapis.com/auth/actions.order.developer'], null ); // Authorize the client asynchronously, passing in a callback to run upon authorization. jwtClient.authorize((err, tokens) => { if (err) { console.log(err); return; } // Declare the ID of the order to update. const orderId = '<UNIQUE_MERCHANT_ORDER_ID>'; const orderUpdate = new OrderUpdate({ updateMask: [ 'lastUpdateTime', 'purchase.status', 'purchase.userVisibleStatusLabel', ].join(','), order: { merchantOrderId: orderId, lastUpdateTime: new Date().toISOString(), purchase: { status: 'DELIVERED', userVisibleStatusLabel: 'Order delivered', }, }, reason: 'Order status updated to delivered.', }); // Set up the PATCH request header and body, including the authorized token // and order update. const bearer = 'Bearer ' + tokens.access_token; const options = { method: 'PATCH', url: `https://actions.googleapis.com/v3/orders/${orderId}`, headers: { 'Authorization': bearer, }, body: { header: { 'isInSandbox': true, }, orderUpdate, }, json: true, }; // Send the PATCH request to the Orders API. request.patch(options, (err, httpResponse, body) => { if (err) { console.log('There was an error...'); console.log(err); return; } }); });
处理其他订单状态
Orders API 版本 3 支持额外的订单状态值 许多其他功能您应该发送 与每笔交易相关的每个状态的订单更新。
以下是版本 3 的新增状态值:
IN_PREPARATION
- 订单正在准备发货/交付,比如食品 烹饪或包装的食物等。READY_FOR_PICKUP
- 订单商品可供收件人自提。DELIVERED
- 订单已送达收件人OUT_OF_STOCK
- 订单中的一件或多件商品缺货。CHANGE_REQUESTED
- 用户请求更改订单,但更改已 处理中。
FULFILLED
状态已弃用,取而代之的是 DELIVERED
。
将 Java 迁移到 v3
请按照以下步骤迁移使用 Java 客户端库的 Action。
1. 更新购物车组件
ProposedOrder
类型已替换为更详细的 Order
对象。请参阅 JSON 参考文档,将您的 ProposedOrder
购物车转换为
Order
购物车。
2. 更新付款参数
订单提案步骤中付款信息的结构 因 API 版本而异
在 actions.intent.TRANSACTION_DECISION
intent 请求中,替换旧的 intent
将 paymentOptions
对象与新的 paymentParameters
对象结合使用。大部分
包含的字段相同,但 JSON 对象的某些更改除外,
结构。
以下代码段显示了一个示例 actions.intent.TRANSACTION_DECISION
使用版本 3 的 Google Pay 发出旧版 intent 请求,而使用版本 2 的旧版本
比较。
// Create order options OrderOptionsV3 orderOptions = new OrderOptionsV3() .setRequestDeliveryAddress(false) .setUserInfoOptions(new UserInfoOptions() .setUserInfoProperties(Collections.singletonList("EMAIL"))); // Create presentation options PresentationOptionsV3 presentationOptions = new PresentationOptionsV3() .setActionDisplayName("PLACE_ORDER"); // Create payment parameters JSONObject merchantInfo = new JSONObject(); merchantInfo.put("merchantName", "Example Merchant"); JSONObject facilitationSpec = new JSONObject(); facilitationSpec.put("apiVersion", 2); facilitationSpec.put("apiVersionMinor", 0); facilitationSpec.put("merchantInfo", merchantInfo); JSONObject allowedPaymentMethod = new JSONObject(); allowedPaymentMethod.put("type", "CARD"); JSONArray allowedAuthMethods = new JSONArray(); allowedAuthMethods.addAll(Arrays.asList("PAN_ONLY", "CRYPTOGRAM_3DS")); JSONArray allowedCardNetworks = new JSONArray(); allowedCardNetworks.addAll(Arrays.asList("AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA")); JSONObject allowedPaymentMethodParameters = new JSONObject(); allowedPaymentMethodParameters.put("allowedAuthMethods", allowedAuthMethods); allowedPaymentMethodParameters.put("allowedCardNetworks", allowedCardNetworks); allowedPaymentMethod.put("parameters", allowedPaymentMethodParameters); JSONObject tokenizationSpecificationParameters = new JSONObject(); tokenizationSpecificationParameters.put("gateway", "example"); tokenizationSpecificationParameters.put("gatewayMerchantId", "exampleGatewayMerchantId"); JSONObject tokenizationSpecification = new JSONObject(); tokenizationSpecification.put("type", "PAYMENT_GATEWAY"); tokenizationSpecification.put("parameters", tokenizationSpecificationParameters); allowedPaymentMethod.put("tokenizationSpecification", tokenizationSpecification); JSONArray allowedPaymentMethods = new JSONArray(); allowedPaymentMethods.add(allowedPaymentMethod); facilitationSpec.put("allowedPaymentMethods", allowedPaymentMethods); JSONObject transactionInfo = new JSONObject(); transactionInfo.put("totalPriceStatus", "FINAL"); transactionInfo.put("totalPrice", "10.00"); transactionInfo.put("currencyCode", "USD"); facilitationSpec.put("transactionInfo", transactionInfo); GooglePaymentOption googlePaymentOption = new GooglePaymentOption() .setFacilitationSpec(facilitationSpec.toJSONString()); PaymentParameters paymentParameters = new PaymentParameters() .setGooglePaymentOption(googlePaymentOption); // Ask for transaction decision return getResponseBuilder(request) .add("Placeholder for transaction decision text") .add(new TransactionDecision() .setOrder(order) .setOrderOptions(orderOptions) .setPresentationOptions(presentationOptions) .setPaymentParameters(paymentParameters) ) .build();
OrderOptions orderOptions; PaymentOptions paymentOptions; // Setup Google provided payment options Map<String, String> parameters = new HashMap<>(); parameters.put("gateway", "stripe"); parameters.put("stripe:publishableKey", request.isInSandbox() ? "pk_test_key" : "pk_live_key"); parameters.put("stripe:version", "2017-04-06"); PaymentMethodTokenizationParameters tokenizationParameters = new PaymentMethodTokenizationParameters() .setTokenizationType("PAYMENT_GATEWAY") .setParameters(parameters); orderOptions = new OrderOptions().setRequestDeliveryAddress(false); GoogleProvidedPaymentOptions googleProvidedPaymentOptions = new GoogleProvidedPaymentOptions() .setPrepaidCardDisallowed(false) .setSupportedCardNetworks(Arrays.asList("VISA", "AMEX")) .setTokenizationParameters(tokenizationParameters); paymentOptions = new PaymentOptions().setGoogleProvidedOptions(googleProvidedPaymentOptions); return getResponseBuilder(request) .add("Placeholder for transaction decision text") .add( new TransactionDecision() .setOrderOptions(orderOptions) .setPaymentOptions(paymentOptions) .setProposedOrder(proposedOrder)) .build();
请注意,下面的 Dialogflow JSON 描述了一个 webhook 响应。
{ "payload": { "google": { "expectUserResponse": true, "systemIntent": { "intent": "actions.intent.TRANSACTION_DECISION", "data": { "@type": "type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec", "orderOptions": { "requestDeliveryAddress": "false" }, "paymentParameters": { "googlePaymentOption": { "facilitationSpec": "{\"apiVersion\":2,\"apiVersionMinor\":0,\"merchantInfo\":{\"merchantName\":\"Example Merchant\"},\"allowedPaymentMethods\":[{\"type\":\"CARD\",\"parameters\":{\"allowedAuthMethods\":[\"PAN_ONLY\",\"CRYPTOGRAM_3DS\"],\"allowedCardNetworks\":[\"AMEX\",\"DISCOVER\",\"JCB\",\"MASTERCARD\",\"VISA\"]},\"tokenizationSpecification\":{\"type\":\"PAYMENT_GATEWAY\",\"parameters\":{\"gateway\":\"example\",\"gatewayMerchantId\":\"exampleGatewayMerchantId\"}}}],\"transactionInfo\":{\"totalPriceStatus\":\"FINAL\",\"totalPrice\":\"10.00\",\"currencyCode\":\"USD\"}}" } }, "presentationOptions": { "actionDisplayName": "PLACE_ORDER" }, "order": { "createTime": "2019-08-01T17:12:13.765Z", "lastUpdateTime": "2019-08-01T17:12:13.765Z", "merchantOrderId": "UNIQUE_ORDER_ID", "userVisibleOrderId": "USER_VISIBLE_ORDER_ID", "transactionMerchant": { "id": "http://www.example.com", "name": "Example Merchant" }, "contents": { "lineItems": [ { "id": "LINE_ITEM_ID", "name": "Pizza", "description": "A four cheese pizza.", "priceAttributes": [ { "type": "REGULAR", "name": "Line Item Price", "state": "ACTUAL", "amount": { "currencyCode": "USD", "amountInMicros": 8990000 }, "taxIncluded": true } ], "notes": [ "Extra cheese." ], "purchase": { "quantity": 1, "unitMeasure": { "measure": 1, "unit": "POUND" }, "itemOptions": [ { "id": "ITEM_OPTION_ID", "name": "Pepperoni", "prices": [ { "type": "REGULAR", "state": "ACTUAL", "name": "Item Price", "amount": { "currencyCode": "USD", "amountInMicros": 1000000 }, "taxIncluded": true } ], "note": "Extra pepperoni", "quantity": 1, "subOptions": [] } ] } } ] }, "buyerInfo": { "email": "janedoe@gmail.com", "firstName": "Jane", "lastName": "Doe", "displayName": "Jane Doe" }, "priceAttributes": [ { "type": "TOTAL", "name": "Total Price", "state": "ESTIMATE", "amount": { "currencyCode": "USD", "amountInMicros": 15770000 }, "taxIncluded": true }, { "type": "TAX", "name": "Tax", "state": "ESTIMATE", "amount": { "currencyCode": "USD", "amountInMicros": 3780000 }, "taxIncluded": true }, { "type": "SUBTOTAL", "name": "Subtotal", "state": "ESTIMATE", "amount": { "currencyCode": "USD", "amountInMicros": 9990000 }, "taxIncluded": true }, { "type": "DELIVERY", "name": "Delivery", "state": "ACTUAL", "amount": { "currencyCode": "USD", "amountInMicros": 2000000 }, "taxIncluded": true } ], "followUpActions": [ { "type": "VIEW_DETAILS", "title": "View details", "openUrlAction": { "url": "http://example.com" } }, { "type": "CALL", "title": "Call us", "openUrlAction": { "url": "tel:+16501112222" } }, { "type": "EMAIL", "title": "Email us", "openUrlAction": { "url": "mailto:person@example.com" } } ], "termsOfServiceUrl": "www.example.com", "note": "Sale event", "promotions": [ { "coupon": "COUPON_CODE" } ], "purchase": { "status": "CREATED", "userVisibleStatusLabel": "CREATED", "type": "FOOD", "returnsInfo": { "isReturnable": false, "daysToReturn": 1, "policyUrl": "http://www.example.com" }, "fulfillmentInfo": { "id": "FULFILLMENT_SERVICE_ID", "fulfillmentType": "DELIVERY", "expectedFulfillmentTime": { "timeIso8601": "2017-01-16T01:30:15.01Z" }, "location": { "zipCode": "94086", "city": "Sunnyvale", "postalAddress": { "regionCode": "US", "postalCode": "94086", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "222, Some other Street" ] } }, "price": { "type": "REGULAR", "name": "Delivery Price", "state": "ACTUAL", "amount": { "currencyCode": "USD", "amountInMicros": 2000000 }, "taxIncluded": true }, "fulfillmentContact": { "email": "johnjohnson@gmail.com", "firstName": "John", "lastName": "Johnson", "displayName": "John Johnson" } }, "purchaseLocationType": "ONLINE_PURCHASE" } } } } } } }
请注意,下面的 Dialogflow JSON 描述了一个 webhook 响应。
{ "payload": { "google": { "expectUserResponse": true, "systemIntent": { "intent": "actions.intent.TRANSACTION_DECISION", "data": { "@type": "type.googleapis.com/google.actions.v2.TransactionDecisionValueSpec", "orderOptions": { "requestDeliveryAddress": false }, "paymentOptions": { "googleProvidedOptions": { "prepaidCardDisallowed": false, "supportedCardNetworks": [ "VISA", "AMEX", "DISCOVER", "MASTERCARD" ], "tokenizationParameters": { "tokenizationType": "PAYMENT_GATEWAY", "parameters": { "gateway": "stripe", "stripe:publishableKey": "pk_test_key", "stripe:version": "2018-11-08" } } } }, "proposedOrder": { "id": "UNIQUE_ORDER_ID222", "cart": { "merchant": { "id": "book_store_id", "name": "A Book Store" }, "lineItems": [ { "name": "My Memoirs", "id": "mymemoirs_id", "price": { "amount": { "currencyCode": "USD", "nanos": 990000000, "units": 8 }, "type": "ACTUAL" }, "quantity": 1, "subLines": [ { "note": "By Bestselling Novelist" } ], "type": "REGULAR" }, { "name": "Biography", "id": "biography_id", "price": { "amount": { "currencyCode": "USD", "nanos": 990000000, "units": 10 }, "type": "ACTUAL" }, "quantity": 1, "subLines": [ { "note": "Signed copy" } ], "type": "REGULAR" } ], "notes": "Sale event", "otherItems": [] }, "otherItems": [ { "name": "Subtotal", "id": "subtotal", "price": { "amount": { "currencyCode": "USD", "nanos": 980000000, "units": 19 }, "type": "ESTIMATE" }, "type": "SUBTOTAL" }, { "name": "Tax", "id": "tax", "price": { "amount": { "currencyCode": "USD", "nanos": 780000000, "units": 2 }, "type": "ESTIMATE" }, "type": "TAX" } ], "totalPrice": { "amount": { "currencyCode": "USD", "nanos": 760000000, "units": 22 }, "type": "ESTIMATE" } } } } } } }
3. 使用 Orders API 发送更新
Orders API 版本 3 可处理订单更新,因此你不再需要
向 Actions API 发送 POST 请求。您可以改为发送 PATCH 请求
有助于更新 Order
对象内容的 Orders API。
检索新的不记名令牌
您可以使用检索 不记名令牌,您需要请求一个新的不记名令牌, Orders API将您的服务密钥交换为不记名令牌 使用 Google API 客户端库和 "https://www.googleapis.com/auth/actions.order.developer" 范围。
您可以在 API 客户端库 GitHub 页面上找到安装步骤和示例。
如需查看 Orders API 密钥交换示例,您还可以在我们的 Java 示例中引用更新后的 order-update.js
。
发送更新
使用 Orders API 发送订单更新的过程与发送 使用 Actions API 进行更新,尽管您发送 PATCH 请求 而不是 POST 请求。PATCH 请求应采用 以下格式:
{ "orderUpdate": OrderUpdate" }
OrderUpdate
格式在版本 3 中也有所不同。请参阅 PATCH 请求参考文档
并相应地更新 OrderUpdate
字段。以下代码段
显示了一个将订单状态更新为“DELIVERED
”的 PATCH 请求示例:
// Create order update FieldMask fieldMask = FieldMask.newBuilder().addAllPaths(Arrays.asList( "last_update_time", "purchase.status", "purchase.userVisibleStatusLabel")) .build(); OrderUpdateV3 orderUpdate = new OrderUpdateV3() .setOrder(new OrderV3() .setMerchantOrderId(orderId) .setLastUpdateTime(Instant.now().toString()) .setPurchase(new PurchaseOrderExtension() .setStatus("DELIVERED") .setUserVisibleStatusLabel("Order delivered."))) .setUpdateMask(FieldMaskUtil.toString(fieldMask)) .setReason("Order status was updated to delivered."); // Setup JSON body containing order update JsonParser parser = new JsonParser(); JsonObject orderUpdateJson = parser.parse(new Gson().toJson(orderUpdate)).getAsJsonObject(); JsonObject body = new JsonObject(); body.add("orderUpdate", orderUpdateJson); JsonObject header = new JsonObject(); header.addProperty("isInSandbox", true); body.add("header", header); StringEntity entity = new StringEntity(body.toString()); entity.setContentType(ContentType.APPLICATION_JSON.getMimeType()); request.setEntity(entity); // Make request HttpClient httpClient = HttpClientBuilder.create().build(); HttpResponse response = httpClient.execute(request);
处理其他订单状态
Orders API 版本 3 支持额外的订单状态值 许多其他功能您应该发送 与每笔交易相关的每个状态都会更新订单。
以下是版本 3 的新增状态值:
IN_PREPARATION
- 订单正在准备发货/交付,比如食品 烹饪或包装的食物等。READY_FOR_PICKUP
- 订单商品可供收件人自提。DELIVERED
- 订单已送达收件人OUT_OF_STOCK
- 订单中的一件或多件商品缺货。CHANGE_REQUESTED
- 用户请求更改订单,但更改已 处理中。
FULFILLED
状态已弃用,取而代之的是 DELIVERED
。