实现预订服务器：API v2

在您设置预订服务器后，Action Center 便可代表用户与您创建预约/预订。

基于 gRPC 实现 API 接口

请注意：所有新合作伙伴都应使用 REST API 接口，而不是 gRPC API。

实现基于 gRPC 的 API 接口。这样一来，Google 便可发送预订请求。API 接口使用 gRPC 基于 protobuf 的 IDL 进行定义。

我们要求新合作伙伴实现一组建议的 API v2。合作伙伴可以选择最适合其基础架构的网址和端口。

本部分介绍了建议使用的一组 API v2。它适用于尚未实现 API v0 的合作伙伴。对于目前已实现 API v0 的合作伙伴，请与 Action Center 联系以了解详情。

下载以下 proto 格式的服务定义，开始使用 API 实现。

下载服务定义

API 资源

请熟悉此实现中将使用的以下资源类型：

  • 空档：商品目录空档
  • 预订：对商品目录空档的预约

方法

您必须为 gRPC 服务器实现以下 API 方法：

以下 5 种方法定义了所需的 BookingService RPC 集：

// Manages slot availability, leases and bookings for an inventory of
// appointments
service BookingService {
  // Gets availability information for an appointment slot
  rpc CheckAvailability(CheckAvailabilityRequest)
      returns (CheckAvailabilityResponse) {}

  // Creates a booking
  rpc CreateBooking(CreateBookingRequest) returns (CreateBookingResponse) {}

  // Updates an existing booking
  rpc UpdateBooking(UpdateBookingRequest) returns (UpdateBookingResponse) {}

  // Gets status for an existing booking
  rpc GetBookingStatus(GetBookingStatusRequest)
      returns (GetBookingStatusResponse) {}

  // Lists all upcoming bookings for a user
  rpc ListBookings(ListBookingsRequest) returns (ListBookingsResponse) {}
}

流程：创建预订

图 1：从空档创建预订

用户创建预订后，Google 会向合作伙伴发送用户的名字、姓氏、电话号码和电子邮件地址。从合作伙伴的角度来看，这应被视为游客结账，因为 Google 易行事中心无法在合作伙伴的系统中查找用户的账号。最终的预订信息应显示在合作伙伴商家的系统中，就像通过合作伙伴的预订系统进行的预订一样。

Java 中的框架实现

首先，我们提供了一个可编译和安装的 Java 版 gRPC 服务器框架。如需了解详情，请参阅 Samples > gRPC Reference Implementation 部分。此服务器已桩出支持集成所需的 gRPC 方法，包括身份验证和健康服务。

要求

gRPC 错误和业务逻辑错误

合作伙伴后端处理 gRPC 请求时可能会出现两种类型的错误：由数据错误引起的意外错误；以及表明无法创建或更新预订的业务逻辑错误（请参阅预订失败），例如请求的空档不可用。

如果遇到意外错误，应使用规范的 gRPC 错误代码将其返回给客户端。相关信号的示例包括但不限于：

  • INVALID_ARGUMENT 用于 CheckAvailability 和 CreateLease 等 RPC，如果提供的槽包含无效信息，则应返回此错误。
  • NOT_FOUND 用于 CreateBooking 和 ListBookings 等 RPC，如果合作伙伴不知道提供的标识符，则应返回此错误代码。

请参阅各个方法的参考文档，了解其规范 gRPC 错误代码，或参阅完整状态代码列表。

相反，应在预订失败中捕获业务逻辑错误，并在 RPC 响应中返回。创建或更新资源（即处理 RPC CreateBooking 和 UpdatingBooking）时可能会遇到业务逻辑错误。相关信号的示例包括但不限于：

  • 如果请求的空档不再可用，请使用 SLOT_UNAVAILABLE。
  • 如果不接受所提供的信用卡类型，请使用 PAYMENT_ERROR_CARD_TYPE_REJECTED。

幂等性

通过网络进行的通信并非始终可靠，如果 Google 预订未收到任何响应，可能会重试 RPC。因此，更改状态的所有 RPC（CreateBooking、UpdateBooking）都必须具有幂等性。这些 RPC 的请求消息包含幂等性令牌，用于唯一标识请求，并允许合作伙伴区分重新提交的 RPC（旨在创建单个预订）和两个单独的预订。

相关信号的示例包括但不限于：

  • 成功的 CreateBooking RPC 响应包含创建的预订，在某些情况下，会将付款作为预订流程的一部分。如果再次收到完全相同的 CreateBookingRequest（包括 idempotency_token），则必须返回相同的 CreateBookingResponse。系统不会再次创建预订，且仅向用户收取一次费用（如适用）。请注意，如果 CreateBooking 尝试失败，如果再次发送同一请求，合作伙伴后端应重试。

幂等性要求适用于包含幂等性令牌的所有方法。

gRPC 服务器安全和身份验证

您需要使用 SSL/TLS 通过基于证书的双向客户端/服务器身份验证来保护从 Action Center 到后端的调用。这需要为 gRPC 实现使用有效的服务器证书，并接受有效的客户端证书。

服务器证书：合作伙伴服务器必须配备与服务器域名关联的有效服务器证书（请参阅此接受的根 CA 列表）。GRPC 服务器实现应提供一条可追溯到根证书的证书链。实现此目的的最简单方法是将合作伙伴的 Web 托管服务提供的 PEM 格式中间证书附加到服务器证书（也采用 PEM 格式）。

系统会在连接时验证服务器证书，并且不接受自签名证书。只要证书有效，系统就不会检查实际证书内容。您可以通过以下命令检查证书的有效性：

echo "" | openssl s_client  -connect YOUR_URL:YOUR_PORT  -showcerts -CApath /etc/ssl/certs

客户端证书：为了向合作伙伴证明我们（Google）的身份，我们会提供由 Google Internet Authority G2 颁发的客户端证书（CA 证书），该证书具有以下属性：

字段 值
CN mapsbooking.businesslink-3.net
SAN DNS：mapsbooking.businesslink-3.net

合作伙伴服务器应拒绝未使用此客户端证书的连接尝试。

为了验证客户端证书，服务器依赖于一组可信客户端根证书。您可以选择从 Mozilla 等权威机构获取这组可信根，也可以安装 Google Internet Authority G2 目前推荐的一组根。在这两种情况下，您有时可能需要手动更新根证书。

实现 gRPC 健康检查协议

实现 GRPC 健康检查协议。借助此协议，Google 可以监控 gRPC 实现的后端状态。服务规范是 GRPC 发行版的一部分。根据 GRPC 命名惯例，健康检查调用中的服务名称为 API v2 的 ext.maps.booking.partner.v2.BookingService，或 API v0 的 ext.maps.booking.partner.v0.BookingService。健康检查应在与其他端点相同的网址和端口上运行。

其他版本

如需查看其他 API 版本的文档，请参阅以下页面： * API v3 * API v0