關於 Cloud Storage 物件

本頁說明 Cloud Storage 中的資源「物件」。如要大致瞭解 Cloud Storage 的運作方式，請參閱 Cloud Storage 產品總覽。

物件

物件指的是您儲存在 Cloud Storage 中的個別資料片段。值區中可建立的物件數量沒有限制。

物件分為兩大部分：物件資料和物件中繼資料。物件資料基本上是您要儲存到 Cloud Storage 的檔案，且 Cloud Storage 完全不會解讀物件資料。物件中繼資料則有一系列的「名稱/值」組合，描述各項物件性質。

所有物件都有兩項重要的物件中繼資料，分別是物件的名稱和產生編號。將物件新增至 Cloud Storage 值區時，您會指定物件名稱，而 Cloud Storage 會指派產生號。名稱和產生編號會共同識別該值區中的物件。

您可以使用存取控制清單 (ACL) 控制個別物件的存取權。您也可以使用 Identity and Access Management (IAM)，控管值區或代管資料夾中所有物件的存取權。

命名注意事項

在 Cloud Storage 中命名物件時，請務必遵守特定規定，確保相容性並避免發生錯誤。這些規定適用於平面命名空間 bucket 和已啟用階層命名空間的 bucket。

一般規定

  • 物件名稱可包含按任何順序排列的有效 Unicode 字元。
  • 物件名稱不能含有回車或換行字元。
    • 請注意，透過 gcloud CLI 和 Google Cloud 控制台等介面傳送的反斜線，會在幕後逸出。舉例來說，\n 會變為 \\n。回車和換行限制嚴格來說是指 ANSI 逸出字元。
  • 物件名稱的開頭不得為 .well-known/acme-challenge/。
  • 物件不能命名為 . 或 ..。

命名空間專用物件大小限制

物件名稱大小上限會因值區的命名空間而異：

  • 扁平命名空間值區中的物件名稱大小：如果名稱採 UTF-8 編碼，則長度須為 1 到 1024 個位元組。

  • 已啟用階層式命名空間的值區中的物件名稱大小：物件名稱可分為兩部分：

    • 資料夾名稱：物件所在的資料夾名稱。 以 UTF-8 編碼時，資料夾名稱大小上限為 512 個位元組。
    • 基本名稱：資料夾中的物件名稱。以 UTF-8 編碼時，基本名稱大小上限為 512 個位元組。

    舉例來說，路徑 my-folder/my-object.txt 代表基本名稱為 my-object.txt 的物件，該物件儲存在名為 my-folder/ 的資料夾中。

建議

