自 2019 年 8 月 7 日起，Orders v2 API 已淘汰，並由訂單版本 3 取代。如果您已建立用於處理此日期之前實際交易的動作，請按照本指南的說明，將動作更新為使用訂單 v3。
API 變更
第 3 版 Orders API 具備下列第 2 版的重要異動：
- 要求結構 - 第 3 版的訂單結構包含所有訂單詳細資料，而非只包含購物車內容。
- 訂單更新 - Orders API 第 3 版除了處理訂單位置外，也會處理訂單更新，因此您的端點不需要使用 Actions API 向使用者傳送訂單的最新資訊。您也可以將更新做為 PATCH 要求傳送至 Orders API，以便更新現有
order物件，而不是以 POST 要求來傳送狀態更新資訊。 - 協助付款：使用 Google Pay 搭配第 3 版 Orders API 的動作，會將付款閘道詳細資料嵌入新的 JSON 結構中，藉此增加擴充性，並確實遵守歐盟法律。
將 Node.JS 遷移至 v3
請按照下列步驟遷移使用 Node.JS 用戶端程式庫的動作。
1. 新增訂單 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 意圖要求中，將舊的 paymentOptions 物件替換為新的 paymentParameters 物件。包含的大部分欄位都相同，儲存部分 JSON 物件結構的變更。
以下程式碼片段為使用第 3 版 Google Pay 的 actions.intent.TRANSACTION_DECISION 意圖要求範例，以及用於比較的舊版第 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 要求傳送至 Orders API，藉此更新 Order 物件的內容。
擷取新的不記名權杖
您可以使用同一個 JSON 服務帳戶金鑰來擷取 Actions API 的不記名憑證，這樣就能為 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" }
OrderUpdate 格式也與第 3 版不同。請參閱 PATCH 要求參考資料，並據此更新 OrderUpdate 欄位。下列程式碼片段提供 PATCH 要求範例，可將訂單的狀態更新為「DELIVERED」：
// 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 用戶端程式庫的動作。
1. 更新購物車組件
ProposedOrder 類型已由更詳細的 Order 物件取代。請參閱 JSON 參考資料，將 ProposedOrder 購物車轉換為 Order 購物車。
2. 更新付款參數
訂單提案步驟中的付款資訊結構會因 API 版本而異。
在 actions.intent.TRANSACTION_DECISION 意圖要求中，將舊的 paymentOptions 物件替換為新的 paymentParameters 物件。包含的大部分欄位都相同，儲存部分 JSON 物件結構的變更。
以下程式碼片段為使用第 3 版 Google Pay 的 actions.intent.TRANSACTION_DECISION 意圖要求範例，以及用於比較的舊版第 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 要求傳送至 Orders API，藉此更新 Order 物件的內容。
擷取新的不記名權杖
您可以使用同一個 JSON 服務帳戶金鑰來擷取 Actions API 的不記名憑證，這樣就能為 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" }
OrderUpdate 格式也與第 3 版不同。請參閱 PATCH 要求參考資料，並據此更新 OrderUpdate 欄位。下列程式碼片段提供 PATCH 要求範例，可將訂單的狀態更新為「DELIVERED」：
// 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 取代。