使用 ETag 進行資料物件並行控制

Vector Search 2.0 支援使用 ETag (實體標記) 的樂觀並行控制 (OCC)，這類不透明的 ID 代表特定資料物件版本。

如果多個程序同時對同一個資料集執行作業 (例如即時 API 更新和大量匯入作業)，可能會互相覆寫變更內容 (最後寫入者勝出情境)。ETag 可確保資料完整性，並確保自您上次讀取記錄後，沒有其他程序修改該記錄。

ETag 的運作方式

  1. 讀取：當您建立或取得資料物件時，伺服器會傳回代表資料物件確切版本的 ETag 字串。

  2. 修改：在本機對資料物件進行變更。

  3. 寫入：您將 update 或 delete 要求傳回 Vector Search 2.0，包括您原先收到的 ETag。

  4. 驗證：伺服器會檢查提供的 ETag 是否與資料庫中儲存的目前 ETag 相符。

    • 如果相符，作業就會成功，且伺服器會傳回更新後資料物件的新 ETag。
    • 如果不相符，系統會封鎖作業，且伺服器會傳回 ABORTED 錯誤 (HTTP 409 Conflict)。

擷取 ETag

如要使用 ETag 進行並行控制，您必須先從系統擷取最新版本。

您可以透過下列方式擷取 ETag：

  • 即時 API 回應：在 DataObjectService 上呼叫讀取或寫入方法 (例如 GetDataObject、ListDataObjects、CreateDataObject 或 UpdateDataObject) 時，傳回的資料物件資源會包含目前的 ETag。

  • 匯入 API 輸出內容：呼叫 ImportDataObjects 時，您可以在 GcsImportConfig 欄位 output-uri 中，指定 Cloud Storage 的 URI 前置字元。如果匯入作業成功，系統會建立 JSONL 檔案，每行包含匯入資料物件的 ID 和 ETag。格式如下：

    { "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"}

  • Export API (ExportDataObjects)：從 Vector Search 2.0 匯出資料至 Cloud Storage 時，產生的標準 JSONL 資料檔案會包含所有匯出資料物件的 ETag。

建立資料物件

呼叫 CreateDataObject 或 BatchCreateDataObjects 時，系統會忽略您在要求中提供的任何 ETag，因為資料物件尚不存在。

如果建立要求成功，伺服器會在傳回的資料物件資源中加入新產生的 ETag。

更新資料物件

如要使用 UpdateDataObject 或 BatchUpdateDataObjects 安全地更新現有記錄，請在要求中的資料物件資源內直接加入 ETag。

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d",
  "data": {
    "genre": ["science-fiction", "thriller", "action"]
  }
}

刪除資料物件

由於 DeleteDataObject 和 BatchDeleteDataObjects 方法不會將完整的資料物件資源做為酬載，因此必須在 DeleteDataObjectRequest 中提供 ETag 做為頂層欄位。

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"
}

使用 ETag 進行大量擷取 (ImportDataObjects)

使用 ImportDataObjects API 時，系統會以非同步方式執行，因此可能會與即時更新發生衝突。在 JSONL 匯入檔案中加入 etag 欄位，在匯入期間強制執行並行控制。

向量搜尋會自動偵測每個記錄的衝突解決模式：

  • 使用 ETag (OCC)：如果提供 ETag，但與伺服器的目前版本不符，特定記錄將無法匯入。失敗記錄會寫入您指定的錯誤 URI，但匯入作業的其餘部分會繼續執行。

  • 沒有 ETag：如果省略 ETag，系統會擷取記錄並覆寫所有現有資料。如果不需要並行控制，這樣做可將輸送量最大化。

JSONL 格式

在匯入檔案的 JSON 物件根層級中加入 ETag，如下列範例所示。

{ "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d", "data":{ "genre": ["science-fiction", "thriller"] }, "vectors": { ... } }

處理並行錯誤

如果作業未通過 ETag 檢查，API 會傳回 ABORTED (HTTP 409 Conflict) 錯誤代碼。

建議的錯誤處理方式：

收到 ABORTED 錯誤時，應用程式應執行下列操作：

  1. 從伺服器重新擷取最新版本的資料物件。

  2. 解決新擷取資料與預期更新之間的所有業務邏輯衝突。

  3. 使用新的 ETag 重試作業。

後續步驟