您需要建立一个预订服务器,以允许“通过 Google 预订”代表您进行创建和更新预订的回调。
- 标准实现。这样,“通过 Google 预订”就可以代表用户创建预约和预订。
请参阅合作伙伴门户文档,了解如何配置与沙盒和生产预订服务器的连接。
实现 REST API 接口
实现基于 REST 的 API 接口。这样 Google 就可以通过 HTTP 发送预订服务器请求。
首先,请设置一个可连接到“通过 Google 预订”沙盒环境的开发或沙盒预订服务器。只有在对沙盒服务器进行全面测试后,才能将其切换到生产环境。
方法
对于每种类型的预订服务器,您都需要使用不同的一组 API 方法。您也可以选择下载 proto 格式的服务定义,以开始使用 API 实现。下表显示了每种实现的方法,并包含指向服务 proto 格式的链接。
标准实现 |
---|
标准服务定义:下载 proto 服务定义文件。 |
方法 | HTTP 请求 |
---|---|
HealthCheck | GET /v3/HealthCheck/ |
BatchAvailabilityLookup | POST /v3/BatchAvailabilityLookup/ |
CreateBooking | POST /v3/CreateBooking/ |
UpdateBooking | POST /v3/UpdateBooking/ |
GetBookingStatus | POST /v3/GetBookingStatus/ |
ListBookings | POST /v3/ListBookings/ |
API 资源
预订
标准实现需要以下资源类型:
流程:创建预订
本部分介绍了如何为标准实现创建预订。
用户创建预订后,Google 会向您发送用户的名字、姓氏、电话号码和电子邮件地址。从您的角度来看,需要将此预订视为游客结帐,因为“通过 Google 预订”无法在您的系统中查找用户的帐号。确保最终的预订信息与您的商家通过系统完成的预订信息一致。
安全和身份验证
与预订服务器的所有通信均通过 HTTPS 进行,因此您的服务器必须具有与其 DNS 名称匹配的有效 TLS 证书。为了帮助设置服务器,我们建议您使用可公开访问的 SSL/TLS 验证工具,例如 Qualys 的 SSL 服务器测试。
Google 将向预订服务器发出的所有请求都将使用 HTTP 基本身份验证机制进行身份验证。您可以在合作伙伴门户的“预订服务器配置”页面中输入预订服务器的基本身份验证凭据(用户名和密码)。必须每 6 个月轮替一次密码。
框架实现示例
首先,请查看为 Node.js 和 Java 框架编写的预订服务器的以下示例框架:
- Node.js 框架 js-maps-booking-rest-server-v3-skeleton
- Java 框架 java-maps-booking-rest-server-v3-skeleton
这些服务器已弃用 REST 方法。
要求
HTTP 错误和业务逻辑错误
在后端处理 HTTP 请求时,可能会出现两种类型的错误。
- 与基础架构或数据不正确相关的错误
- 使用标准 HTTP 错误代码将这些错误返回给客户端。请参阅完整的 HTTP 状态代码列表。
- 与业务逻辑相关的错误
- 返回设置为
200
确定的 HTTP 状态代码,并在响应正文中指定业务逻辑故障。对于不同类型的服务器实现,您可能会遇到的业务逻辑错误类型会有所不同。
- 返回设置为
对于标准实现,预订失败会捕获可能的业务逻辑错误,这些错误会在 HTTP 响应中返回。创建或更新资源时可能会遇到业务逻辑错误。例如,当您处理 CreateBooking
或 UpdatingBooking
方法时。相关示例包括但不限于:
- 如果请求的空档不再可用,则使用
SLOT_UNAVAILABLE
。 - 如果不接受所提供的信用卡类型,请使用
PAYMENT_ERROR_CARD_TYPE_REJECTED
。
幂等性
通过网络进行的通信并非始终可靠,如果 Google 未收到响应,可能会重试 HTTP 请求。因此,更改状态的所有方法都必须具有幂等性:
CreateBooking
UpdateBooking
对于除 UpdateBooking
之外的所有请求消息,系统都会添加幂等性令牌以唯一标识请求。这样,您就可以区分重试的 REST 调用(意在创建一个请求)和两个单独的请求。UpdateBooking
分别由其预订条目 ID 唯一标识,因此其请求不包含幂等令牌。
以下是一些有关预订服务器如何处理幂等性的示例:
成功的
CreateBooking
HTTP 响应包括创建的预订。在某些情况下,付款会在预订流程中进行处理。如果再次收到完全相同的CreateBookingRequest
(具有同一idempotency_token
),则必须返回相同的CreateBookingResponse
。系统不会再次创建预订,且只会向用户收取一次费用(如果适用)。请注意,如果
CreateBooking
尝试失败,且重新发送了同一请求,在这种情况下,您的后端应重试该请求。
幂等性要求适用于更改状态的所有方法。