实现预订服务器：API v2

在您的后端设置预订服务器后，Actions Center 便可以用户的身份向您创建预约/预订。

实现基于 gRPC 的 API 接口

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

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

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

本部分介绍了一组推荐的 API v2。它适用于尚未实现 API v0 的合作伙伴。对于已实现 API v0 的现有合作伙伴，请与操作中心联系以了解详情。

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

流程：创建预订

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

Java 中的框架实现

为了帮助您入门，我们提供了一个可编译和安装的 Java 版 gRPC 框架服务器。您可以在示例 > gRPC 参考实现部分中查看。此服务器已为支持集成所需的 gRPC 方法（包括身份验证和健康服务）创建了桩。

要求

gRPC 错误和业务逻辑错误

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

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

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

如需了解每种方法的规范 gRPC 错误代码，请参阅相应方法的参考文档，或查看完整的状态代码列表。

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

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

幂等性

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

gRPC 服务器安全性和身份验证

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

服务器证书：合作伙伴服务器必须配备与服务器域名关联的有效服务器证书（请参阅可接受的根 CA 列表）。 GRPC 服务器实现需要提供通向根证书的证书链。最简单的方法是将合作伙伴的网络托管服务商提供的 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