命名 Amazon S3 物件 - Amazon Simple Storage Service
選擇物件金鑰名稱物件金鑰命名準則物件索引鍵排序順序

命名 Amazon S3 物件

物件索引鍵 (或索引鍵名稱) 可在 Amazon S3 儲存貯體中找出獨一的物件。當您建立物件時，您可以指定金鑰名稱。例如，在 Amazon S3 主控台上，當您選取某個儲存貯體時，即會顯示該儲存貯體中的物件清單。這些名稱即為物件金鑰。

物件索引鍵名稱包含一系列以 UTF-8 編碼的 Unicode 字元，長度上限為 1,024 位元組，或大約 1,024 個拉丁字元。在某些地區設定中，單一字元可能需要 2 個位元組才能編碼。命名物件時，請注意下列事項：

  • 物件金鑰名稱區分大小寫。

  • 物件索引鍵名稱包含任何字首 (在主控台中，稱為資料夾)。例如，Development/Projects.xls 是位於 Development 字首 (或資料夾) 內 Projects.xls 物件的完整物件索引鍵名稱。字首、分隔符號 (/) 和物件名稱都包含在物件索引鍵名稱的 1,024 個位元組限制中。如需有關字首和資料夾的詳細資訊，請參閱 選擇物件金鑰名稱。

  • 某些字元在使用於物件索引鍵名稱時，可能需要特殊處理。如需更多詳細資訊，請參閱 物件金鑰命名準則。

注意

virtual-hosted-style requests 不支援值為 "soap" 的物件索引鍵名稱。對於使用 "soap" 的物件索引鍵名稱值，必須改用 path-style URL。

選擇物件金鑰名稱

Amazon S3 資料模型是單層式結構：您建立儲存貯體，儲存貯體存放物件。子儲存貯體或子資料夾沒有階層。但您可以仿照 Amazon S3 主控台的做法，使用金鑰名稱字首以及分隔符號來推斷邏輯階層。Amazon S3 主控台支援資料夾的概念。如需如何從 Amazon S3 主控台編輯中繼資料的詳細資訊，請參閱「在 Amazon S3 主控台中編輯物件中繼資料」。

假設您的儲存貯體 (admin-created) 具有四個物件，其物件金鑰如下：

Development/Projects.xls

Finance/statement1.pdf

Private/taxdocument.pdf

s3-dg.pdf

主控台會使用索引鍵名稱字首 (Development/、Finance/ 和 Private/) 以及分隔符號 (/) 呈現資料夾結構。s3-dg.pdf 索引鍵不包含以斜線分隔的字首，因此會直接在儲存貯體的根層級顯示其物件。如果開啟 Development/ 資料夾，會看到其中內含 Projects.xlsx 物件。

  • Amazon S3 支援儲存貯體與物件，且沒有任何階層。但在物件金鑰名稱中使用字首與分隔符號，能讓 Amazon S3 主控台及 AWS SDK 推斷階層，並引進資料夾的概念。

  • Amazon S3 主控台會透過資料夾前綴和分隔符號值作為金鑰建立零位元組物件，以實作資料夾物件的建立。這些資料夾物件不會出現在主控台中，但其他行為會與任何其他物件一樣，並且可以透過 REST API、AWS CLI 和 AWS SDK 來檢視和操作。

物件金鑰命名準則

您可以在物件索引鍵名稱中使用任何 UTF-8 字元。但是，在索引鍵名稱中使用特定字元可能對某些應用程式和通訊協定造成問題。下列準則可協助您提高與 DNS、網頁適用字元、XML 剖析器及其他 API 的合規。

安全字元

下列字元集通常可安心用於金鑰名稱中：

Alphanumeric characters

  • 0-9

  • a-z

  • A-Z
