本指南将逐步介绍如何开发使用 Orders API 进行预订的 Actions 项目。
交易流程
当您的 Actions 项目处理预留时，它会使用以下流程：
- 验证交易要求（可选）- 在对话开始时使用事务要求帮助程序，以确保用户能够执行交易。
- 构建订单 - 引导用户完成“购物车组件”，以便他们构建预订的详细信息。
- 建议订单 - 完成“购物车”后，向用户建议预留“订单”，以便他们可以确认其是否正确。如果预订得到确认，您将收到包含预留详细信息的响应。
- 完成订单并发送收据 - 确认订单后，更新您的预订系统并向用户发送收据。
- 发送订单更新 - 在预留的生命周期内，通过向 Orders API 发送 PATCH 请求向用户提供预留状态更新。
限制和审核指南
请注意，使用交易和 Orders API 的 Action 还需遵循其他政策。审核涉及交易的 Action 最多可能需要 6 周的时间，因此在规划发布时间表时请将这段时间考虑在内。为了简化审核流程，请确保先遵守交易政策和准则，然后再提交 Action 以供审核。
您只能在以下国家/地区部署使用 Orders API 的 Action：
|
澳大利亚 巴西 加拿大 印度尼西亚 |
日本 墨西哥 卡塔尔 俄罗斯 |
新加坡 瑞士 泰国 土耳其 英国 美国 |
构建您的项目
如需查看事务性对话的详细示例，请参阅 Node.js 和 Java 中的事务示例。
项目设置
创建 Action 时，您必须指定要在 Actions 控制台中执行事务。此外，如果您使用的是 Node.JS 客户端库，请将执行方式设置为使用最新版本的 Orders API。
如需设置项目和执行方式，请执行以下操作：
- 创建新项目或导入现有项目。
- 依次点击 Deploy > Directory information。
在其他信息 > 交易 > 下，选中显示“您的 Action 是否使用 Transaction API 执行实体商品的交易？”复选框。
如果您使用 Node.JS 客户端库构建 Action 的执行方式，请打开执行方式代码并更新应用声明，将
ordersv3标志设置为true。以下代码段展示了订单版本 3 的应用声明示例。
Node.js
const {dialogflow} = require('actions-on-google');
let app = dialogflow({
clientId, // If using account linking
debug: true,
ordersv3: true,
});
Node.js
const {actionssdk} = require('actions-on-google');
let app = actionssdk({
clientId, // If using account linking
debug: true,
ordersv3: true,
});
1. 验证交易要求（可选）
用户体验
用户表明想要设置预留后，我们建议触发 actions.intent.TRANSACTION_REQUIREMENTS_CHECK intent，以确保他们可以请求预留。例如，调用时，您的 Action 可能会询问“您想预订座位吗？”如果用户说“是”，您应该立即请求此 intent。这样可以确保他们可以继续操作，并有机会修正任何阻止其继续进行交易的设置。
请求事务要求检查 intent 会产生以下结果之一：
- 如果满足这些要求，您的执行方式会收到包含成功条件的 intent，并且您可以继续构建用户的订单。
如果其中一个或多个要求不符合，您的执行方式会收到带有失败条件的 intent。在这种情况下，请结束对话或离开预留流程。
如果用户可以修正错误，系统会自动提示他们在设备上解决这些问题。如果对话是在纯语音界面（例如智能音箱）上进行的，系统会将对话传递给用户的手机。
履单
为确保用户满足交易要求，请使用 TransactionRequirementsCheckSpec 对象请求执行 actions.intent.TRANSACTION_REQUIREMENTS_CHECK intent。
查看要求
检查用户是否满足客户端库的预留要求：
conv.ask(new TransactionRequirements());
return getResponseBuilder(request)
.add("Placeholder for transaction requirements text")
.add(new TransactionRequirements())
.build();
请注意，以下 JSON 描述了 webhook 响应。
{
"payload": {
"google": {
"expectUserResponse": true,
"systemIntent": {
"intent": "actions.intent.TRANSACTION_REQUIREMENTS_CHECK",
"data": {
"@type": "type.googleapis.com/google.actions.transactions.v3.TransactionRequirementsCheckSpec"
}
}
}
}
}
请注意，以下 JSON 描述了 webhook 响应。
{
"expectUserResponse": true,
"expectedInputs": [
{
"possibleIntents": [
{
"intent": "actions.intent.TRANSACTION_REQUIREMENTS_CHECK",
"inputValueData": {
"@type": "type.googleapis.com/google.actions.transactions.v3.TransactionRequirementsCheckSpec"
}
}
]
}
]
}
接收要求检查的结果
Google 助理在执行 intent 后，会向您的执行方式发送包含 actions.intent.TRANSACTION_REQUIREMENTS_CHECK intent 的请求，其中包含检查结果。
为了正确处理此请求，请声明由 actions_intent_TRANSACTION_REQUIREMENTS_CHECK 事件触发的 Dialogflow intent。触发后，在执行方式中处理此 intent：
const arg = conv.arguments.get('TRANSACTION_REQUIREMENTS_CHECK_RESULT');
if (arg && arg.resultType === 'CAN_TRANSACT') {
// Normally take the user through cart building flow
conv.ask(`Looks like you're good to go!`);
} else {
conv.close('Transaction failed.');
}
Argument transactionCheckResult = request
.getArgument("TRANSACTION_REQUIREMENTS_CHECK_RESULT");
boolean result = false;
if (transactionCheckResult != null) {
Map<String, Object> map = transactionCheckResult.getExtension();
if (map != null) {
String resultType = (String) map.get("resultType");
result = resultType != null && resultType.equals("CAN_TRANSACT");
}
}
ResponseBuilder responseBuilder = getResponseBuilder(request);
if (result) {
responseBuilder.add("Looks like you're good to go! Now say 'confirm transaction'");
} else {
responseBuilder.add("Transaction failed");
}
return responseBuilder.build();
请注意，以下 JSON 描述了 webhook 请求。
{
"responseId": "",
"queryResult": {
"queryText": "",
"action": "",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [],
"intent": {
"name": "reservation_transaction_check_complete_df",
"displayName": "reservation_transaction_check_complete_df"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": ""
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"inputs": [
{
"rawInputs": [],
"intent": "",
"arguments": [
{
"extension": {
"@type": "type.googleapis.com/google.transactions.v3.TransactionRequirementsCheckResult",
"resultType": "CAN_TRANSACT"
},
"name": "TRANSACTION_REQUIREMENTS_CHECK_RESULT"
}
]
}
],
"user": {},
"conversation": {},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
},
"session": ""
}
请注意，以下 JSON 描述了 webhook 请求。
{
"user": {},
"device": {},
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"conversation": {},
"inputs": [
{
"rawInputs": [],
"intent": "reservation_transaction_check_complete_asdk",
"arguments": [
{
"extension": {
"@type": "type.googleapis.com/google.transactions.v3.TransactionRequirementsCheckResult",
"resultType": "CAN_TRANSACT"
},
"name": "TRANSACTION_REQUIREMENTS_CHECK_RESULT"
}
]
}
],
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
2. 构建订单
用户体验
获得所需的用户信息后，打造“购物车组合”体验，引导用户构建预订。每个 Action 的购物车组装流程都会因服务而异。
在基本的购物车组装体验中，用户可从列表中选择要添加到预订中的选项，但您也可以设计对话以简化用户体验。例如，打造一种购物车组装体验，让用户能够通过简单的是非问题来安排每月预订。您还可以向用户显示“推荐”预留的轮播界面或列表卡片。
我们建议使用富响应，以直观的方式呈现用户的选项，但同时也要设计对话，让用户只需通过语音就能构建自己的购物车。如需了解一些最佳实践和购物车组合体验的示例，请参阅交易设计准则。
履单
在整个对话中，收集用户想要购买的预留详细信息，然后构建一个 Order 对象。
您的 Order 必须至少包含以下内容：
buyerInfo- 用户进行预订安排的相关信息。transactionMerchant- 协助进行预订的商家的相关信息。contents- 列为lineItems的预留的实际详情。
如需了解如何构建购物车，请参阅 Order 响应文档。请注意，根据预留，您可能需要包含不同的字段。
以下示例代码显示了一个完整的预留订单，其中包括可选字段：
app.intent('build_reservation_df', (conv) => {
const now = new Date().toISOString();
const order = {
createTime: now,
lastUpdateTime: now,
merchantOrderId: 'UNIQUE_ORDER_ID',
userVisibleOrderId: 'USER_VISIBLE_ORDER_ID',
transactionMerchant: {
id: 'https://www.example.com',
name: 'Example Merchant',
},
contents: {
lineItems: [
{
id: 'LINE_ITEM_ID',
name: 'Dinner reservation',
description: 'A world of flavors all in one destination.',
reservation: {
status: 'PENDING',
userVisibleStatusLabel: 'Reservation is pending.',
type: 'RESTAURANT',
reservationTime: {
timeIso8601: '2020-01-16T01:30:15.01Z',
},
userAcceptableTimeRange: {
timeIso8601: '2020-01-15/2020-01-17',
},
partySize: 6,
staffFacilitators: [
{
name: 'John Smith',
},
],
location: {
zipCode: '94086',
city: 'Sunnyvale',
postalAddress: {
regionCode: 'US',
postalCode: '94086',
administrativeArea: 'CA',
locality: 'Sunnyvale',
addressLines: [
'222, Some other Street',
],
},
},
},
},
],
},
buyerInfo: {
email: 'janedoe@gmail.com',
firstName: 'Jane',
lastName: 'Doe',
displayName: 'Jane Doe',
},
followUpActions: [
{
type: 'VIEW_DETAILS',
title: 'View details',
openUrlAction: {
url: 'https://example.com',
},
},
{
type: 'CALL',
title: 'Call us',
openUrlAction: {
url: 'tel:+16501112222',
},
},
{
type: 'EMAIL',
title: 'Email us',
openUrlAction: {
url: 'mailto:person@example.com',
},
},
],
termsOfServiceUrl: 'https://www.example.com',
};
private static OrderV3 createOrder() {
// Transaction Merchant
MerchantV3 transactionMerchant = new MerchantV3()
.setId("http://www.example.com")
.setName("Example Merchant");
// Line Item
// Reservation Item Extension
ReservationItemExtension reservationItemExtension = new ReservationItemExtension()
.setStatus("PENDING")
.setUserVisibleStatusLabel("Reservation pending.")
.setType("RESTAURANT")
.setReservationTime(new TimeV3()
.setTimeIso8601("2020-01-16T01:30:15.01Z"))
.setUserAcceptableTimeRange(new TimeV3()
.setTimeIso8601("2020-01-15/2020-01-17"))
.setPartySize(6)
.setStaffFacilitators(Collections.singletonList(new StaffFacilitator()
.setName("John Smith")))
.setLocation(new Location()
.setZipCode("94086")
.setCity("Sunnyvale")
.setPostalAddress(new PostalAddress()
.setRegionCode("US")
.setPostalCode("94086")
.setAdministrativeArea("CA")
.setLocality("Sunnyvale")
.setAddressLines(
Collections.singletonList("222, Some other Street"))));
LineItemV3 lineItem = new LineItemV3()
.setId("LINE_ITEM_ID")
.setName("Dinner reservation")
.setDescription("A world of flavors all in one destination.")
.setReservation(reservationItemExtension);
// Order Contents
OrderContents contents = new OrderContents()
.setLineItems(Collections.singletonList(lineItem));
// User Info
UserInfo buyerInfo = new UserInfo()
.setEmail("janedoe@gmail.com")
.setFirstName("Jane")
.setLastName("Doe")
.setDisplayName("Jane Doe");
// Follow up actions
Action viewDetails = new Action()
.setType("VIEW_DETAILS")
.setTitle("View details")
.setOpenUrlAction(new OpenUrlAction()
.setUrl("https://example.com"));
Action call = new Action()
.setType("CALL")
.setTitle("Call us")
.setOpenUrlAction(new OpenUrlAction()
.setUrl("tel:+16501112222"));
Action email = new Action()
.setType("EMAIL")
.setTitle("Email us")
.setOpenUrlAction(new OpenUrlAction()
.setUrl("mailto:person@example.com"));
// Terms of service and order note
String termsOfServiceUrl = "https://example.com";
String now = Instant.now().toString();
OrderV3 order = new OrderV3()
.setCreateTime(now)
.setLastUpdateTime(now)
.setMerchantOrderId("UNIQUE_ORDER_ID")
.setUserVisibleOrderId("UNIQUE_USER_VISIBLE_ORDER_ID")
.setTransactionMerchant(transactionMerchant)
.setContents(contents)
.setBuyerInfo(buyerInfo)
.setFollowUpActions(Arrays.asList(
viewDetails,
call,
email
))
.setTermsOfServiceUrl(termsOfServiceUrl);
return order;
}
请注意，以下 JSON 描述了 webhook 响应。
{
"payload": {
"google": {
"expectUserResponse": true,
"systemIntent": {
"intent": "actions.intent.TRANSACTION_DECISION",
"data": {
"@type": "type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec",
"order": {
"createTime": "2019-07-17T18:25:30.182Z",
"lastUpdateTime": "2019-07-17T18:25:30.182Z",
"merchantOrderId": "UNIQUE_ORDER_ID",
"userVisibleOrderId": "USER_VISIBLE_ORDER_ID",
"transactionMerchant": {
"id": "https://www.example.com",
"name": "Example Merchant"
},
"contents": {
"lineItems": [
{
"id": "LINE_ITEM_ID",
"name": "Dinner reservation",
"description": "A world of flavors all in one destination.",
"reservation": {
"status": "PENDING",
"userVisibleStatusLabel": "Reservation is pending.",
"type": "RESTAURANT",
"reservationTime": {
"timeIso8601": "2020-01-16T01:30:15.01Z"
},
"userAcceptableTimeRange": {
"timeIso8601": "2020-01-15/2020-01-17"
},
"partySize": 6,
"staffFacilitators": [
{
"name": "John Smith"
}
],
"location": {
"zipCode": "94086",
"city": "Sunnyvale",
"postalAddress": {
"regionCode": "US",
"postalCode": "94086",
"administrativeArea": "CA",
"locality": "Sunnyvale",
"addressLines": [
"222, Some other Street"
]
}
}
}
}
]
},
"buyerInfo": {
"email": "janedoe@gmail.com",
"firstName": "Jane",
"lastName": "Doe",
"displayName": "Jane Doe"
},
"followUpActions": [
{
"type": "VIEW_DETAILS",
"title": "View details",
"openUrlAction": {
"url": "https://example.com"
}
},
{
"type": "CALL",
"title": "Call us",
"openUrlAction": {
"url": "tel:+16501112222"
}
},
{
"type": "EMAIL",
"title": "Email us",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
],
"termsOfServiceUrl": "https://www.example.com"
},
"orderOptions": {
"requestDeliveryAddress": false,
"userInfoOptions": {
"userInfoProperties": [
"EMAIL"
]
}
},
"presentationOptions": {
"actionDisplayName": "RESERVE"
}
}
}
}
}
}
3. 提出订单建议
将您的预留订单出示给用户，供其确认或拒绝。请求 actions.intent.TRANSACTION_DECISION intent 并提供您构建的 Order。
用户体验
当您请求 actions.intent.TRANSACTION_DECISION intent 时，Google 助理会启动一种内置体验，在这种体验中，Order 会直接呈现到“购物车预览卡片”上。用户可以说“安排预订”、拒绝事务或请求更改预留详细信息。
此时，用户也可以请求更改订单。在这种情况下，您应确保您的执行方式可以在完成购物车组装体验后处理订单更改请求。
履单
当您请求 actions.intent.TRANSACTION_DECISION intent 时，请创建一个包含 Order 和 orderOptions 的 TransactionDecision
以下代码展示了订单的示例 TransactionsDecision：
conv.ask(new TransactionDecision({
orderOptions: {
requestDeliveryAddress: 'false',
},
presentationOptions: {
actionDisplayName: 'RESERVE',
},
order: order,
}));
// Create order options
OrderOptionsV3 orderOptions = new OrderOptionsV3()
.setRequestDeliveryAddress(false)
.setUserInfoOptions(new UserInfoOptions()
.setUserInfoProperties(Collections.singletonList("EMAIL")));
// Create presentation options
PresentationOptionsV3 presentationOptions = new PresentationOptionsV3()
.setActionDisplayName("RESERVE");
// Ask for transaction decision
return getResponseBuilder(request)
.add("Placeholder for transaction decision text")
.add(new TransactionDecision()
.setOrder(order)
.setOrderOptions(orderOptions)
.setPresentationOptions(presentationOptions)
)
.build();
请注意，以下 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"
},
"presentationOptions": {
"actionDisplayName": "RESERVE"
},
"order": {
"createTime": "2019-07-17T18:25:30.184Z",
"lastUpdateTime": "2019-07-17T18:25:30.184Z",
"merchantOrderId": "UNIQUE_ORDER_ID",
"userVisibleOrderId": "USER_VISIBLE_ORDER_ID",
"transactionMerchant": {
"id": "https://www.example.com",
"name": "Example Merchant"
},
"contents": {
"lineItems": [
{
"id": "LINE_ITEM_ID",
"name": "Dinner reservation",
"description": "A world of flavors all in one destination.",
"reservation": {
"status": "PENDING",
"userVisibleStatusLabel": "Reservation is pending.",
"type": "RESTAURANT",
"reservationTime": {
"timeIso8601": "2020-01-16T01:30:15.01Z"
},
"userAcceptableTimeRange": {
"timeIso8601": "2020-01-15/2020-01-17"
},
"partySize": 6,
"staffFacilitators": [
{
"name": "John Smith"
}
],
"location": {
"zipCode": "94086",
"city": "Sunnyvale",
"postalAddress": {
"regionCode": "US",
"postalCode": "94086",
"administrativeArea": "CA",
"locality": "Sunnyvale",
"addressLines": [
"222, Some other Street"
]
}
}
}
}
]
},
"buyerInfo": {
"email": "janedoe@gmail.com",
"firstName": "Jane",
"lastName": "Doe",
"displayName": "Jane Doe"
},
"followUpActions": [
{
"type": "VIEW_DETAILS",
"title": "View details",
"openUrlAction": {
"url": "https://example.com"
}
},
{
"type": "CALL",
"title": "Call us",
"openUrlAction": {
"url": "tel:+16501112222"
}
},
{
"type": "EMAIL",
"title": "Email us",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
],
"termsOfServiceUrl": "https://www.example.com"
}
}
}
}
}
}
请注意，以下 JSON 描述了 webhook 响应。
{
"expectUserResponse": true,
"expectedInputs": [
{
"possibleIntents": [
{
"intent": "actions.intent.TRANSACTION_DECISION",
"inputValueData": {
"@type": "type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec",
"orderOptions": {
"requestDeliveryAddress": "false"
},
"presentationOptions": {
"actionDisplayName": "RESERVE"
},
"order": {
"createTime": "2019-07-17T18:25:30.057Z",
"lastUpdateTime": "2019-07-17T18:25:30.057Z",
"merchantOrderId": "UNIQUE_ORDER_ID",
"userVisibleOrderId": "USER_VISIBLE_ORDER_ID",
"transactionMerchant": {
"id": "https://www.example.com",
"name": "Example Merchant"
},
"contents": {
"lineItems": [
{
"id": "LINE_ITEM_ID",
"name": "Dinner reservation",
"description": "A world of flavors all in one destination.",
"reservation": {
"status": "PENDING",
"userVisibleStatusLabel": "Reservation is pending.",
"type": "RESTAURANT",
"reservationTime": {
"timeIso8601": "2020-01-16T01:30:15.01Z"
},
"userAcceptableTimeRange": {
"timeIso8601": "2020-01-15/2020-01-17"
},
"partySize": 6,
"staffFacilitators": [
{
"name": "John Smith"
}
],
"location": {
"zipCode": "94086",
"city": "Sunnyvale",
"postalAddress": {
"regionCode": "US",
"postalCode": "94086",
"administrativeArea": "CA",
"locality": "Sunnyvale",
"addressLines": [
"222, Some other Street"
]
}
}
}
}
]
},
"buyerInfo": {
"email": "janedoe@gmail.com",
"firstName": "Jane",
"lastName": "Doe",
"displayName": "Jane Doe"
},
"followUpActions": [
{
"type": "VIEW_DETAILS",
"title": "View details",
"openUrlAction": {
"url": "https://example.com"
}
},
{
"type": "CALL",
"title": "Call us",
"openUrlAction": {
"url": "tel:+16501112222"
}
},
{
"type": "EMAIL",
"title": "Email us",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
],
"termsOfServiceUrl": "https://www.example.com"
}
}
}
]
}
]
}
处理用户的决定
用户响应建议的订单后，您的执行方式会收到 actions_intent_TRANSACTION_DECISION intent，其中包含包含 TransactionDecisionValue 的参数。此值将包含以下内容：
transactionDecision- 用户关于提议的订单的决定。可能的值包括ORDER_ACCEPTED、ORDER_REJECTED、CART_CHANGE_REQUESTED和USER_CANNOT_TRANSACT。
如需处理此请求，请声明由 actions_intent_TRANSACTION_DECISION 事件触发的 Dialogflow intent。在执行方式中处理此 intent：
const arg = conv.arguments.get('TRANSACTION_DECISION_VALUE');
if (arg && arg.transactionDecision === 'ORDER_ACCEPTED') {
console.log('order accepted');
const order = arg.order;
}
Argument transactionDecisionValue = request
.getArgument("TRANSACTION_DECISION_VALUE");
Map<String, Object> extension = null;
if (transactionDecisionValue != null) {
extension = transactionDecisionValue.getExtension();
}
String transactionDecision = null;
if (extension != null) {
transactionDecision = (String) extension.get("transactionDecision");
}
if ((transactionDecision != null && transactionDecision.equals("ORDER_ACCEPTED"))) {
OrderV3 order = ((OrderV3) extension.get("order"));
}
请注意，以下 JSON 描述了 webhook 请求。
{
"responseId": "",
"queryResult": {
"queryText": "",
"action": "",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [],
"intent": {
"name": "reservation_get_transaction_decision_df",
"displayName": "reservation_get_transaction_decision_df"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": ""
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"inputs": [
{
"rawInputs": [],
"intent": "",
"arguments": []
}
],
"user": {},
"conversation": {},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
},
"session": ""
}
请注意，以下 JSON 描述了 webhook 请求。
{
"user": {},
"device": {},
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"conversation": {},
"inputs": [
{
"rawInputs": [],
"intent": "reservation_get_transaction_decision_asdk",
"arguments": []
}
],
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
4. 完成预订并发送收据
当 actions.intent.TRANSACTION_DECISION intent 返回 transactionDecision 为 ORDER_ACCEPTED 时，执行安排预留所需的任何处理（例如将其保留在您自己的数据库中）。
发送简单响应以保持对话顺利进行。用户收到“收起的收据卡”以及您的响应。
履单
// Set lastUpdateTime and update status of reservation
order.lastUpdateTime = new Date().toISOString();
order.reservation.status = 'CONFIRMED';
order.reservation.userVisibleStatusLabel = 'Reservation confirmed';
order.reservation.confirmationCode = '123ABCDEFGXYZ';
// Send synchronous order update
conv.ask(`Transaction completed! You're all set!`);
conv.ask(new OrderUpdate({
type: 'SNAPSHOT',
reason: 'Reason string',
order: order,
}));
ResponseBuilder responseBuilder = getResponseBuilder(request);
order.setLastUpdateTime(Instant.now().toString());
// Set reservation status to confirmed and provide confirmation code
LineItemV3 lineItem = order.getContents().getLineItems().get(0);
ReservationItemExtension reservationItemExtension = lineItem.getReservation();
reservationItemExtension.setStatus("CONFIRMED");
reservationItemExtension.setUserVisibleStatusLabel("Reservation confirmed.");
reservationItemExtension.setConfirmationCode("123ABCDEFGXYZ");
lineItem.setReservation(reservationItemExtension);
order.getContents().getLineItems().set(0, lineItem);
// Order update
OrderUpdateV3 orderUpdate = new OrderUpdateV3()
.setType("SNAPSHOT")
.setReason("Reason string")
.setOrder(order);
responseBuilder
.add("Transaction completed! You're all set! Would you like to do anything else?")
.add(new StructuredResponse().setOrderUpdateV3(orderUpdate));
return responseBuilder.build();
请注意，以下 JSON 描述了 webhook 响应。
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Transaction completed! You're all set!"
}
},
{
"structuredResponse": {
"orderUpdateV3": {
"type": "SNAPSHOT",
"reason": "Reason string",
"order": {
"merchantOrderId": "UNIQUE_ORDER_ID",
"reservation": {
"status": "CONFIRMED",
"userVisibleStatusLabel": "Reservation confirmed",
"confirmationCode": "123ABCDEFGXYZ"
},
"lastUpdateTime": "2019-07-17T18:25:30.187Z"
}
}
}
}
]
}
}
}
}
请注意，以下 JSON 描述了 webhook 响应。
{
"expectUserResponse": true,
"expectedInputs": [
{
"possibleIntents": [
{
"intent": "actions.intent.TEXT"
}
],
"inputPrompt": {
"richInitialPrompt": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Transaction completed! You're all set!"
}
},
{
"structuredResponse": {
"orderUpdateV3": {
"type": "SNAPSHOT",
"reason": "Reason string",
"order": {
"merchantOrderId": "UNIQUE_ORDER_ID",
"reservation": {
"status": "CONFIRMED",
"userVisibleStatusLabel": "Reservation confirmed",
"confirmationCode": "123ABCDEFGXYZ"
},
"lastUpdateTime": "2019-07-17T18:25:30.059Z"
}
}
}
}
]
}
}
}
]
}
5. 发送订单动态
预留状态会在其生命周期内发生变化。通过 HTTP PATCH 请求将用户预订订单更新包含订单状态和详细信息。
设置向 Orders API 发送的异步请求
对 Orders API 的订单更新请求由访问令牌进行授权。如需修补 Orders API 的订单更新，请下载与您的 Actions 控制台项目关联的 JSON 服务帐号密钥，然后用服务帐号密钥交换可以传递到 HTTP 请求的 Authorization 标头的不记名令牌。
如需检索您的服务帐号密钥，请执行以下步骤：
- 在 Google Cloud 控制台中，依次点击“菜单”图标 ☰ >“API 和服务”>“凭据”>“创建凭据”>“服务帐号密钥”。
- 在服务帐号下，选择新的服务帐号。
- 将服务帐号设置为
service-account。 - 将角色设置为项目 > Owner。
- 将密钥类型设置为 JSON。
- 选择创建。
- 一个 JSON 私钥服务账号密钥将下载到您的本地机器。
在订单更新代码中，请使用 Google API 客户端库和 "https://www.googleapis.com/auth/actions.order.developer" 范围将服务密钥交换为不记名令牌。您可以在 API 客户端库的 GitHub 页面上找到安装步骤和示例。
如需查看密钥交换示例，在我们的 Node.js 和 Java 示例中引用 order-update.js。
发送订单动态
将服务帐号密钥换成 OAuth 不记名令牌后，将订单更新作为已获授权的 PATCH 请求发送到 Orders API。
Orders API 网址：
PATCH https://actions.googleapis.com/v3/orders/${orderId}
在请求中提供以下标头：
- 将
"Authorization: Bearer token"替换为您交换的服务帐号密钥的 OAuth 不记名令牌。 "Content-Type: application/json".
PATCH 请求应采用以下格式的 JSON 正文：
{ "orderUpdate": OrderUpdate }
OrderUpdate 对象包含以下顶级字段：
updateMask- 要更新的订单的字段。如需更新预留状态，请将值设置为reservation.status, reservation.userVisibleStatusLabel。order- 更新的内容。如果要更新预留的内容，请将值设置为更新后的Order对象。如果您只是更新预留的状态（例如，从"PENDING"更新为"FULFILLED"），则该对象包含以下字段：merchantOrderId- 您在Order对象中设置的同一 ID。lastUpdateTime- 此更新的时间戳。purchase- 包含以下内容的对象：status- 订单的状态，为ReservationStatus，例如“CONFIRMED”或“CANCELLED”。userVisibleStatusLabel- 面向用户的标签，提供订单状态详细信息，例如“您的预订已确认”。
userNotification对象。请注意，添加此对象不能保证通知会显示在用户的设备上。
以下示例代码展示了一个将预留订单状态更新为 FULFILLED 的示例 OrderUpdate：
// 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 orderUpdateJson = new OrderUpdate({
updateMask: [
'lastUpdateTime',
'contents.lineItems.reservation.status',
'contents.lineItems.reservation.userVisibleStatusLabel',
].join(','),
order: {
merchantOrderId: orderId,
lastUpdateTime: new Date().toISOString(),
contents: {
lineItems: [
{
reservation: {
status: 'FULFILLED',
userVisibleStatusLabel: 'Reservation fulfilled',
},
}
]
}
},
reason: 'Reservation status was updated to fulfilled.',
});
// 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: orderUpdateJson,
},
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;
}
});
});
// Create order update
FieldMask fieldMask = FieldMask.newBuilder().addAllPaths(Arrays.asList(
"lastUpdateTime",
"contents.lineItems.reservation.status",
"contents.lineItems.reservation.userVisibleStatusLabel"))
.build();
OrderUpdateV3 orderUpdate = new OrderUpdateV3()
.setOrder(new OrderV3()
.setMerchantOrderId(orderId)
.setLastUpdateTime(Instant.now().toString())
.setContents(new OrderContents()
.setLineItems(Collections.singletonList(new LineItemV3()
.setReservation(new ReservationItemExtension()
.setStatus("FULFILLED")
.setUserVisibleStatusLabel("Reservation fulfilled."))))))
.setUpdateMask(FieldMaskUtil.toString(fieldMask))
.setReason("Reservation status was updated to fulfilled.");
// 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);
设置预留状态
订单更新的 ReservationStatus 必须描述订单的当前状态。在更新的 order.ReservationStatus 字段中，使用以下某个值：
PENDING- 预留已由您的 Action“创建”，但需要在您的后端进行额外处理。CONFIRMED- 已在日程安排后端确认预订。CANCELLED- 用户取消了预订。FULFILLED- 服务实现了用户的预订。CHANGE_REQUESTED- 用户请求了对预留的更改，并且更改正在处理中。REJECTED- 如果您无法处理或以其他方式确认预留。
针对与预留相关的每种状态发送订单更新。例如，如果您的预留在收到预留请求后需要手动处理来确认，请发送 PENDING 订单更新，直到额外处理完成为止。并非每个预留都需要每个状态值。
问题排查
如果您在测试期间遇到任何问题，请阅读我们针对事务的问题排查步骤。