实现预订服务器：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 方法：

• CheckAvailability
• CreateBooking
• UpdateBooking
• GetBookingStatus
• ListBookings

以下 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) {}
}

流程：创建预订

用户创建预订后，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 证书），该证书具有以下属性：

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

为了验证客户端证书，服务器依赖于一组可信客户端根证书。您可以选择从 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