此页面由 Cloud Translation API 翻译。

第 5 步：实现实时 API 更新

由于商家的新预订、取消和时间安排变更，您系统中的库存在一天中会出现波动。实时更新 API 是一种将商品目录可用性变化告知 Google 的机制。您还可以使用实时的 API 更新，通知 Google 对现有预订所做的更改。

API 的实时更新和 Feed

API 实时更新用于将库存可用性和预订的实时增量更改通知 Google。除了实时 API 更新之外，您每天都应发送完整的可用性 Feed，以确保 Google 与您系统中的可用性信息完全一致，并且是最新的。完整的 Feed 可用作您系统中商品目录可用性的当前状态的快照。

虽然 API 更新可用于更新由 Feed 提供的任何信息（例如与商家和服务相关的信息），但它们通常仅用于更新库存状况信息。

需要实时更新的 API

需要实时更新 (RTU) 的 API
BookingNotification	必须	只要预订发生变化（例如修改或取消），系统就会发送 BookingNotification RTU。
可用性替换 RTU	随条件发生变化[1]	发送批量替换或单个替换 RTU，以发送关于商品目录可用性的更新。更改可能需要几分钟才能传播和生效。
商家 RTU	可选	如果您想实时更改商家信息，请发送商家 RTU。更改可能需要几个小时才能传播和生效。
服务 RTU	可选	如果您想实时更改服务信息，请发送服务 RTU。一种常见的使用场景是，如果服务价格在白天急剧波动，建议实现服务 RTU，以避免因价格不匹配而导致订单失败。更改可能需要几个小时才能传播和生效。

可用性替换 API RTU

请在以下用例中使用 Availability Replace API 提供可用性更新：

用户在您的系统上预订，因此可用性空档不再可用。
商家在您的系统中更改了可用性。
用户通过 Google 预订，因此可用性空档不再可用。
通过 Google 进行的预订由您这一方取消，例如商家直接取消。您需要更新预订信息以及空房情况，因为原来的空档现在又可以重新预订了。
预订服务器 BatchAvailabilityLookup 调用返回的商品目录与实际商品目录不匹配。

如需了解详情，请参阅以下资源：

Booking Notification API RTU

Booking Notification API 会将现有预订的更新通知 Google。发送有关取消的更新时，请仅使用 updateMask 查询参数在请求中发送重要信息。示例如下：

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

访问 API

创建服务账号

您可以使用 Google API 控制台中的凭据标签页创建服务帐号。将 JSON 格式的私钥存储在安全的位置。创建帐号时，您可以选择将角色设置为“所有者”。

对 Maps Booking API 进行身份验证

创建服务账号后，请对以下 API 进行身份验证：

Google Maps Booking API
Google Maps Booking API（开发者版）

有关如何执行此操作的分步指南，请参阅使用 Maps Booking API 进行身份验证教程。

使用 RESTful 调用或者下载客户端库

我们建议您使用 JSON 载荷直接对 Maps Booking API 进行 RESTful 调用。如需了解详情，请参阅 REST API 文档。

您还可以通过客户端库连接到 API。

语言	下载链接
Java	Java 客户端库。如需了解详情，请参阅 Java 客户端说明。

您还可下载其他支持库，这些库用于处理对 Google API 调用的授权和其他方面。如果需要，请查看这些示例。

提取发现文档

对于某些客户端库（例如 Ruby），您需要提取 API 的发现文档，该文档介绍了其方法和参数。

使用以下命令提取发现文档：

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

如需详细了解如何从 Ruby 访问此 API，请访问以下链接：Ruby API 客户端和 Ruby Auth 库。

对 API 进行已获授权的调用

调用 API 时，请参阅准备进行已获授权的 API 调用，使用您的私钥和以下 OAuth 范围向您的服务帐号授权：https://www.googleapis.com/auth/mapsbooking。

API 配额

API 更新的配额为每 60 秒 1500 个请求，即平均每秒 25 个请求。当超出配额（如果您尚未在合作伙伴门户中添加正确的 Google Cloud 项目编号，就会发生这种情况）时，Google 会返回以下错误消息：

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

如需解决此问题，请以指数级更大的间隔再次重试调用，直到调用成功为止。如果您经常使用 ReplaceServiceAvailability 耗尽配额，请切换到 BatchReplaceServiceAvailabily 以减少 API 调用次数。利用此方法，您可以在单次 API 调用中更新多项服务。

沙盒环境和生产环境中的端点

您可以通过该 API 调用沙盒环境和生产环境。请务必在 Google Cloud 项目中启用这两个 API。这两种 API 使用同一范围，但端点不同。

生产端点：https://mapsbooking.googleapis.com/

沙盒端点：https://partnerdev-mapsbooking.googleapis.com/

以下是有关如何切换端点的 Java 示例：

    // This block of code is for OAuth and is the same for prod and sandbox.
    GoogleCredential
      .fromStream(new FileInputStream(...))
      .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)
      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
      .build()

第 4 步：实现预订服务器

第 6 步：端到端测试