複合物件

建立

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

Compose 作業

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

執行組合時：

  • 來源物件不會受到影響。
  • 你可以使用 1 到 32 個來源物件。
  • 來源物件本身可以是複合物件。

組合產生的複合物件：

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

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

複合物件中繼資料

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

  • 複合物件沒有 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 附加至現有 Cloud Storage 物件的一系列指令如下：

$ echo 'new data' | gcloud storage cp - gs://bucket/temporary_object
$ gcloud storage objects compose gs://bucket/object_to_append gs://bucket/temporary_object \
    gs://bucket/object_to_append
$ gcloud storage rm gs://bucket/temporary_object

您也可以使用組合來支援物件編輯的基本自行設定。例如，您可以依據「{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"
        }
      }
    }
  }

重複的內容鍵

如果多個來源物件具有相同的內容鍵，Cloud Storage 最後處理的物件值會覆寫先前處理的任何物件值。

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

  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"
        }
      }
    }
  }

後續步驟