Special characters

  • 驚嘆號 (!)

  • 連字號 (-)

  • 底線 (_)

  • 句號 (.)

  • 星號 (*)

  • 單引號 (')

  • 左括號 (()

  • 右括號 ())

有效的物件索引鍵名稱範例如下：

  • 4my-organization

  • my.great_photos-2014/jan/myvacation.jpg

  • videos/2014/birthday/video1.wmv

注意

如果您使用 Amazon S3 主控台下載的物件中，其索引鍵名稱結尾為句號 (.)，則該句號會從所下載物件的索引鍵名稱中移除。若要保留所下載物件索引鍵名稱結尾的句號，您必須使用 AWS Command Line Interface (AWS CLI)、AWS SDK 或 Amazon S3 REST API。

此外，也請注意以下字首限制：

  • 必須使用 AWS CLI、AWS SDK 或 REST API 上傳或下載字首為 ./ 的物件。您可以使用 Amazon S3 主控台上傳這些物件。

  • 包含相對路徑元素 (例如，../) 的物件索引鍵在以下情況表示有效：如果從左到右進行剖析，相對路徑區段的累積計數永遠不會超過遇到的非相對路徑元素數目。此規則適用於使用 Amazon S3 主控台、Amazon S3 REST API、AWS CLI 和 AWS SDK 提出的所有請求。

    例如：

    • videos/2014/../../video1.wmv 有效。

    • videos/../../video1.wmv 無效。

    • videos/../../2014/video1.wmv 無效。

僅限句號的路徑區段

包含僅限句號的路徑區段 (. 或 ..) 的物件索引鍵，可能會在應用程式、SDK 或工具將它們解譯為相對路徑參考時，造成非預期的行為。

下列模式可能會導致產生問題：

  • folder/./file.txt - 包含目前的目錄參考

  • folder/../file.txt - 包含父目錄參考

  • ./file.txt - 從目前的目錄參考開始

  • ../file.txt - 從父目錄參考開始

下列模式正常運作：

  • folder/.hidden/file.txt - 句號檔案名稱的一部分，而非單獨存在

  • folder/..backup/file.txt - 句號是檔案名稱的一部分，而非單獨存在

當應用程式使用僅限句號區段處理物件索引鍵時，可能會發生下列行為影響：

  • 路徑標準化 - 許多系統會自動解析 . 和 .. 參考，可能會變更有效路徑 (例如，folder/./file.txt 變成 folder/file.txt)

  • 存取問題 - 由於路徑解析差異，應用程式可能無法找到物件

  • 不一致的行為 - 不同的工具和 SDK 可能會以不同的方式處理這些模式

重要

為了避免這些問題發生，建議避免在物件索引鍵名稱中使用僅限句號路徑區段。將替代命名慣例用於組織用途。

可能需要特殊處理的字元

索引鍵名稱中的下列字元可能需要額外的程式碼處理，且很有可能需要進行 URL 編碼，或以十六進位形式做為參考。這些字元的其中一部分是您的瀏覽器可能無法處理的不可列印字元，也需要特殊處理：

  • 和符號 (&)

  • 貨幣符號 ($)

  • ASCII 字元範圍：00 - 1F 十六進位 (0 - 31 十進位) 與 7F (127 十進位)

  • 小老鼠符號 (@)

  • 等號 (=)

  • 分號 (;)

  • 正斜線 (/)

  • 冒號 (:)

  • 加號 (+)

  • 空格 - 在某些情況下，可能會遺失大量連續空格 (特別是多個空格)

  • 逗號 (,)

  • 問號 (?)

需要避免的字元

建議您要在索引鍵名稱中使用下列字元，因為這些字元需要經過大量的特殊字元處理，才能在所有應用程式之間達到一致。

  • 反斜線 (\)

  • 左大括號 ({)

  • 無法列印的 ASCII 字元 (128 - 255 十進位字元)

  • 插入號 (^)

  • 右大括號 (})

  • 百分比字元 (%)

  • 重音符或抑音符或反引號 (`)

  • 右括號 (])

  • 引號 (")

  • 大於符號 (>)

  • 左括號 ([)

  • 波浪號 (~)

  • 小於符號 (<)

  • 井字號 (#)

  • 豎線或管道符號 (|)

根據行尾處理 XML 標準的規定，所有 XML 文字都會標準化，以便單一歸位字元 (ASCII 碼 13) 和後跟換行字元的歸位字元 (ASCII 碼 10)，即所謂的新行字元，由單一換行字元取代。為了確保在 XML 請求中正確剖析物件索引鍵，歸位字元和其他特殊字元插入 XML 標籤時，必須用其對等的 XML 實體程式碼取代。

以下是此類特殊字元及其對等 XML 實體程式碼的清單：

  • 撇號 (') 必須取代為 &apos;

  • 引號 (") 必須取代為 &quot;

  • 和號 (&) 必須取代為 &amp;

  • 小於符號 (<) 必須取代為 &lt;

  • 大於符號 (>) 必須取代為 &gt;

  • 歸位字元 (\r) 必須取代為 &#13; 或 &#x0D;

  • 新行字元 (\n) 必須取代為 &#10; 或 &#x0A;

下列範例說明了如何使用 XML 實體程式碼作為歸位字元的替代。此 DeleteObjects 請求刪除具有 key 參數 /some/prefix/objectwith\rcarriagereturn 的物件 (其中 \r 是歸位字元)。

<Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Object>
    <Key>/some/prefix/objectwith&#13;carriagereturn</Key>
  </Object>
</Delete>

物件索引鍵排序順序

Amazon S3 會依 UTF-8 編碼的位元組值對物件索引 (包括字首) 以詞典方式排序。

ASCII 字元依下列順序排序：

  • 特殊字元 (例如 !、/)

  • 大寫字母 (A–Z)

  • 小寫字母 (a–z)

非 ASCII 字元 (例如 é、中文) 編碼為多位元組 UTF-8 序列，通常在 ASCII 字元之後排序，因為其位元組值較高 (例如 0xC3 代表 é，0xE4 代表中)。

例如，apple/、Apple/、éclair/、中 文/ 等字首會排序為：

1. Apple/ (以 0x41 開頭)

2. apple/(以 0x61 開頭)

3. éclair/(以 0xC3 0xA9 開頭)

4. 中 文/(以 0xE4 0xB8 0xAD 0xE6 0x96 0x87 開頭)