建立即時更新架構

即時更新的用途

在下列情況下，必須一律發出即時更新：

  • 使用者在系統上取消預訂，導致該時段變成可預訂。
  • 使用者透過 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": "2025-01-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

供應情形取代 RTU

更新供應情形時，你可以使用兩種取代方法：

  • 批次取代 (InventoryUpdate.BatchServiceAvailability)： 完全取代多個商家和服務的供應情形資料。
    • 注意：這項批次呼叫不保證不可分割性。系統只會傳回成功更新的供應時段。
  • 單一取代 (InventoryUpdate.ReplaceServiceAvailability)： 完全取代單一商家和服務的供應情形。

詳情請參閱以下參考資料。

即時更新必須使用與透過動態饋給傳送的資料相同的可用性結構。必須使用下列其中一種方式：

  • spotsOpen
  • recurrence

選擇要呼叫的替換方法

請參考下列指南，判斷哪種取代方法較為合適：

  • 是否影響到多個商家？例如，在單一要求中取代多個商家的供應情形。
  • 你的系統會不時與 Google 同步，方法是傳送自上次更新以來的所有可用性變更 (不建議)。
    • 批次取代
    • 注意：我們預計在您更新後的 5 分鐘內，就會傳送廣告空間 RTU。因此，您應至少每 5 分鐘檢查一次並傳送任何更新。
  • 以上皆不適用，或您只需要更新單一商家和服務嗎？
    • 單一取代
    • 注意：您可以使用多個單一取代呼叫來模擬批次取代呼叫，但使用單一批次取代呼叫會更有效率

即時更新：時段開放格式

請務必在動態饋給、預訂伺服器和即時更新中使用相同的格式。

spots_open 動態饋給摘要如下所示：

動態消息摘要

   "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 分鐘時段已預訂，則取代要求主體格式如下：

取代即時更新程式碼片段

  {
    "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 分鐘時段預約成功，下一個每日動態饋給會如何顯示：

動態消息摘要

"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"
        }
      ]

即時更新：重複週期格式

請務必在動態饋給、預訂伺服器和即時更新中使用相同的格式。

使用週期性的動態饋給如下所示：

動態消息摘要

  "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"
                }
              }
            ]
          }
        ]
      }
    ]
  }

以下是下一個每日動態饋給的預期內容。請注意，這項資訊是該商家提供的所有服務，以及所有先前和新 schedule_exceptions 的供應情形：

動態消息摘要

   "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
              }
            }
          ],
        }
      ]

提交即時更新的時機

供應情形有任何變動時，即時更新應持續傳送。除了完整的供應情形動態饋給 (應每天提交一次)，您還必須提交這項資訊，確保您和 Google 的系統之間的供應情形同步。