複合物件

建立

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

撰寫作業

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

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

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

  • 您也可以在組合過程中，選擇永久刪除來源物件。 如果暫時性物件不需要虛刪除或物件版本管理功能保護，請使用這個選項，盡可能減少相關費用。
  • 您可以組合 1 到 32 個來源物件。
  • 來源物件本身可以是複合物件。

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

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

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

複合物件中繼資料

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

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

    • 您在撰寫要求中提供的任何 MD5 值都會遭到忽略。

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

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

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

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

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

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

附加並編輯

您可以使用 compose 作業附加及編輯物件。

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

舉例來說，在 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 會合併來源物件的所有內容，並附加至目的地物件。這項程序會處理不重複和重複的情境索引鍵，詳情請參閱以下各節。

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

不重複的脈絡資料鍵

如果來源物件具有不重複的情境金鑰，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"
        }
      }
    }
  }

後續步驟