Amazon S3 Compatibility API for Object StorageでのPOSTを使用したアップロード

HTMLフォームおよび事前署名済POSTポリシーを使用して、Amazon S3 Compatibility APIとともにHTTPS POSTを使用してオブジェクト・ストレージからオブジェクトをアップロードします。

オブジェクト・ストレージのHTMLフォームおよび署名済のPOSTポリシーを使用して、オブジェクトをブラウザから直接アップロードできます。この方法では、アップロード・パラメータを詳細に制御し、セキュリティ要件を適用し、サーバー側の暗号化やチェックサム検証などの主要な機能をサポートします。

このトピックでは、POSTベース・アップロードの必須要素、必要なポリシーと署名の作成方法、拡張ルールとカスタム・フィールドの指定方法について説明します。

ワークフローの設定

次のステップでは、ブラウザを使用してオブジェクトをオブジェクト・ストレージにアップロードするワークフローについて説明します。

HTMLページは、アプリケーションのWebサーバーからWebブラウザを使用してリクエストします。
返されるWebページには、オブジェクト・ストレージへのオブジェクト・アップロードに必要なパラメータを含むフォームが含まれます。
ファイルを選択し、ブラウザからフォームを送信して、オブジェクトをObject Storageに直接アップロードします。

これらのステップを実行するには、次の要素を設定する必要があります。

セキュリティ・ポリシー:許可されるバケット、オブジェクト・キー接頭辞、メタデータおよびその他の条件を定義します。
ポリシー署名:ポリシーを認証し、アップロードを承認します。
HTMLフォーム:ファイル選択用のフィールドが表示され、ポリシーと署名が非表示要素として含まれます。

セキュリティ・ポリシーおよびHTMLフォーム

ポリシー・ドキュメントは、送信時にアップロード・リクエストを検証するためにのみ使用される一時JSONオブジェクトです。このドキュメントはObject Storageに格納されず、APIコールを作成する必要はありません。サーバーは、HTMLフォームにポリシーを作成、署名および埋め込む必要があります。

HTMLフォームの作成に使用されるポリシーJSONの例を次に示します:

{ "expiration": "2025-12-30T12:00:00.000Z",
  "conditions": [
    {"bucket": "examplebucket"},
    ["starts-with", "$key", "user/user1/"],
    {"success_action_redirect": "http://some-website.com/successful_upload.html"},
    ["starts-with", "$Content-Type", "image/"],
    {"x-amz-meta-uuid": "14365123651274"},
    {"x-amz-server-side-encryption": "AES256"},
    ["starts-with", "$x-amz-meta-tag", ""],
 
    {"x-amz-credential": "AKIAIOSFODNN7EXAMPLE/20250428/us-east-1/s3/aws4_request"},
    {"x-amz-algorithm": "AWS4-HMAC-SHA256"},
    {"x-amz-date": "20250428T000000Z" }
  ]
}

結果のHTMLフォームは次のとおりです。

<html>
  <body>
  <form action="https://idic1l2s171r.compat.objectstorage.us-ashburn-1.oraclecloud.com/test-bucket" method="post" enctype="multipart/form-data">
    Key to upload:
    <input type="input"  name="key" value="user/user1/test-object-name" /><br />
    <input type="hidden" name="success_action_redirect" value="http://some-website.com/successful_upload.html" />
    Content-Type:
    <input type="input"  name="Content-Type" value="image/jpeg" /><br />
    <input type="hidden" name="x-amz-meta-uuid" value="14365123651274" /> 

         <input type="hidden" name="x-amz-meta-tag" value="simple-tag" />
    <input type="hidden" name="x-amz-server-side-encryption" value="AES256" />
    <input type="text"   name="X-Amz-Credential" value="AKIAIOSFODNN7EXAMPLE/20250428/us-east-1/s3/aws4_request" />
    <input type="text"   name="X-Amz-Algorithm" value="AWS4-HMAC-SHA256" />
    <input type="text"   name="X-Amz-Date" value="20250428T000000Z" />
 
    Tags for File:
    <input type="hidden" name="Policy" value='<Base64-encoded policy string>' />
    <input type="hidden" name="X-Amz-Signature" value="<signature-value>" />
    File:
    <input type="file"   name="file" /> <br />
    <input type="submit" name="submit" value="Upload" />
  </form>
</html>

ポリシー条件および照合ルール

POSTポリシーは、次の目的で使用されます。

認証署名を作成しています。
リクエストが満たす必要がある条件を指定します。

POSTポリシーには、expirationおよびconditions要素が含まれます。expiration要素は、POSTポリシーの失効日時をISO8601 UTC日付書式で指定します。各フォーム・フィールド(x-amz-signature、file、policyおよびx-ignore-で始まるフィールドを除く)には、ポリシーJSONに少なくとも1つの条件が必要です。このポリシーでは、フォーム・フィールドに複数の条件を指定することで、複雑なルールもサポートされます。

