第 5 步：实时的 API 更新

您的系统中的商品目录会随着来自商家的预订、取消情况和时间安排的新变化在一天中出现波动。实时的 API 更新是一种机制，旨在将商品目录可用性的变化通知 Google。您还可以通过实时的 API 更新将现有预订的变化通知 Google。

API 的实时更新和 Feed

API 的实时更新用于将商品目录可用性和预订的实时增量变化通知 Google。除了实时更新 API，请每天发送完整的可用性 Feed，确保 Google 尽可能准确且及时地了解您系统中的可用性信息。完整的 Feed 可作为您系统中商品目录可用性的当前状态的快照。

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

需要实时更新的 API

可用性替换 API RTU

请在以下情况下使用可用性替换 API 更新可用性：

• 某个用户通过您的系统完成了一项预订，因此，相应可用性空档不再可预订。
• 商家在您的系统中更改了可用性。
• 某个用户通过 Google 完成了一项预订，因此，相应可用性空档不再可预订。
• 通过 Google 完成的预订由您这一方取消（例如商家直接取消）。您需要更新预订信息及空房情况，因为原来的空档已恢复为可预订状态。
• 预订服务器 BatchAvailabilityLookup 调用返回的商品目录与实际的商品目录不匹配。

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

• 教程：如何构建实时更新
• 通过 RESTful 调用进行实时更新的 Java 客户端示例
• Inventory update API 参考页面

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。

您还可下载其他支持库，以处理对 Google API 调用的授权及其他方面。如有需要，请参阅这些示例。

提取发现文档

对于部分客户端库（例如 Ruby），有必要提取 API 发现文档，该文档中介绍了相关方法及参数。

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

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

如需详细了解如何使用来自 Ruby 的 API，请访问以下链接：Ruby API 客户端和 Ruby 身份验证库。

对 API 进行已获授权的调用

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

API 配额

API 更新的配额为每 60 秒 1,500 个请求，即平均每秒 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()