由於商家的新預訂、取消和排程有所變動,您的系統中的廣告空間會在一天之內波動。即時更新 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
在下列應用實例中,使用 Availability Replace 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 酬載,直接呼叫符合 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()