设计实时更新的结构

实时更新的使用场景

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

  • 当用户在您的系统上取消预订并且相应空档变为可用时。
  • 当用户通过操作中心预订时，可用性空档不再可用。
  • 当您方面通过 Actions 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": "2014-10-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

可用性替换 RTU

有两种类型的替换方法可用于更新可用性：

  • 批量替换 (InventoryUpdate.BatchServiceAvailability)：完全替换一个商家和多项服务的可用性数据。
    • 注意：此批量调用不保证原子性。系统将仅返回已成功更新的可用性空档。
  • 单次替换 (InventoryUpdate.ReplaceServiceAvailability)：完全替换单个商家和服务的库存状况。

如需了解详情，请使用以下参考。

实时更新必须使用与通过 Feed 发送的数据相同的可用性结构。他们必须使用以下其中一项：

  • spotsOpen
  • recurrence

选择要调用的替换方法

您可以参考以下指南来确定哪种替换方法更合适：

  • 一项预订会影响多项服务吗？例如，一个发型师预订了理发和着色服务（每项都是不同的服务），因此在相应时间段与造型师关联的所有服务都应移除。
  • 您的系统会不时地通过发送自上次更新以来的所有可用性变更与 Google 同步（不推荐）。
    • 批量替换
    • 注意：我们预计 Inventory RTU 会在您进行更新后的 5 分钟内发送。因此，您至少应该每 5 分钟检查并发送一次更新。
  • 以上选项皆不适用？
    • 单次替换
    • 注意：您可以使用多个单个替换调用来模拟批量替换调用，但使用单个批量替换调用会更高效

实时动态：Spots Open 格式

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

spots_open Feed 代码段如下所示：

Feed 代码段

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

对于 Inventory Update API，当预订下午 3:30 的空档时对应的请求正文格式如下：

替换实时更新代码段

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
        "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2014-10-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": 1412263800, # October 02, 2014 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 空档时的替换请求正文格式如下所示：

  {
    "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 系统之间保持同步。