RTU 主要用於無法觀察的更新,例如緊急關閉,或是定期變動的中繼資料 (例如預計到達時間)。如果變更不需要立即反映,您可以改用批次動態饋給擷取功能。系統會在 5 分鐘內處理即時更新。
Google Cloud Platform 設定
- 設定 GCP 專案。需要 GCP 專案才能存取 RTU API。
- 授予編輯者存取權 food-support@google.com
- 將 GCP 專案編號告知 Google 聯絡窗口。您的 GCP 專案必須與 Actions Center 帳戶建立關聯,才能即時進行更新。
- 啟用 Maps Booking API:
- 在 GCP 中,前往「API 和服務」>「程式庫」。
- 搜尋「Google Maps Booking API」。
- 找到沙箱執行個體 (「Google Maps Booking API (Dev)」),然後按一下「啟用」
- 找到實際工作環境執行個體 (「Google Maps Booking API」),然後按一下「啟用」
- 建立具有 GCP 專案編輯者角色的服務帳戶。詳情請參閱服務帳戶設定。
- 請務必將批次動態饋給上傳至您要進行即時更新的環境。
- 針對 API 驗證,建議您以您選擇的語言安裝 Google 用戶端程式庫。使用「https://www.googleapis.com/auth/mapsbooking」做為 OAuth 範圍。下列程式碼範例使用這些程式庫。否則,您必須按照使用 OAuth 2.0 存取 Google API 一文所述的方式,手動處理權杖交換作業。
服務帳戶設定
您必須具備服務帳戶,才能向 Google API (例如即時更新 API) 發出通過驗證的 HTTPS 要求。
如要設定服務帳戶,請執行下列操作:
- 存取 Google Cloud Platform 控制台。
- 您在 Actions Center 上的帳戶也有相關聯的 Google Cloud 專案。如果尚未選取該專案,請選取該專案。
- 按一下左選單中的「服務帳戶」。
- 按一下「建立服務帳戶」。
- 輸入服務帳戶的名稱,然後按一下「建立」。
- 在「請選取角色」中,依序選擇「專案」>「編輯者」。
- 按一下「繼續」。
- 選用:新增使用者將服務帳戶存取權授予對方,然後按一下「完成」。
- 針對剛建立的服務帳戶,依序點選「more」(更多)>「建立金鑰」。
- 選擇「JSON」做為格式,然後按一下「建立」。
- 新的公開/私密金鑰組產生後,請下載到您的裝置上。
使用 API
Real-time Update API 支援兩種作業類型:Update 和 Delete。不支援透過即時更新 API 新增實體。如果您在單一 API 要求中加入多項更新,就可以批次處理即時更新。單一 API 呼叫最多可以批次處理 1,000 項更新。建議您盡可能採用以觸發條件為基礎的方法,透過 RTU 傳送更新 (即系統資料有所變更時,將即時更新傳送給 Google),而不要採用以頻率為準的做法 (也就是每 X 分鐘掃描系統是否有變更)。
即時更新 API 在沙箱和正式環境中都是運作。沙箱環境的用途是測試 API 要求和正式環境,以更新訂購端對端使用者可見的內容。
- 沙箱 -
partnerdev-mapsbooking.googleapis.com
- 正式版 -
mapsbooking.googleapis.com
端點
即時更新 API 會公開兩個端點,以處理傳入的庫存更新要求:
- 更新 -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
- 刪除 -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
您可以在「帳戶與使用者」頁面的動作中心中找到 PARTNER_ID 參數,如下方螢幕截圖所示。
![合作夥伴入口網站上的夥伴 ID](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/verticals/ordering/images/rtu-partnerid.png?authuser=3&hl=zh-tw)
以 10000001 做為 PARTNER_ID 的值,如上方螢幕截圖所示,在沙箱和正式環境中傳送 API 要求的完整網址,如以下範例所示。
沙箱更新
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
沙箱刪除
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
正式版更新
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
實際工作環境刪除
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
更新實體
如要更新庫存中的實體,請在 HTTP POST 要求中使用 update 端點。每個 POST 要求都必須包含 10000001 參數,以及包含您要更新實體的 JSON 酬載。
注意:請確認每日資料動態饋給也包含透過即時更新 API 提交的所有變更。否則您的資料可能已過時或已過時。
更新要求酬載
要求主體是包含記錄清單的 JSON 物件。每筆記錄都對應一個要更新的實體。其中包含 proto_record
欄位,以及指出實體更新時間的 generation_timestamp
:
{ "records": [ { "proto_record":"ServiceData PROTO", "generation_timestamp":"UPDATE_TIMESTAMP" } ] }
ServiceData PROTO
:您要更新的 ServiceData 實體的 proto 或 JSON 轉譯。UPDATE_TIMESTAMP
:請務必加入實體在後端系統中產生時間的時間戳記。如未加入這個欄位,則會設為 Google 收到要求的時間。透過batchPush
要求更新實體時,generation_timestamp
欄位會用於實體版本管理。請參閱關聯廣告空間結構定義中的時間值預期格式。
- 酬載內文大小不得超過 5 MB。
- 移除空白字元來縮減大小。
- 一個
batchPush
要求最多可有 1,000 項更新。
示例
更新預計到達時間
假設您急需將外送服務的預計送達時間從 30-60 分鐘更新為 60-90 分鐘。更新內容必須包含整個 Service 實體的 JSON。
假設有一個服務實體,如下所示:
{ "service": { "service_id": "service/entity002", "service_type": "DELIVERY", "parent_entity_id": "entity002", "lead_time": { "min_lead_time_duration": "600s", "max_lead_time_duration": "1800s" }, "action_link_id": "delivery_link/entity002" } }
HTTP POST 的即時更新如下 (要求內容經過輸出,以便使用者閱讀):
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "3600" }, "max_lead_time_duration" : { "seconds": "5400" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }] }
更新多個實體
如要在單一 API 呼叫中更新多個餐廳實體,請在要求主體的 proto_record 欄位中加入多筆記錄。
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "1800" }, "max_lead_time_duration" : { "seconds": "3600" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee", "fee_type" : "DELIVERY", "fixed_amount" : { "currency_code" : "USD", "units" : "10", "nanos" : "0" }, "service_ids": ["service/entity002"] } }, "generation_timestamp" : "2023-09-13T17:11:10.750Z" }] }
刪除實體
如要從清單刪除實體,請在 HTTP POST 要求中使用 DELETE 端點。每個 POST 要求都必須包含 PARTNER_ID 參數,以及內含要刪除實體 ID 的 JSON 酬載。
注意:請確認每日資料動態饋給也包含透過即時更新 API 提交的所有變更。否則每日批次擷取作業會覆寫即時變更。
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery" } }, "delete_time": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee" } }, "delete_time" : "2023-09-13T17:11:10.750Z" }] }
新增實體
請勿使用即時更新來新增實體,這可能會導致資料不一致。請改用批次動態饋給。
驗證與 API 回應代碼
即時更新 API 呼叫會執行兩種驗證類型:
- 要求層級 - 這些驗證會檢查酬載是否遵循結構定義,且每個
proto_record
都包含id
和type
欄位。這些檢查為同步性質,且會在 API 回應主體中傳回結果。回應代碼 200 和空白的 JSON 主體{}
代表已通過的驗證,且該要求中的實體已排入處理佇列。非 200 回應代碼表示一或多項驗證失敗,且整個要求都會遭到拒絕 (包括酬載中的所有實體)。例如,如果proto_record
缺少@type
,系統會傳回下列錯誤回應:
{ "error": { "code": 400, "message": "Record:{...}", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." } ] }
- 實體層級:酬載中的每個實體 (proto_record) 會根據結構定義進行驗證。這個驗證階段遇到的問題不會列在 API 回應中。這些回報只會記錄在 Actions Center 的「RTU 回報」資訊主頁中。
注意:200 回應代碼並不代表已成功擷取所有實體。
API 配額
即時 API 更新作業的配額為每 60 秒 1,500 個要求,或平均每秒 25 個要求。超過配額時,Google 會回應以下錯誤訊息:
{ "error": { "code": 429, "message": "Insufficient tokens for quota ...", "status": "RESOURCE_EXHAUSTED", "details": [...] } }
如要處理這個問題,請以指數增長的間隔重新重試呼叫,直到成功為止。如果您經常用盡配額,請考慮在同一個 API 要求中加入更多實體。一個 API 呼叫中最多可以加入 1,000 個實體。
處理時間即時更新
透過即時更新更新的實體,會在 5 分鐘內處理完畢。