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)」)，然後按一下「啟用」
- 找出「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 主控台。
- 動作中心中的帳戶也與 Google Cloud 專案相關聯。如果尚未選取該專案，請選取該專案。
- 按一下左選單中的「服務帳戶」。
- 按一下「建立服務帳戶」。
- 輸入服務帳戶名稱，然後按一下「建立」。
- 在「請選擇角色」中，依序選擇「專案」>「編輯者」。
- 按一下「繼續」。
- 選用：新增使用者並授予服務帳戶存取權，然後按一下「完成」。
- 針對剛建立的服務帳戶，依序按一下「更多」>「建立金鑰」。
- 選取「JSON」做為格式，然後按一下「建立」。
- 產生新的公開/私密金鑰組後，請將其下載到您的機器。
使用 API
Real-time updates API 支援兩種作業：更新和刪除。不支援透過即時更新 API 新增實體。如果在單一 API 要求中加入多項更新，即時更新可批次處理。您可以在單一 API 呼叫中批次處理最多 1,000 個更新。建議您盡可能使用觸發事件為依據的方法，透過 RTU 傳送更新 (也就是在系統資料發生變更時，觸發對 Google 的即時更新)，而非依據頻率的方法 (也就是每隔 X 分鐘掃描系統是否有變更)。
即時更新 API 可在沙箱和正式環境中運作。沙箱環境可用於測試 API 要求，而正式環境則可用於更新 Ordering 端對端使用者可見的內容。
- 沙箱 -
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 參數，請前往「帳戶和使用者」頁面，在「行動中心」中查看，如以下螢幕截圖所示。
以上述螢幕截圖中 PARTNER_ID 的值 10000001 為例，在沙箱和正式版中傳送 API 要求的完整網址如下所示。
沙箱更新
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Sandbox DELETE
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 分鐘。更新內容必須包含整個服務實體的 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 分鐘內處理完畢。