自 2019 年 8 月 7 日起,Orders v2 API 已废弃,取而代之的是 Orders 版本 3。如果您在此日期之前已构建了一个用于处理实际交易的 Action,请按照本指南中的说明更新 Action 以使用 Orders v3。
API 变更
Orders API 版本 3 与版本 2 相比存在以下主要变更:
- 请求结构 - 版本 3 订单结构包含所有订单详情,而不是仅包含购物车内容。
- 订单更新 - 版本 3 Orders API 不但会处理订单,还会处理订单更新,因此您的端点不需要使用 Actions API 向用户发送有关其订单的更新信息。您还可以将更新作为 PATCH 请求发送到用于更新现有
order
对象的 Orders API,而不是用于发送状态更新的 POST 请求。 - 付款便利服务 - 将 Google Pay 与版本 3 Orders API 配合使用的 Action 会将支付网关详细信息嵌套在新的 JSON 结构中,这提高了可扩展性并遵守欧盟法律。
将 Node.JS 迁移到 v3
如需迁移使用 Node.JS 客户端库的 Action,请按以下步骤操作。
1. 添加 Orders v3 标记
您用于处理交易的客户端库函数针对订单版本 3 进行了更新,您只需在履单代码中添加标志来更新函数以发送版本 3 JSON 即可。
将以下代码添加到执行方式:
const {dialogflow} = require('actions-on-google'); const app = dialogflow({ordersv3: true});
2. 更新购物车组件
ProposedOrder
类型已替换为更详细的 Order
对象。请参阅 JSON 参考文档,将您的 ProposedOrder
购物车转换为 Order
购物车。
3. 更新付款参数
订单提案步骤中的付款信息结构因 API 版本而异。
在 actions.intent.TRANSACTION_DECISION
intent 请求中,将旧的 paymentOptions
对象替换为新的 paymentParameters
对象。除了对 JSON 对象结构的一些更改外,其中包含的大多数字段都是相同的。
以下代码段显示了使用版本 3 的 Google Pay 的 actions.intent.TRANSACTION_DECISION
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 请求。不过,您可以向 Orders API 发送 PATCH 请求,以更新 Order
对象的内容。
检索新的不记名令牌
您可以使用为 Actions API 检索不记名令牌时所用的同一 JSON 服务帐号密钥,但需要为 Orders API 请求新的不记名令牌。您可以使用 Google API 客户端库和 "https://www.googleapis.com/auth/actions.order.developer" 范围将服务密钥交换为不记名令牌。
您可以在 API 客户端库的 GitHub 页面上找到安装步骤和示例。
您还可以在 Node.js 示例中引用更新后的 order-update.js
,查看 Orders API 密钥交换示例。
发送更新
使用 Orders API 发送订单更新的过程与使用 Actions API 发送更新的过程类似,只不过前者发送的是 PATCH 请求,而不是 POST 请求。PATCH 请求应采用以下格式的 JSON 正文:
{ "orderUpdate": OrderUpdate" }
版本 3 中的 OrderUpdate
格式也有所不同。请参阅 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 支持版本 2 中未提供的其他订单状态值。您应该针对与每笔交易相关的每个状态发送订单更新。
以下状态值是版本 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 请求中,将旧的 paymentOptions
对象替换为新的 paymentParameters
对象。除了对 JSON 对象结构的一些更改外,其中包含的大多数字段都是相同的。
以下代码段显示了使用版本 3 的 Google Pay 的 actions.intent.TRANSACTION_DECISION
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 请求。不过,您可以向 Orders API 发送 PATCH 请求,以更新 Order
对象的内容。
检索新的不记名令牌
您可以使用为 Actions API 检索不记名令牌时所用的同一 JSON 服务帐号密钥,但需要为 Orders API 请求新的不记名令牌。您可以使用 Google API 客户端库和 "https://www.googleapis.com/auth/actions.order.developer" 范围将服务密钥交换为不记名令牌。
您可以在 API 客户端库的 GitHub 页面上找到安装步骤和示例。
您还可以在我们的 Java 示例中引用更新后的 order-update.js
,查看 Orders API 密钥交换示例。
发送更新
使用 Orders API 发送订单更新的过程与使用 Actions API 发送更新的过程类似,只不过前者发送的是 PATCH 请求,而不是 POST 请求。PATCH 请求应采用以下格式的 JSON 正文:
{ "orderUpdate": OrderUpdate" }
版本 3 中的 OrderUpdate
格式也有所不同。请参阅 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 支持版本 2 中未提供的其他订单状态值。您应该针对与每笔交易相关的每个状态发送订单更新。
以下状态值是版本 3 中新增的状态:
IN_PREPARATION
- 订单正在准备配送/配送,例如正在烹饪食物或商品正在包装。READY_FOR_PICKUP
- 订单商品可由收货人自提。DELIVERED
- 订单已送达收货人OUT_OF_STOCK
- 订单中的一件或多件商品缺货。CHANGE_REQUESTED
- 用户请求更改订单,并且更改正在处理中。
FULFILLED
状态已废弃,取而代之的是 DELIVERED
。