实现预订服务器：API v2

在您这边设置预订服务器后，Actions Center 就可以执行以下操作： 代表用户与您创建预约 / 预订 / 预订信息。

实现基于 gRPC 的 API 接口

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

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

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

本部分介绍了一组建议的 API v2。它适用于 尚未实现 API v0。面向已实现 API 的当前合作伙伴 v0，请与操作中心联系以了解详情。

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

下载服务 定义

API 资源

请先熟悉以下资源类型 示例：

方法

您必须为 gRPC 服务器：

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

流程：创建预订

<ph type="x-smartling-placeholder">
</ph>
图 1：从以下来源创建预订： 槽

创建预订时，Google 会向合作伙伴发送用户的名字、 姓氏、电话号码和电子邮件地址。应将其视为 访客结账选项，因为操作中心没有 在合作伙伴系统中查找用户账号的方法。最终预订 应在合作伙伴系统中向合作伙伴的商家显示，就像显示预订信息一样 来自合作伙伴预订系统的消息

Java 中的框架实现

首先，我们提供了一个采用 Java 的 gRPC 框架服务器，该服务器可进行编译 和已安装。欢迎在 示例 >gRPC 参考实现 部分。此服务器已打桩支持这些 gRPC 方法 包括身份验证和健康服务。

要求

gRPC 错误和业务逻辑错误

在合作伙伴后端处理 gRPC 请求时，可能会发生两种类型的错误： 数据不正确导致的意外错误；错误和业务逻辑错误 表示无法创建或更新预订（请参阅预订 Failure）， 例如，如果请求的槽不可用。

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

  • INVALID_ARGUMENT 用于 CheckAvailability 和 CreateLease 等 RPC， 如果提供的广告位包含无效信息，则应返回此属性。
  • NOT_FOUND 用于 CreateBooking 和 ListBookings 等 RPC，应 如果合作伙伴不知道所提供的标识符，则返回 。

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

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

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

幂等性

通过网络进行的通信并非始终可靠，因此 Google 预订型广告资源可能会 如果未收到响应，则重试 RPC。因此，更改的所有 RPC 状态（CreateBooking、UpdateBooking）必须具有幂等性。请求消息： 这些 RPC 包含幂等令牌，可唯一标识请求并允许 合作伙伴来区分重试的 RPC（目的是创建 单个预订）和两个单独的预订。

相关示例包括但不限于：

  • 成功的 CreateBooking RPC 响应会包含已创建的预订，在某些情况下，付款 在预订流程中进行处理。如果创建预订请求 （包括 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 互联网目前推荐的一组根目录 授权方 G2。在 则有时可能需要手动更新根证书。

实现 gRPC 健康检查协议

实现 GRPC 健康检查 协议。 此协议使 Google 能够监控您的 gRPC 的后端状态 实施。服务 规范 是 GRPC 分发的一部分。按照 GRPC 命名惯例 “健康检查”调用中的服务账号 ext.maps.booking.partner.v2.BookingService（对于 API v2），或 ext.maps.booking.partner.v0.BookingService（适用于 API v0）。健康检查应该 在与其他端点相同的网址和 PORT 上运行。

其他版本

有关其他 API 版本的文档，请参阅以下页面： * API v3 * API v0