条件は、内部的に異なる照合タイプを持つことができます。たとえば、POSTアップロードを特定のバケットに制限するには、条件を{"bucket": "examplebucket"}として指定します。これは、オブジェクト・ストレージがURL内の受信バケット名とポリシーで指定された特定のバケットと一致することを示します。もう1つの一致タイプは、starts-withで、値がポリシーで指定した文字列で始まることを指定します。たとえば、オブジェクト名/キーを特定の接頭辞で開始する場合は、条件を["starts-with", "$key", "user/user1/"]と指定できます。ここで、$keyは、key HTMLフォーム・フィールドに指定された値を表します。

条件は、$keyに示すように変数をサポートします。$で始まる単語は、変数として扱われます。これらの変数は、POSTポリシーの検証前にHTMLフォーム・フィールドから受信する値に拡張されます。オブジェクト・ストレージで実行される検証のために、customfield01などのHTML形式のカスタム・フィールドおよび対応する$customfield01をポリシー条件に含めることができます。

次の表に、照合タイプの完全なリストを示します。

一致タイプ
一致タイプ	説明
範囲の指定	アップロードのファイル・サイズ制限など、最小値と最大値を定義します。たとえば、`["content-length-range", 2097152, 10485760]`は、2から10のMiBの間のコンテンツを許可します。
任意のコンテンツの照合	`starts-with`条件の空の文字列は、任意の値と一致します。たとえば、`["starts-with", "$success_action_redirect", ""]`です。
カンマ区切りリスト内のコンテンツ・タイプの照合	Content-Typeの`starts-with`の場合、カンマ区切りリストのすべての値が一致する必要があります。例: パス: `"image/jpg,image/png,image/gif"` `["starts-with", "$Content-Type", "image/"]` 失敗: `["image/jpg,text/plain"]`。その他のフィールドは単純な文字列として扱われます。
次で始まる	値は、指定された接頭辞で始まる必要があります。たとえば、`["starts-with", "$key", "u/u1/"]`は、オブジェクト・キーが`u/u1/`で始まる必要があることを意味します。
完全照合	フィールド値はポリシー値と正確に一致する必要があります。たとえば: `{"bucket": "prod-bucket-01"}`

bucket、content-length-range、REST固有のヘッダーなどのフォーム・フィールドには、条件に対する特別な処理があります。たとえば、bucketでは完全一致のみがサポートされ、starts-with操作はサポートされません。

次の表に、ポリシーで指定できる様々な要素に対する照合の処理を示します。

異なる要素の照合
エレメント- 名前	必須	説明
`success_action_status`	いいえ	アップロード成功後にクライアントに返されるステータス・コード(リダイレクトがない場合)。完全一致をサポートします。成功処理ステータス・コードがデフォルト(200)から上書きされる場合にのみ必要です。
`x-amz-date`	あり	署名計算のISO8601日付(20130728T000000Zなど)。完全一致をサポートします。
`x-amz-credential`	あり	署名計算に使用される資格証明文字列(アクセス・キーID、日付、リージョン、サービス)。完全一致をサポートします。
`x-amz-signature`	あり	ポリシーに基づいて計算された署名。これはフォーム・フィールドとしてのみ存在し、ポリシーの一部ではありません。
`success_action_redirect`	いいえ	アップロード成功後にクライアントをリダイレクトするURL。完全一致およびstart-withをサポートします。POSTアップロードが成功したときにサーバーがリダイレクトを行う必要がある場合にのみ必要です。
`Cache-Control / Content-Type / Content-Disposition / Content-Encoding / Expires`	いいえ	REST固有のヘッダー。完全一致およびstarts-withをサポートします。
`key`	あり	受け入れ可能なオブジェクト・キー名または接頭辞。完全一致およびstart-withをサポートします。
`bucket`	あり	使用可能なバケット名。完全一致をサポートします。
`content-length-range`	いいえ	アップロードされたコンテンツの最小サイズと最大サイズ。content-length-range一致をサポートします。オブジェクトを特定の範囲に制限する必要がある場合にのみ必要です。
`x-amz-meta-*`	いいえ	ユーザー定義メタデータ・フィールド。完全一致およびstarts-withをサポートします。これらはオプションのフィールドであり、オブジェクトのユーザー・メタデータとして格納されます。
`x-amz-storage-class`	いいえ	オブジェクトの格納に使用するストレージクラス。完全一致をサポートします。オプション。デフォルトは標準です。
`x-amz-algorithm`	あり	必要な署名アルゴリズム(AWS4-HMAC-SHA256など)を指定します。完全一致をサポートします。

