客户提交食品订单后，您可以向端到端订餐服务发送订单更新消息，以便通知我们发生的更改。
以下是发送订单更新的一些常见原因：
- 订单的预计送货时间变为可用或发生变化。
- 订单的状态发生变化。
- 订单无法再履行。
- 订单中包含的菜单项的价格发生了变化。
- 客户可以通过新的方式管理订单，例如通过客户服务或餐厅电话号码。
- 订单的收据会随之显示。
以下部分详细介绍了如何使用订单更新来处理这些不同的场景。
订单状态转换
订单有 6 种可能的状态。下图概述了这些状态及其可能的转换：
客户首次提交订单时，订单的初始状态为 CREATED、CONFIRMED 或 REJECTED。只要状态转换有效，您就可以发送订单更新消息来更新订单状态。当合作伙伴的平台无法立即确认或拒绝订单时，系统会使用 CREATED 状态。一个示例用例是客户通过配送集合商家下单。配送集合商家会从 Google 接收配送信息，然后将信息发送给餐厅。餐厅收到并确认订单可用性后，状态现在可以是 CONFIRMED，否则为 REJECTED。
处于 CONFIRMED 状态的订单接下来会转换为 IN_PREPARATION 状态。接下来，根据订单是自提还是送货，使用 READY_FOR_PICKUP 或 IN_TRANSIT 状态。当食物送达或被自提后，订单会设为 FULFILLED 状态。
如果您允许客户取消订单，则可以使用 CANCELLED 状态。订单在 CREATED、CONFIRMED、IN_PREPARATION、READY_FOR_PICKUP 或 IN_TRANSIT 状态时可以取消。您的端到端订购服务应根据您的取消政策以及取消时付款状态发放退款。
您的端到端订购服务不必支持所有可用状态和转换。不过，订单的最终状态必须为 FULFILLED、REJECTED 或 CANCELLED。
提供预计完成时间
您可以向用户提供订单预计可供自提（或送达）的时间范围。使用 FoodOrderUpdateExtension 的 estimatedFulfillmentTimeIso8601 字段提供客户订单的预计自提或送达时间范围。
在以下时间发送 estimatedFulfillmentTimeIso8601：
- 预计时间可用时，最好是在订单
CREATED或CONFIRMED状态下。 - 预计时间发生变化时，例如在订单为
IN_TRANSIT时更新预计时间以提高准确性。
为有效管理用户预期，请谨慎估算，并提供日期和时间范围，而不是固定的日期和时间。您应尽可能考虑交通状况等变化。例如，如果订单的预计送货时间为下午 1:00，您可以发送下午 12:45（下限）到下午 1:15（上限）的预计送货时间。
提供订单管理操作
发送订单动态时，您可以以 OrderManagementAction 的形式向客户提供有助于他们管理订单的资源。客户下单后，可能需要与您或负责履行订单的餐厅联系，以跟踪订单进度、进行更改或取消订单。
借助 OrderManagementAction，客户可以直接从其设备发送电子邮件、拨打电话或关联到网址。在 OrderManagementAction 中使用与您向用户发送的电子邮件订单确认中相同的信息。
订单管理操作包括以下类型：
CUSTOMER_SERVICE：为客户提供与客户服务团队联系的操作。若要更新订单，必须使用此管理操作类型。EMAIL：向客户提供向所提供的电子邮件地址发送电子邮件的操作。CALL：为客户提供用于拨打所提供电话号码的操作。VIEW_DETAIL：为客户提供查看订单详情的操作。
每个订单更新都必须包含至少一个订单管理操作。不过，提供的订单管理操作可能会因订单状态而异。例如，当订单处于 CONFIRMED 状态时，CUSTOMER_SERVICE 操作可以指向您的客户服务电话号码。当该订单状态更新为 IN_TRANSIT 时，CUSTOMER_SERVICE 操作可以指向履单餐厅的电话号码。
发送订单动态
您可以使用 AsyncOrderUpdateRequestMessage 消息类型将订单更新发送到端到端订购服务。Google 会回复 AsyncOrderUpdateResponseMessage。例如，如果您想告知客户其订单有效且已接受，可以发送 AsyncOrderUpdateRequestMessage 将订单状态更改为 CONFIRMED，并使用标签 Accepted by restaurant。
设置订单更新消息
向 Google 发送 AsyncOrderUpdateRequestMessage 时，您必须使用 OrderUpdate 字段添加有关订单状态的信息。
以下示例展示了每种订单状态的 AsyncOrderUpdateRequestMessage 示例：
已确认
此示例展示了一个示例订单更新请求，用于通知用户订单已确认，并附上收据和预计送货时间。
{ "isInSandbox": true, "customPushMessage": { "orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "CONFIRMED", "label": "Provider confirmed" }, "receipt": { "userVisibleOrderId": "userVisibleId1234" }, "updateTime": "2017-07-17T12:00:00Z", "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:person@example.com" } } }, { "type": "CALL_RESTAURANT", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+16505554679" } } }, { "type": "CALL_DRIVER", "button": { "title": "Call driver", "openUrlAction": { "url": "tel:+16505554681" } } } ], "infoExtension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension", "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z" } } } }
已拒绝
此示例展示了一个订单更新请求示例，该请求会通知用户订单已被拒绝以及拒绝原因。
{ "isInSandbox": true, "customPushMessage": { "orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "REJECTED", "label": "Order rejected" }, "updateTime": "2017-05-10T02:30:00.000Z", "rejectionInfo": { "type": "UNKNOWN", "reason": "Sorry, the restaurant cannot take your order right now." }, "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:person@example.com" } } }, { "type": "CALL_RESTAURANT", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+16505554679" } } }, { "type": "CALL_DRIVER", "button": { "title": "Call driver", "openUrlAction": { "url": "tel:+16505554681" } } } ], "infoExtension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension", "foodOrderErrors": [ { "error": "NO_CAPACITY", "description": "Sorry, the restaurant cannot take your order right now." } ] } } } }
已取消
此示例展示了一个订单更新请求示例，该请求会通知用户订单已取消并附上取消原因。
{ "isInSandbox": true, "customPushMessage": { "orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "CANCELLED", "label": "Order cancelled" }, "updateTime": "2017-05-10T02:30:00.000Z", "cancellationInfo": { "reason": "Customer requested" }, "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:person@example.com" } } }, { "type": "CALL_RESTAURANT", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+16505554679" } } }, { "type": "CALL_DRIVER", "button": { "title": "Call driver", "openUrlAction": { "url": "tel:+16505554681" } } } ] } } }
IN_PREPARATION
此示例展示了一个示例订单更新请求，用于通知用户食物正在准备中。
{ "isInSandbox":true, "customPushMessage":{ "orderUpdate":{ "actionOrderId":"sample_action_order_id", "orderState":{ "state":"IN_PREPARATION", "label":"Order is being prepared" }, "receipt": { "userVisibleOrderId": "userVisibleId1234" }, "updateTime":"2018-04-15T11:30:00Z", "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:person@example.com" } } }, { "type": "CALL_RESTAURANT", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+16505554679" } } }, { "type": "CALL_DRIVER", "button": { "title": "Call driver", "openUrlAction": { "url": "tel:+16505554681" } } } ], "infoExtension":{ "@type":"type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension", "estimatedFulfillmentTimeIso8601":"PT20M" } } } }
READY_FOR_PICKUP
此示例展示了一个示例订单更新请求，用于通知用户食物已准备好自提。
{ "isInSandbox": true, "customPushMessage": { "orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "READY_FOR_PICKUP", "label": "Order is ready for pickup" }, "receipt": { "userVisibleOrderId": "userVisibleId1234" }, "updateTime": "2018-04-15T12:00:00Z", "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:person@example.com" } } }, { "type": "CALL_RESTAURANT", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+16505554679" } } }, { "type": "CALL_DRIVER", "button": { "title": "Call driver", "openUrlAction": { "url": "tel:+16505554681" } } } ], "infoExtension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension", "estimatedFulfillmentTimeIso8601": "PT20M" } } } }
IN_TRANSIT
此示例显示了一个示例订单更新请求，用于通知用户订单正在运输中以及预计送货时间。
{ "isInSandbox": true, "customPushMessage": { "orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "IN_TRANSIT", "label": "Order is on the way" }, "inTransitInfo": { "updatedTime": "2017-07-17T12:00:00Z" }, "updateTime": "2017-07-17T12:00:00Z", "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:person@example.com" } } }, { "type": "CALL_RESTAURANT", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+16505554679" } } }, { "type": "CALL_DRIVER", "button": { "title": "Call driver", "openUrlAction": { "url": "tel:+16505554681" } } } ], "infoExtension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension", "estimatedFulfillmentTimeIso8601": "PT20M" } } } }
FULFILLED
以下示例展示了一个示例订单更新请求，用于通知用户订单已被取件或送达：
{ "isInSandbox": true, "customPushMessage": { "orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "FULFILLED", "label": "Order delivered" }, "updateTime": "2017-05-10T02:30:00.000Z", "fulfillmentInfo": { "deliveryTime": "2017-05-10T02:30:00.000Z" }, "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:person@example.com" } } }, { "type": "CALL_RESTAURANT", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+16505554679" } } }, { "type": "CALL_DRIVER", "button": { "title": "Call driver", "openUrlAction": { "url": "tel:+16505554681" } } } ] } } }
如需查看不同使用情形中的更多订单更新请求示例，请参阅实现高级订单更新。
生成授权令牌并发送消息
订单更新需要授权令牌，以便端到端订餐服务可以验证消息是否来自您的端到端订餐 Web 服务。
如需为您的项目实现有序更新，请按以下步骤操作：
- 请按以下步骤生成授权令牌：
- 使用 Google Auth 库从服务账号文件中读取凭据。
- 使用以下 API 范围请求令牌：
https://www.googleapis.com/auth/actions.fulfillment.conversation
- 使用此令牌向以下端点发送经过身份验证的 HTTP POST 请求：
https://actions.googleapis.com/v2/conversations:send - 在请求中将
Content-Type标头设置为application/json。
以下示例演示了如何实现订单更新：
Node.js
此代码使用 Node.js 版 Google 身份验证库。
const {auth} = require('google-auth-library') const request = require('request'); // The service account client secret file downloaded from the Google Cloud Console const serviceAccountJson = require('./service-account.json') // order-update.json is a file that contains the payload const jsonBody = require('./order-update.json') /** * Get the authorization token using a service account. */ async function getAuthToken() { let client = auth.fromJSON(serviceAccountJson) client.scopes = ['https://www.googleapis.com/auth/actions.fulfillment.conversation'] const tokens = await client.authorize() return tokens.access_token; } /** * Send an order update request */ async function sendOrderUpdate() { const token = await getAuthToken() request.post({ headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, url: 'https://actions.googleapis.com/v2/conversations:send', body: jsonBody, json: true }, (err, res, body) => { if (err) { return console.log(err); } console.log(`Response: ${JSON.stringify(res)}`) }) }
Python
此代码使用 Python 版 Google 身份验证库。
from google.oauth2 import service_account from google.auth.transport.requests import AuthorizedSession import json # service-account.json is the service account client secret file downloaded from the # Google Cloud Console credentials = service_account.Credentials.from_service_account_file( 'service-account.json') scoped_credentials = credentials.with_scopes( ['https://www.googleapis.com/auth/actions.fulfillment.conversation']) authed_session = AuthorizedSession(scoped_credentials) # order-update.json is a file that contains the payload json_payload=json.load(open('order-update.json')) response = authed_session.post( 'https://actions.googleapis.com/v2/conversations:send', json=json_payload)
Java
此代码使用适用于 Java 的 Google Auth 库。
/** * Get the authorization token using a service account. */ private static String getAuthToken() { InputStream serviceAccountFile = Example.class.getClassLoader().getResourceAsStream("service-account.json"); ServiceAccountCredentials.Builder credentialsSimpleBuilder = ServiceAccountCredentials.fromStream(serviceAccountFile).toBuilder(); credentialsSimpleBuilder.setScopes(ImmutableList.of("https://www.googleapis.com/auth/actions.fulfillment.conversation")); AccessToken accessToken = credentialsSimpleBuilder.build().refreshAccessToken(); return accessToken.getTokenValue(); } /** * Send an order update request */ public void sendOrderUpdate() { String authToken = getAuthToken(); // Execute POST request executePostRequest("https://actions.googleapis.com/v2/conversations:send", authToken, "update_order_example.json",); }
对于成功且没有错误的订单更新，Google 会返回包含空载荷的 HTTP 200 响应。如果出现问题（例如更新格式有误），Google 会返回错误。