複合物件

建立

本頁面說明複合物件，這類物件是從現有物件建立，不需要轉移額外的物件資料。複合物件可用於附加至現有物件，以及重新建立以多個元件平行上傳的物件。

Compose 作業

組合作業會串連指定順序的來源物件資料，建立名為「複合物件」的新物件。來源物件必須符合下列規定：

  • 所有來源物件都必須擁有相同的儲存空間級別。
  • 所有來源物件都必須儲存在同一個 Cloud Storage bucket 中。

執行組合時，請注意下列事項：

  • 您也可以在組合程序中選擇強制刪除來源物件。 使用這個選項，盡量減少不需要虛刪除或物件版本管理功能保護的暫時性物件費用。
  • 最多可組合 1 到 32 個來源物件。
  • 來源物件本身可以是複合物件。

組合產生的複合物件具有下列特徵：

  • 複合物件的儲存空間級別與來源物件相同。
  • 如果來源物件隨後遭到取代或刪除，複合物件不會變更。

使用 gcloud storage 執行物件組合時，產生的物件會將 Content-Type 設為與第一個來源物件的 Content-Type 相符。

複合物件中繼資料

複合物件的中繼資料與其他物件的中繼資料有幾項差異：

  • 複合物件沒有 MD5 雜湊中繼資料欄位。

    • 系統會忽略您在撰寫要求中提供的任何 MD5 值。

  • 複合物件的 ETag 值並非以 MD5 雜湊為依據，用戶端程式碼不應對複合物件 ETag 有任何假設，除非基礎物件依據 HTTP/1.1 的 IETF 規格變更時 Etag 也會變更。

  • 每個複合物件都有「元件計數」中繼資料欄位，用於計算複合物件內含的非複合物件數。

    • 如果將複合物件重新寫入其他位置或儲存空間類別，結果會是元件計數為 1 的複合物件。

對複合物件執行完整性檢查

Cloud Storage 使用 CRC32C 對上傳時的每一個來源物件執行完整性檢查，並允許叫用者在產生的複合物件下載時進行完整性檢查。CRC32C 是一種錯誤偵測碼，可以依據其元件的 CRC32C 值有效計算。您的應用程式應依照下列指示使用 CRC32C：

  • 上傳來源物件時，您應使用 CRC32C 程式庫 (例如物件中繼資料頁面列出的其中一項) 計算每個物件的 CRC32C，並在要求中納入該值。Cloud Storage 會根據您提供的值驗證每次上傳。
  • 組合作業會自動檢查來源物件是否正確組裝，並忽略您在組合要求中提供的任何 CRC32C 值。系統會在回應中傳回產生的複合物件 CRC32C。
  • 如果應用程式可以在上傳和組合物件兩項作業之間變更來源物件，您應指定來源物件的產生版本專用名稱，以避免發生競爭狀況。或者，您也可以依據預期來源物件的 CRC32C 值建構 CRC32C 值，並與組合作業傳回的 CRC32C 值進行比較。
  • 下載時，您應計算下載物件的 CRC32C，並與回應所含的值進行比較。

附加並編輯

您可以使用組合作業來附加及編輯物件。

如要將資料附加至現有物件，請先建立臨時物件，其中包含要附加的資料。接著，您會將現有物件與暫時物件組合。在組合過程中，您可以刪除臨時物件和原始物件的舊版。您也可以將產生的物件命名為與原始物件相同的名稱。

舉例來說，在 gcloud CLI 中，下列指令會將 new data 字串附加至現有物件：

$ echo 'new data' | gcloud storage cp - gs://bucket/temporary_object
$ gcloud storage objects compose gs://bucket/existing_object gs://bucket/temporary_object \
    gs://bucket/existing_object --delete-source-objects

您也可以使用組合來支援物件編輯的基本自行設定。例如，您可以依據「{Y1, Y2, Y3}」的順序組合物件「X」，取代「Y2」的內容，然後依據這些相同元件重新組合「X」。請注意，這需要「Y1」、「Y2」和「Y3」維持未刪除狀態，所以系統會向您收取這些元件及複合物件的費用。

複合物件脈絡

使用組合作業時，Cloud Storage 會合併來源物件的所有內容，並附加至目的地物件。這個程序會處理不重複和重複的內容鍵，詳情請參閱下列章節。

這是預設的合併行為。如果您未在組合要求中指定目的地物件的環境，就會發生這種情況。您可以在撰寫作業期間清除內容，或為目的地物件指定新內容，藉此覆寫這項預設行為。

不重複的脈絡資料鍵

如果來源物件具有不重複的內容鍵，Cloud Storage 會直接將這些鍵及其對應值附加至目的地物件。

請見如下範例：

來源物件 A 的內容：Department: Engineering, Status: Active

來源物件 B 脈絡：Owner: m_jones, Version: 1.1

組合作業完成後，目的地物件會包含下列合併的內容：

  {
    "contexts": {
      "custom": {
        "Department": {
          "value": "Engineering",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        },
        "Status": {
          "value": "Active",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        },
        "Owner": {
          "value": "m_jones",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        },
        "Version": {
          "value": "1.1",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        }
      }
    }
  }

重複的脈絡資料鍵

如果多個來源物件具有相同的內容鍵，系統會使用組合清單中最後一個包含該鍵的來源物件值，做為組合物件的值。

舉例來說，假設來源物件的處理順序如下：

  1. 來源物件 A

  2. 來源物件 B

來源物件 A 的內容：Version: 1.0, ReleaseDate: 2024-01-15

來源物件 B 脈絡：Version: 1.1, Owner: m_jones

兩個來源物件都有 Version 鍵，但物件 A 有 Version: 1.0，物件 B 則有 Version: 1.1。由於 Cloud Storage 會在來源物件 A 之後處理來源物件 B，因此來源物件 B 的 Version 值會優先處理，最終值為 1.1。

目的地物件會合併這些環境，如下所示：

  {
    "contexts": {
      "custom": {
        "Version": {
          "value": "1.1",
          "createTime": "2025-01-01T00:00:00.000Z",
          "updateTime": "2025-01-01T00:00:00.000Z"
        },
        "ReleaseDate": {
          "value": "2024-01-15",
          "createTime": "2025-01-01T00:00:00.000Z",
          "updateTime": "2025-01-01T00:00:00.000Z"
        },
        "Owner": {
          "value": "m_jones",
          "createTime": "2025-01-01T00:00:00.000Z",
          "updateTime": "2025-01-01T00:00:00.000Z"
        }
      }
    }
  }

後續步驟