強烈建議您避免在物件名稱中使用下列項目：

  • XML 1.0 中無效的控制字元 (#x7F–#x84 及 #x86–#x9F)：這些字元會在您嘗試列出物件時造成 XML 清單問題。
  • # 字元：Google Cloud CLI 指令會將結尾為 #<數字字串> 的物件名稱解譯為版本 ID，因此在物件名稱中加入 #，會造成系統很難甚或無法使用 gcloud CLI 對這類已加上版本的物件執行作業。
  • [、]、* 或 ? 字元：Google Cloud CLI 指令會將這些字元解讀為萬用字元，因此在物件名稱中加入這些字元，可能會導致萬用字元作業難以執行或無法執行。 此外，* 和 ? 不是 Windows 檔案名稱的有效字元。
  • :、"、<、> 或 | 字元：這些字元不適用於 Windows 的檔案名稱，因此如果物件名稱包含這類字元，除非下載方法會重新命名產生的 Windows 檔案，否則無法將物件下載為 Windows 檔案。/ 字元在 Windows 中不是有效的檔案名稱字元，但通常可用於物件名稱，模擬目錄結構；下載至 Windows 環境時，Google Cloud CLI 等工具會自動將該字元轉換為 \。
  • 機密或個人識別資訊 (PII)：物件名稱的曝光範圍比物件資料更廣。舉例來說，物件名稱會出現在物件的網址中，以及列出值區中的物件時。

您無法直接重新命名現有物件，但可以間接重新命名物件，方法是複製並刪除原始物件。

物件命名空間

您可以在下列命名空間中儲存物件：

扁平命名空間

如果 bucket 設定為在扁平命名空間中儲存物件，系統一律會在 bucket 下方直接建立物件。在這種扁平命名空間的 bucket 中，bucket 內沒有階層，也沒有物件所在的目錄或資料夾。

為方便起見，扁平命名空間值區中的物件可透過多種方式視為儲存在資料夾階層中：

舉例來說，如果您在 your-bucket 值區中建立名為 folder1/file.txt 的物件，該物件的路徑為 your-bucket/folder1/file.txt，而 Cloud Storage 中沒有名為 folder1 的資料夾。從 Cloud Storage 的角度來看，字串 folder1/ 是物件名稱的一部分。

不過，由於物件名稱中含有 /，部分工具會實作資料夾的外觀。舉例來說，使用 Google Cloud 控制台時，您會folder1/file1.txt 像是瀏覽名為 folder1 的資料夾中名為 file1.txt 的物件。同樣地，您可以建立名為 folder1 的代管資料夾，然後 file1.txt 就會受到這個代管資料夾所設定的存取政策限制。

請注意，由於物件位於扁平命名空間，因此具有許多巢狀層級的目錄結構，無法呈現與原生檔案系統所列出的多層級巢狀子目錄一樣的效用。

如要瞭解如何避免在大量上傳時使用依序排列的名稱，進而提升效能，請參閱要求比率最佳做法。如果上傳的物件名稱是連續的，可能會使用相同的後端伺服器，進而限制效能。

模擬資料夾

為協助您整理 Cloud Storage 值區中的物件，部分工具會模擬資料夾，而 JSON 和 XML API 都有相關功能，可讓您設計自己的命名架構來模擬資料夾。按一下下列分頁，瞭解不同工具如何處理模擬資料夾。

控制台

Google Cloud 控制台會建立資料夾的視覺化表示法，類似於本機檔案瀏覽器。

在 Google Cloud 控制台中，您可以在值區中建立空資料夾，或上傳現有資料夾。

上傳現有資料夾時，資料夾名稱會成為資料夾中所有物件路徑的一部分。上傳內容也包含所有子資料夾和其中的物件。

如要建立資料夾，請按照以下步驟進行：

  1. 在 Google Cloud 控制台，前往「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 前往 bucket。

  3. 按一下「建立資料夾」即可建立空白新資料夾，按一下「上傳資料夾」則可上傳現有資料夾。

指令列

Cloud Storage CLI 會使用各種規則，模擬典型的指令列目錄體驗。

為營造階層式檔案樹的錯覺，gcloud CLI 會套用下列規則，判斷指令中的目的地網址應視為物件名稱或資料夾：

  1. 如果到達網頁網址以 / 字元結尾，gcloud CLI 指令會將到達網頁網址視為資料夾。舉例來說，請參考下列指令，其中的 your-file 是檔案名稱：

    gcloud storage cp your-file gs://your-bucket/abc/

    執行這項指令後，Cloud Storage 會在 your-bucket 值區中建立名為 abc/your-file 的物件。

  2. 如果您使用 --recursive 標記或 萬用字元 (例如 **)，將多個來源檔案複製到目的地網址，gcloud CLI 會將目的地網址視為資料夾。舉例來說，請參考下列指令，其中 top-dir 是包含 file1 和 file2 等檔案的資料夾：

    gcloud storage cp top-dir gs://your-bucket/abc --recursive

    執行這項指令後，Cloud Storage 會在 your-bucket 值區中建立 abc/top-dir/file1 和 abc/top-dir/file2 物件。

  3. 如果上述兩項規則都不適用，gcloud CLI 會檢查值區中的物件，判斷目的地網址是物件名稱還是資料夾。舉例來說，請參考下列指令，其中 your-file 是檔案名稱：

    gcloud storage cp your-file gs://your-bucket/abc

    gcloud CLI 會使用 / 分隔符和 prefix=abc，對 your-bucket 提出物件列出要求，判斷 your-bucket 中是否有路徑以 abc/ 開頭的物件。如果是，gcloud CLI 會將 abc/ 視為資料夾名稱，並在 your-bucket 值區中建立 abc/your-file 物件。否則，gcloud CLI 會在 your-bucket 中建立 abc 物件。

許多工具會建立 0 位元組的物件來標記資料夾是否存在，這種做法與這項以規則為基礎的方法不同。gcloud CLI 可辨識這類工具使用的多種慣例，例如在 0 位元組物件名稱結尾加上 _$folder$ 的慣例，但不需要這類標記物件實作與 UNIX 指令一致的命名行為。

除了這些規則之外，gcloud CLI 處理來源檔案的方式取決於您是否使用 --recursive 標記。如果您使用這個標記，gcloud CLI 會建構物件名稱，以鏡像來源目錄結構，從遞迴處理的點開始。舉例來說，請參考下列指令，其中 home/top-dir 是包含 file1 和 sub-dir/file2 等檔案的資料夾：

gcloud storage cp home/top-dir gs://your-bucket --recursive

執行這項指令後，Cloud Storage 會在 your-bucket 值區中建立 top-dir/file1 和 top-dir/sub-dir/file2 物件。

反之，如果複製時沒有 --recursive 旗標，即使因有 ** 等萬用字元而複製多個檔案，產生的物件也會以來源檔案的最終路徑元件命名。舉例來說，再次假設 home/top-dir 是包含 file1 和 sub-dir/file2 等檔案的資料夾，則指令：

gcloud storage cp home/top-dir/** gs://your-bucket

在 your-bucket 值區中建立名為 file1 的物件和名為 file2 的物件。

重試和命名

如果 gcloud CLI 重試遭中斷的要求，可能會發生問題，導致第一次嘗試複製部分檔案，後續嘗試時遇到已存在的目的地資料夾，進而導致物件命名錯誤。

舉例來說，假設下列指令的 your-dir/ 底下有 dir1 和 dir2 等子資料夾，且這兩個子資料夾都含有 abc 檔案：

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

如果路徑 gs://your-bucket/new 尚不存在，gcloud CLI 會在首次成功嘗試時建立下列物件：

new/dir1/abc
new/dir2/abc

不過，下次成功嘗試執行相同指令時，gcloud CLI 會建立下列物件：

new/your-dir/dir1/abc
new/your-dir/dir2/abc

如要確保 gcloud CLI 每次都能正常運作，請嘗試下列做法：

  1. 在到達網址結尾加上斜線，讓 gcloud CLI 一律將其視為資料夾。

  2. 使用gcloud storage rsync。由於 rsync 不會使用 Unix cp 定義的資料夾命名規則，因此無論目的地子資料夾是否存在，都能正常運作。

其他注意事項

  • 您無法使用 gcloud CLI 建立零位元組物件，模擬空白資料夾。

  • 下載至本機檔案系統時，gcloud CLI 會略過名稱結尾為 / 字元的物件，因為 Linux 和 macOS 不允許建立結尾為 / 的檔案。

  • 如果您使用指令碼合併子路徑來建構檔案路徑，請注意，由於 / 只是物件名稱中的一個字元，CLI 會將 gs://your-bucket/folder/ 解讀為與 gs://your-bucket/folder 不同的物件。

REST API

JSON API

JSON API 中沒有資料夾。您可以使用 prefix 和 delimiter 查詢參數，縮小列出的物件範圍，並模擬資料夾。

舉例來說，如要列出值區 my-bucket 中前置字串為 folder/subfolder/ 的所有物件，請使用下列網址提出物件清單要求：

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

XML API

XML API 中沒有資料夾。您可以透過 prefix 和 delimiter 查詢參數，縮減列出的物件範圍並模擬資料夾。

舉例來說，如要列出值區 my-bucket 中前置字串為 folder/subfolder/ 的所有物件，請使用下列網址提出物件清單要求：

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

移除模擬資料夾

由於模擬資料夾並非實際存在，因此通常只要重新命名物件，讓模擬資料夾不再是物件名稱的一部分，即可移除模擬資料夾。舉例來說，如果有名為 folder1/file 的物件，只要將物件重新命名為 file，即可移除模擬資料夾 folder1/。

不過，如果您使用會建立零位元組物件做為資料夾預留位置的工具 (例如 Google Cloud 控制台)，則必須刪除零位元組物件才能移除資料夾。

階層命名空間

階層式命名空間可讓您在 Cloud Storage 值區中，以檔案系統的階層結構 (例如資料夾) 整理物件。階層式命名空間可提升效能，並協助您有效管理資料。如要進一步瞭解階層式命名空間和使用時機，請參閱「階層式命名空間」。

物件不變原則

物件是不會變更的，也就是說，物件一經上傳，在整個儲存週期中即完全不會變更。物件儲存週期是指從成功建立物件 (例如上傳) 到成功刪除物件之間的時期。在具體做法上，這表示您無法對物件做出累進式的變更，例如附加或截斷作業。不過，儲存在 Cloud Storage 的物件是可以取代的，而且會以整體化的方式進行；也就是在新的上傳作業完成之前，會將舊版本的物件提供給讀取者，完成上傳作業後，則將新版本的物件提供給讀取者。單一取代作業的意義其實是一個不可變物件的生命週期結束，以及另一個不可變物件生命週期的開始。

每次取代物件資料時，物件的產生編號就會變更。因此，產生編號可做為不可變更物件的專屬 ID。

請注意，快速更換相同物件的頻率上限為每秒一次。如果更換同一個物件的頻率過高，可能會導致 429 Too Many Requests 錯誤。請將應用程式設計為每秒上傳特定物件的資料次數不得超過一次，並使用指數輪詢重試策略處理偶發的 429 Too Many Requests 錯誤。

後續步驟