即時 API 更新

由於您的商家可能會有新的預訂、取消和排程變更，因此系統中的供應量一整天都會跟著波動。即時更新 API 是一種能讓 Google 掌握供應存量情形變動的機制。此外，您也可以利用即時 API 更新來通知 Google 有關現有預訂的異動。

如果所有商家都使用等候名單功能，就不必進行即時更新。

API 即時更新和動態饋給

API 即時更新功能是用來即時通知 Google 有關供應存量情形及預訂的漸進式變更。除了即時 API 更新，也請每天傳送完整的「供應情形」動態饋給，以便 Google 隨時掌握您目前系統中有關供應情形的最新正確資訊。完整的動態饋給可做為數據匯報，讓我們瞭解您目前系統中供應存量情形的最新狀態。

雖然 API 更新可用來更新由動態饋給提供的任何資訊 (例如商家與服務相關資訊)，但通常只會用來更新供應情形資訊。

必要的即時更新 API

即時更新 (RTU) API
BookingNotification	必要項目	每當預訂發生變更 (例如修改或取消)，就傳送 BookingNotification RTU。
供應情形取代 RTU	有條件限制的必要項目 [1]	傳送批次取代或單一取代 RTU，以傳送供應情形更新資訊。變更可能需要幾分鐘才會全面生效。
商家 RTU	選用	如果您想即時變更商家資訊，請傳送商家 RTU。變更可能需要數小時才能全面生效。
服務 RTU	選用	如果您想即時變更服務資訊，請傳送服務 RTU。常見的適用情況像是當服務價格在一天中會大幅波動時，您就可以導入服務 RTU，以免因價格不符而導致訂單處理失敗。變更可能需要數小時才能全面生效。

注意：這個端點的規定會依據您的整合服務而有所不同。請洽詢您的 Google 聯絡人，以確認哪些端點是必要的。

Availability Replace API RTU

針對以下情況，請使用 Availability Replace API 提供供應情形更新資訊：

• 有使用者在您的系統上進行預訂，因此該供應時段已無法預訂。
• 商家在您的系統中變更了供應情形。
• 有使用者透過 Google 進行預訂，因此該供應時段已無法預訂。
• 由您這端取消了某筆透過 Google 進行的預訂 (例如由商家直接取消)。由於原本的時段現已重新開放預訂，因此您必須更新該預訂以及供應情形。
• 預訂伺服器 BatchAvailabilityLookup 呼叫傳回與實際情況不符的存量資訊。

詳情請參閱下列資源：

• 教學課程：如何建立即時更新結構
• 使用符合 REST 樣式的呼叫進行即時更新 (Java 用戶端範例)
• 存量更新 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 進行驗證」教學課程。

使用符合 REST 樣式的呼叫或下載用戶端程式庫

建議您使用 JSON 酬載直接對 Maps Booking API 執行符合 REST 樣式的呼叫。詳情請參閱 REST API 說明文件。

您也可以使用用戶端程式庫連線至 API。

語言	下載連結
Java	Java 用戶端程式庫。詳情請參閱 Java 用戶端操作說明。

您可以下載額外的支援資料庫，以用來處理授權及對 Google API 發出的其他方面的呼叫。如有需要，請查看這些範例。

擷取「探索」文件

針對特定用戶端程式庫 (例如 Ruby)，您必須為該 API 擷取「探索」文件，其中會說明 API 方法和參數。

使用下列指令擷取 Discovery 文件：

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()