构建实时更新

实时更新的应用场景

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

  • 当用户取消通过您的系统进行的预订时，相应空档会变为可用状态。
  • 当用户通过操作中心完成了一项预订，但相应可用性空档不再可预订时。
  • 通过 Action Center 完成的预订由您这一方取消（例如商家直接取消）。您需要更新预订信息及可用性，因为原来的空档已恢复为可预订状态。

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

  • 当商家在您的系统中更改其日程安排（可用性）时。
  • 当用户通过您的系统完成了一项预订，导致相应可用性空档不再可预订时。
  • 如果您使用的是与 CheckAvailability 的旧版集成，则当预订服务器 CheckAvailability 调用返回的商品目录与实际商品目录不匹配时，就会发生此问题。

并非所有 Maps Booking API 调用都是必需的。以下是强制性要求：

根据集成类型，您可能还需要或可以使用以下功能：

更新预订 RTU

如果您的系统对 Actions 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 分钟内发送 Inventory 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 之外，您还应使用此 API，以确保您和 Google 的系统之间的可用性保持同步。