Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

即時更新

RTU 主要用於你無法預測的更新，例如緊急關閉，或是定期變更的中繼資料 (例如預計抵達時間)。如果不需要立即反映變更，可以改用批次動態饋給擷取。系統會在五分鐘內處理即時更新。

Google Cloud Platform 設定

設定 GCP 專案。您需要 GCP 專案才能存取 RTU API。
- 授予 food-support@google.com 編輯者存取權
- 將 GCP 專案編號告知 Google POC。GCP 專案必須與你的 Actions Center 帳戶建立關聯，才能即時更新。
- 啟用 Maps Booking API：
  - 在 GCP 中，依序前往「APIs & Services」(API 和服務) >「Library」(程式庫)。
  - 搜尋「Google Maps Booking API」。
  - 找到沙箱例項 (「Google Maps Booking API (開發人員)」)，然後按一下「啟用」
  - 找到「Google Maps Booking API」的「正式版」執行個體，然後按一下「啟用」
  - 在 GCP 專案中建立具有編輯者角色的服務帳戶。詳情請參閱「設定服務帳戶」。
  - 請務必將批次動態饋給上傳至您處理即時更新的環境。
  - 建議您以所選語言安裝 Google 用戶端程式庫，進行 API 驗證。使用「https://www.googleapis.com/auth/mapsbooking」做為 OAuth 範圍。下方的程式碼範例會使用這些程式庫。否則，您必須按照「使用 OAuth 2.0 存取 Google API」一文所述，手動處理權杖交換作業。

服務帳戶設定

您需要服務帳戶，才能向 Google API (例如即時更新 API) 發出經過驗證的 HTTPS 要求。

如要設定服務帳戶，請按照下列步驟操作：

存取 Google Cloud Platform 控制台。
動作中心的帳戶也與 Google Cloud 專案相關聯。如果尚未選取該專案，請選取。
按一下左選單中的「服務帳戶」。
按一下「建立服務帳戶」。
輸入服務帳戶名稱，然後按一下「建立」。
在「請選擇角色」部分，依序選取「專案」>「編輯者」。
點按「Continue」(繼續)。
選用：新增使用者，授予他們服務帳戶存取權，然後按一下「完成」。
按一下剛建立的服務帳戶的「更多」>「建立金鑰」。
選取「JSON」做為格式，然後按一下「建立」。
產生新的公開/私密金鑰組後，請下載至您的電腦。

使用 API

即時更新 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

如以下螢幕截圖所示，您可以在 Actions Center 的「帳戶和使用者」頁面中找到 PARTNER_ID 參數。

以上方螢幕截圖中的 PARTNER_ID 值 10000001 為例，在沙箱和正式環境中傳送 API 要求的完整網址如下所示：

沙箱更新

https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

沙箱 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

Production DELETE

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 回應不會回報驗證階段遇到的問題。只會在「動作中心」的 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 分鐘內處理完畢。

轉換追蹤

即時更新 透過集合功能整理內容 你可以依據偏好儲存及分類內容。