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 參數，如下方螢幕截圖所示。
以 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 分鐘內處理完畢。