您需要创建预订服务器,以允许 Actions Center 进行回调,以便代表您创建和更新预订。
- 预订等位名单实现。当您参与预订等位名单试行计划时,将使用此号码。这样,操作中心就可以检索预计等待时间,并代表用户创建候位名单条目。
- 标准实现。这样,Actions Center 就可以代表用户创建预约、预订和预订。如需为预订端到端集成实现预订服务器,请参阅实现预订服务器。
请参阅合作伙伴门户文档,了解如何配置与沙盒和生产环境预订服务器的连接。
实现 REST API 接口
实现基于 REST 的 API 接口,以便 Google 能够通过 HTTP 发送预订服务器请求。
首先,请设置一个可连接到 Actions Center 沙盒环境的开发或沙盒预订服务器。请仅在沙盒服务器经过全面测试后再迁移到生产环境。
方法
对于每种类型的预订服务器,您都需要使用不同的 API 方法。您也可以选择下载 proto 格式的服务定义,以便开始进行 API 实现。下表显示了每种实现的方法,并添加了指向服务 proto 格式的链接。
候位名单实现 |
---|
候位名单服务定义。下载 proto 服务定义文件。 |
方法 | HTTP 请求 |
---|---|
HealthCheck | GET /v3/HealthCheck/ |
BatchGetWaitEstimates | POST /v3/BatchGetWaitEstimates/ |
CreateWaitlistEntry | POST /v3/CreateWaitlistEntry/ |
GetWaitlistEntry | POST /v3/GetWaitlistEntry/ |
DeleteWaitlistEntry | POST /v3/DeleteWaitlistEntry/ |
API 资源
等位名单
可通过以下资源实现基于候位名单的预订:
- WaitEstimate:针对特定人数和商家的预计等待时间。
- WaitlistEntry:用户在候位名单中的条目。
流程:创建候位名单条目
本部分介绍如何为预订候位名单集成创建预订。
![图 2:创建候位名单条目的工作流程](https://developers.google.cn/static/actions-center/images/waitlists/rest_api_v3_waitlist_flow.png?authuser=9&hl=ca)
用户创建候位名单条目后,Google 会向您发送用户的名字、姓氏、电话号码和电子邮件地址。该电子邮件地址与用户的 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
OK 的 HTTP 状态代码,并在响应正文中指定业务逻辑失败。您可能会遇到的业务逻辑错误类型因服务器实现类型不同而异。
- 返回设置为
对于预留等位名单集成,系统会在候位名单业务逻辑故障中捕获业务逻辑错误,并在 HTTP 响应中返回这些错误。创建资源时(例如,当您处理 CreateWaitlistEntry
方法时),可能会遇到业务逻辑错误。这样的示例包括但不限于:
- 如果请求的候位名单条目超过了商家的就餐人数上限,请使用
ABOVE_MAX_PARTY_SIZE
。 - 如果等候名单因商家已关闭而未开放使用,会使用
MERCHANT_CLOSED
。
幂等性
通过网络进行的通信并非始终可靠,如果 Google 未收到任何响应,可能会重试 HTTP 请求。因此,更改状态的所有方法都必须具有幂等性:
CreateWaitlistEntry
DeleteWaitlistEntry
对于除 DeleteWaitlistEntry
之外的所有请求消息,都包括幂等令牌以唯一标识请求。这样,您就可以区分重试的 REST 调用(旨在创建单个请求)和两个单独的请求。
DeleteWaitlistEntry
分别由其候位名单条目 ID 进行唯一标识,因此其请求中不包含幂等性令牌。
以下是一些有关预订服务器如何处理幂等性的示例:
成功的
CreateWaitlistEntry
HTTP 响应包含已创建的候位名单条目 ID。如果再次收到同一个CreateWaitlistEntryRequest
(具有相同idempotency_token
),则必须返回相同的CreateWaitlistEntryResponse
。系统不会创建第二个候位名单条目,也不会返回任何错误。请注意,如果
CreateWaitlistEntry
尝试失败,且重新发送了同一请求,在这种情况下,您的后端应重试。
幂等性要求适用于更改状态的所有方法。