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 分鐘內處理完畢。