即時 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 用戶端範例
• Inventory update 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 酬載，直接呼叫符合 REST 樣式的 Maps Booking API。詳情請參閱 REST API 說明文件。

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

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

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

擷取「探索」文件

部分用戶端程式庫 (例如 Ruby) 需要為 API 擷取「探索」文件，其中會說明 API 的方法和參數。

使用以下指令擷取「探索」文件：

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

如要進一步瞭解如何透過 Ruby 存取 API，請點選下列連結：Ruby API Client 和 Ruby Auth Library。

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