实现预订服务器:API v2

在您的端设置预订服务器后,Actions Center 就可以代表用户为您创建预约 / 预订 / 预订操作。

实现基于 gRPC 的 API 接口

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

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

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

本部分将介绍一组推荐的 API v2。适用于尚未实现 API v0 的合作伙伴。对于已实现 API v0 的当前合作伙伴,请与 Actions 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 会向合作伙伴发送用户的名字、姓氏、电话号码和电子邮件地址。从合作伙伴的角度来看,这应被视为访客结账,因为 Actions Center 无法在合作伙伴的系统中查找用户的帐号。最终预订应在合作伙伴系统中向合作伙伴的商家显示,就像合作伙伴预订系统收到的预订一样。

Java 框架实现

首先,我们使用 Java 提供一个可以编译和安装的 gRPC 框架服务器。在示例 > gRPC 参考实现部分下查看。此服务器已经排除了支持集成(包括身份验证和健康服务)所需的 gRPC 方法。

要求

gRPC 错误和业务逻辑错误

在合作伙伴后端处理 gRPC 请求时可能会发生两种类型的错误:错误数据引起的意外错误;以及表示无法创建或更新预订的业务逻辑错误(请参阅预订失败),例如,如果请求的空档不可用。

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

  • INVALID_STRING 用于 CheckAvailability 和 CreateLease 等 RPC,如果提供的槽包含无效信息,则应返回。
  • NOT_FOUND 用于 CreateBooking 和 ListBookings 等 RPC。如果合作伙伴不知道提供的标识符,则应返回该类型。

请参阅每种方法的参考信息,了解其规范 gRPC 错误代码,或查看完整的状态代码列表

相反,业务逻辑错误应该在 Booking Failure 中捕获,并在 RPC 响应中返回。创建或更新资源(即处理 RPC CreateBooking 和 UpdatedBooking)时,可能会遇到业务逻辑错误。相关示例包括但不限于:

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

幂等性

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

相关示例包括但不限于:

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

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

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 命名惯例,健康检查调用中的服务名称为 ext.maps.booking.partner.v2.BookingService(对于 API v2)或 ext.maps.booking.partner.v0.BookingService(对于 API v0)。健康检查应在与其他端点相同的网址和端口上运行。

其他版本

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