构建实时更新

实时更新的用例

在以下情况下，必须始终发出实时更新：

  • 当用户在您的系统上取消预订，相应空档变为空闲时。
  • 用户通过 Action Center 预订了某个空档，但该空档已被预订。
  • 通过 Google 易购中心完成的预订由您这一方取消（例如商家直接取消）。您需要更新预订信息及空房情况，因为原来的空档已恢复为可预订状态。

此外，如果您实现了可用性替换 RTU，则应在以下情况下发出实时更新：

  • 商家在您的系统中更改了时间表（可用性）。
  • 当用户在您的系统上预订了某个空档，而该空档已不再可预订时。
  • 如果您使用的是旧版 CheckAvailability 集成，当预订服务器 CheckAvailability 调用返回的商品目录与实际的商品目录不匹配时，

并非所有 Maps Booking API 调用都是必需的。以下是必填项：

根据集成类型，您可能还需要执行以下操作或满足以下要求：

更新预订 RTU

如果您在系统中更新了 Action Center 预订（例如取消或修改），则必须发送 notification.partners.bookings.patch (BookingNotification.UpdateBooking)。

可修改的字段

  • status
  • startTime
  • duration
  • partySize
  • paymentInformation.prepaymentStatus

取消示例

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

Body:
{
  "name": "partners/<PARTNER_ID>/bookings/<BOOKING_ID>",
  "merchantId": "10001",
  "serviceId": "1001",
  "startTime": "2025-01-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

可用性替换 RTU

您可以使用两种替换方法来更新空房情况：

  • 批量替换 (InventoryUpdate.BatchServiceAvailability)：彻底替换多个商家和服务的可用性数据。
    • 注意：此批量调用不保证原子性，仅返回成功更新的可用性空档。
  • 单个替换 (InventoryUpdate.ReplaceServiceAvailability)：彻底替换单个商家和服务的可用性。

如需了解详情，请参阅以下参考文档。

实时更新必须使用与通过 Feed 发送的数据相同的播出信息结构。他们必须使用以下任一方式：

  • spotsOpen
  • recurrence

选择要调用的替换方法

请使用以下指南帮助您确定哪种替换方法更适合：

  • 是否有多个商家受到影响？例如，在一个请求中替换多个商家的空房情况。
  • 您的系统会不时与 Google 的系统同步，方法是发送自上次更新以来的所有库存状况更改（不推荐）。
    • 批量替换
    • 注意：我们预计会在您进行更新后的 5 分钟内发送商品目录 RTU。因此，您应至少每 5 分钟检查并发送一次更新。
  • 以上情况都不适用，或者您只需更新单个商家和服务？
    • 单次替换
    • 注意：您可以使用多个单次替换调用来模拟批量替换调用，但使用单次批量替换调用会更高效

实时更新：广告插播 - 公开格式

请务必在 Feed、预订服务器和实时更新中使用相同的格式。

spots_open Feed 代码段如下所示：

Feed 摘要

   "availability": [
          {
            "merchant_id": "1001",
            "service_id": "12310",
            "spots_open": 2,
            "spots_total": 2,
            "start_sec": 1735831800, # January 02, 2025 15:30:00
            "duration_sec": 1800,
            "availabilityTag": "1000001"
          }
    ]

对于 Inventory Update API，当 3:30 PM 时段被预订时，替换请求正文格式如下：

替换实时更新摘要

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2025-01-02T15:01:23.045123456Z",
        "endTimeRestrict": "2025-01-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2025-01-02T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "spotsTotal": "2",
            "availabilityTag": "1000001"
          }
        ]
      }
    ]
  }

下面的示例展示了如果有人预订了下午 3:30 的新空档，那么下一个每日 Feed 中预计会显示的内容：

Feed 摘要

"availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 2,
          "start_sec": 1735831800, # January 02, 2025 15:30:00
          "duration_sec": 1800,
          "availabilityTag": "1000001"
        }
      ]

实时更新：重复设置格式

请务必在 Feed、预订服务器和实时更新中使用相同的格式。

使用重复设置的 Feed 如下所示：

Feed 摘要

  "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            }
          ],
        }
      ]

对于 Inventory Update API，当 3:30 PM 的空档被预订时，替换请求正文格式如下所示：

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2018-10-30T15:01:23.045123456Z",
        "endTimeRestrict": "2018-10-30T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2018-10-30T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "scheduleException": [
             {
                "timeRange": {
                  "startTime": "2018-10-30T12:30:00.00Z",
                  "endTime": "2018-10-30T13:00:00.00Z"
                }
              },
              {
                "timeRange": {
                  "startTime": "2018-10-30T15:30:00.00Z",
                  "endTime": "2018-10-30T16:00:00.00Z"
                }
              }
            ]
          }
        ]
      }
    ]
  }

下面的示例展示了下一个每日 Feed 中应包含的内容。请注意，这是该商家整个服务的可用性，以及其所有旧版和新版 schedule_exceptions：

Feed 摘要

   "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            },
            {
              "time_range": {
                "begin_sec": 1540913400, # October 30, 2018 3:30:00 PM
                "end_sec": 1540915200 # October 30, 2018 4:00:00 PM
              }
            }
          ],
        }
      ]

何时提交实时更新

每当播出信息发生变化时，都应持续发送实时更新。除了应每天提交一次的全面库存状况 Feed 之外，您还应提交此类 Feed，以确保您的系统与 Google 的系统之间同步库存状况。