オブジェクトキーに特殊文字を含むS3 URL

S3オブジェクトキーの特殊文字処理

S3オブジェクトキーは事実上任意のUTF-8文字を含むことができますが、これらのキーがURLに表示される場合、特定の文字はパーセントエンコーディングが必要です。エンコーディングの仕組みを理解することは、S3 URLを正しく構築・解析するために重要です。

URL例

https://media-bucket.s3.eu-west-1.amazonaws.com/uploads/2024/My%20Document%20%28final%29.pdf

解析されたコンポーネント

コンポーネント	値
バケット	media-bucket
キー	uploads/2024/My Document (final).pdf
リージョン	eu-west-1
スタイル	仮想ホスト形式

エンコーディングが必要な文字

文字	エンコード後	備考
スペース	%20	最も一般的なエンコーディング問題
(	%28	ファイル名の括弧
)	%29	ファイル名の括弧
+	%2B	スペースと混同されやすい
#	%23	フラグメント区切り文字
&	%26	クエリパラメータ区切り文字

安全な文字

以下の文字はS3キーでエンコーディング不要です：A-Z、a-z、0-9、/、-、_、.、~。

よくある落とし穴

1. プラス記号とスペース — クエリ文字列では+はスペースを意味しますが、URLのパス部分では+はリテラルのプラス記号です。S3はURL標準に従ってパスを処理するため、キーの+はリテラルです。
2. 二重エンコーディング — 既にエンコードされたキーを再度エンコードしないよう注意してください。例えば、My%20Fileを再度エンコードするとMy%2520Fileとなり、別のキーになります。
3. フォワードスラッシュ — キーの/文字はエンコードされません。S3の「フォルダ」階層を定義するためです（S3はフラットストレージですが）。