RTU 主要用於呈現無法預見的更新內容,例如緊急關閉或會定期變更的中繼資料 (例如預計到達時間)。如果不需要立即反映變更,可以改用批次動態饋給擷取功能。即時更新作業在五分鐘內即可完成。
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)」),然後按一下「啟用」
- 找到 Production 執行個體 (「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 專案。如果尚未選取該專案,請加以選取。
- 按一下左選單中的「服務帳戶」。
- 按一下「建立服務帳戶」。
- 輸入服務帳戶的名稱,然後按一下「建立」。
- 在請選取角色,選擇專案>編輯器。
- 按一下「Continue」(繼續)。
- 選用:新增使用者可授予服務帳戶存取權,然後按一下「完成」。
- 按一下「更多」圖示 >為剛建立的服務帳戶建立金鑰。
- 選取「JSON」JSON格式,然後按一下「建立」JSON。
- 新的公開/私密金鑰組產生後,請將其下載到您的電腦。
使用 API
Real-time Updates API 支援兩種作業類型:更新和刪除。不支援透過即時更新 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 參數,如下方螢幕截圖所示。
以上方螢幕截圖為例,以 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 參數和 JSON 酬載,其中含有您要刪除的實體 ID。
注意:請確認每日資料動態饋給也包含透過即時更新 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 分鐘內處理完畢。