$filenameという特別なフィールドは、ポリシー・ドキュメントで参照できます。この値は、ブラウザからアップロードされるファイルの名前に置き換えられます。HTMLフォームに存在する他のカスタム・フィールドについては、対応するエントリがポリシーJSONに存在します。カスタム・フィールドでは、exact matchesおよびstarts-with値がサポートされています。my-custom-fieldというカスタムフィールドの例を次の例に示します。

{ 
"expiration": "2025-04-30T12:00:00.000Z", 
"conditions": [ {"bucket": "your-bucket-name"}, 
                         ["starts-with", "$key", "uploads/"],
                         ["content-length-range", 0, 1048576], 
                         {"my-custom-field": "someValue"} ] 
}

ポリシーでの特殊文字処理

次の表に、POSTポリシードキュメントでエスケープされるはずの特殊文字を示します。

エスケープされる特殊文字
エスケープ・シーケンス	説明
`\n`	改行
`\uxxxx`	任意のUnicode文字を表します
`\f`	フォーム・フィード
`\v`	垂直タブ
`\r`	キャリッジ・リターン
`\b`	バックスペース
`\`	バックスラッシュ
`\t`	水平タブ
`$`	ドル記号

条件照合の要約

次のリストに、条件一致の概要を示します。

starts-withの値""は、何でも許可されることを示します。
条件のフィールドが$の前にある場合、条件評価の前にフィールドの値が置換されます。
$filenameは、すべてのフォーム・フィールドで認識される特別な変数です。これは、条件が評価される前に指定されたファイルの名前に置き換えられます。ファイル名のみが使用されます。ファイル名にc:\test-folder\test-file.txtや/usr/home/test/test-folder/test-file.txtなどのフルパスが含まれている場合、$filenameの値にはtest-file.txtのみが使用されます。filenameはfileフォーム・フィールドのヘッダーで、通常はブラウザによって自動的に追加されます。
content-lengthの検証では、使用可能な条件はexact-match、starts-with、content-match-in-list、any-matchおよびcontent-length-rangeです。
fileおよびbucketフィールドは特別な意味を持ちます。fileは、常にアップロードされているアタッチされたオブジェクトを参照します。バケット・フィールドは、オブジェクトのアップロード先のバケットを参照します。

署名計算

次のワークフローに従って署名を取得します。

ポリシーを記述し、UTF-8でエンコードします。
ポリシーのUTF-8バイトをbase64エンコード文字列に変換します。これはStringToSignになります。
署名鍵を生成します。
署名キーおよびHMAC-SHA256アルゴリズムを使用してStringToSignに署名します。

その他の機能ヘッダー

この項では、使用可能なその他の機能ヘッダーについて説明します。

追加のチェックサム・フォーム・フィールド

オブジェクトをアップロードするときに、オブジェクト・ストレージでこれらのチェックサムを計算するための追加のチェックサム・ヘッダーを指定できます。チェックサムは、データ整合性チェックにも使用できます。

次の表に、チェックサムでサポートされるヘッダーのリストを示します。

追加のチェックサム・フォーム・フィールド
名前	必須	説明
`x-amz-checksum-algorithm`	いいえ	値SHA256を指定できます。他の1つのチェックサムは、デフォルトであるMD5とともに計算されます。
`x-amz-checksum-sha256`	いいえ	オブジェクトのBase64エンコードされた256ビットSHA-256ダイジェスト。`x-amz-checksum-algorithm`がSHA256に設定されている場合は必須です。

SSE-Cフォーム・フィールド

顧客が独自の暗号化キーを管理する場合は、独自の暗号化キーを管理するときに、次の表にリストされている次のヘッダーをフォーム・フィールドに含めます。

SSE-Cフォーム・フィールド
名前	必須	説明
`x-amz-server-side-encryption-customer-algorithm`	いいえ	オブジェクトの暗号化に使用するアルゴリズムを指定します。サポートされる値はAES256のみです。
`x-amz-server-side-encryption-customer-key`	条件付き	Base64エンコードされた暗号化キー。
`x-amz-server-side-encryption-customer-key-MD5`	条件付き	RFC 1321に従って、暗号化キーのbase64エンコードの128ビットMD5ダイジェストを指定します。

POSTオブジェクト・リクエストへのレスポンス

putの終了後にHTTPステータス・コードのみが返されるPutObjectとは異なり、POSTオブジェクトの戻り値は、ポリシーに定義されている特定のフィールドによって異なります。

PostObjectでエラーが発生した場合は、正確なHTTPステータス・コード(429、500、503など)が返されます。
PostObjectが成功し、ポリシーにsuccess_action_redirectが指定されている場合は、success_action_redirectフィールドに指定されたURLへのリダイレクトが送信されます。
PostObjectが成功したが、success_action_redirectが指定されておらず、success_action_statusが定義されている場合は、 success_action_statusに定義されている正確なステータス・コードを返します。
success_action_redirectもsuccess_action_statusも定義されていない場合は、結果のステータス・コードが通常どおりになります。

Oracle Cloud Infrastructureドキュメント