由於商家的新預訂、取消和排程變更,系統中的商品目錄在一天當中會不斷波動。即時更新 API 是一種通知 Google 服務供應情況異動的機制。此外,您也可以利用即時 API 更新,通知 Google 有關現有預訂的異動。
API 即時更新和動態饋給
API 即時更新功能是用來 即時通知 Google 有關庫存供應情形和預訂的增量變更。除了即時 API 更新之外,您也可以每天傳送完整的供應情形動態饋給,確保 Google 掌握最準確且最新的供應情形資訊,並存在於您的系統中。完整的動態饋給可做為數據匯報,讓我們瞭解系統中商品目錄目前的供應情形。
雖然 API 更新可用於更新動態饋給提供的任何資訊 (例如商家與服務相關資訊),但這類更新通常只會用來更新供應情形資訊。
必要的即時更新 API
即時更新 (RTU) API | ||
---|---|---|
BookingNotification | 必要項目 | 每當預訂變更 (例如修改或取消) 時,就傳送 BookingNotification RTU。 |
供應情形取代 RTU | 有條件限制的必要項目 [1] | 傳送批次取代或單一取代 RTU,以便將更新資訊傳送至商品目錄供應情形。變更可能需要幾分鐘的時間才會生效。 |
商家 RTU | 選用 | 如要即時變更商家資訊,請傳送商家 RTU。變更可能需要數小時才會生效。 |
服務 RTU | 選用 | 如果您想即時變更服務資訊,請傳送服務 RTU。常見的情況是,如果服務價格會在白天大幅波動,建議您導入服務 RTU,以免因價格不符而導致訂單失敗。變更可能需要數小時才會全面生效及反映。 |
Availability Replace API RTU
針對以下用途,請使用 AvailabilityReplace API 提供供應情形更新資訊:
- 有使用者在您的系統上進行預訂,因此該時段已無法預訂。
- 商家在您的系統中變更了供應情形。
- 使用者透過 Google 進行預訂,因此該時段已無法預訂。
- 由您這端取消了透過 Google 進行的預訂,例如由商家直接取消。由於原本的時段已重新開放預訂,因此您必須更新該預訂及供應情形。
- 預訂伺服器
BatchAvailabilityLookup
呼叫傳回的庫存與實際庫存不符。
詳情請參閱下列資源:
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 的「探索」文件,其中會說明方法和參數。
使用下列指令擷取「探索」文件:
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()