此页面由 Cloud Translation API 翻译。

异步订单更新

客户提交订餐后，您可以向“Google 订餐”服务发送订单更新消息，通知我们相应的变化。

以下是发送订单更新的一些常见原因：

订单的预计履行时间变为可用或有变化。
订单的状态会发生变化。
该订单已无法履行。
订单中包含的菜单项的价格发生了变化。
客户有了新的订单管理方式，例如客户服务或餐厅电话号码。
您可以查看订单收据。

接下来的部分详细介绍了如何使用订单更新应对这些不同场景。

转换订单状态

订单有六种可能的状态。这些状态及其可能的转换如下图所示：

订单状态转换

客户首次提交订单时，订单的状态为 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 状态时可以取消。您的“Google 订餐”服务应根据您的取消政策和取消时的付款状态发放退款。

您的“Google 订餐”服务不一定支持所有可用的状态和转换。但是，订单的最终状态必须是 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 订餐”服务发送订单更新。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."
        }
      ]
      }
    }
  }
}

CANCELLED

此示例展示了示例订单更新请求，该请求可通知用户订单因取消而被取消。

{
  "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"
            }
          }
        }
      ]
    }
  }
}

准备中

此示例展示了一个订单更新请求示例，用于通知用户食物正在准备中。

{
  "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"
      }
    }
  }
}

准备好自提

此示例展示了一个订单更新请求示例，该请求会通知用户食物已准备好自提。

{
  "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"
      }
    }
  }
}

转账

此示例显示了一个订单更新请求示例，该请求通知用户订单正在运输，同时还包含预计送货时间。

{
  "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"
      }
    }
  }
}

已填写

以下示例展示了一个订单更新请求示例，用于通知用户自提或配送订单：

{
  "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"
            }
          }
        }
      ]
    }
  }
}

如需查看不同用例中的订单更新请求的更多示例，请阅读实现高级订单更新。

生成授权令牌并发送消息

订单更新需要授权令牌，以便“Google 订餐”服务可以验证消息是否来自“您的 Google 订餐”网络服务。

如需为您的项目实现订单更新，请按以下步骤操作：

请按照以下步骤生成授权令牌：
1. 使用 Google Auth 库从服务帐号文件中读取凭据。
2. 使用以下 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 身份验证库。

/**
 * 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 会返回一个错误。