HTML フォーム (AWS 署名バージョン 2)
Amazon S3 と通信する場合、通常は REST API または SOAP API を使用して、put、get、delete などのオペレーションを実行します。POST では、ユーザーはデータをブラウザから Amazon S3 に直接アップロードします。SOAP API の処理や REST の PUT リクエストの作成は行えません。
注記
SOAP のサポートは HTTP 経由では廃止されましたが、HTTPS 経由では引き続き利用可能です。Amazon S3 の新機能は SOAP でサポートされていません。SOAP の代わりに、REST API か AWS SDK を使用することをお勧めします。
ユーザーがブラウザを使用してコンテンツを Amazon S3 にアップロードできるようにするには、HTML フォームを使用します。HTML フォームは、フォーム宣言とフォームフィールドで構成されます。フォーム宣言には、リクエストの概要情報が含まれています。フォームフィールドには、リクエストの詳細情報と、リクエストを認証し、指定した条件をそのリクエストが確実に満たすようにするためのポリシーが含まれています。
注記
フォームデータと境界 (ファイルのコンテンツは除く) は 20 KB を超えることはできません。
このセクションでは、HTML フォームを使用する方法について説明します。
HTML フォームのエンコーディング
フォームとポリシーは UTF-8 エンコーディングされている必要があります。UTF-8 エンコードをフォームに適用するには、そのエンコードを HTML 見出しで指定するかリクエストヘッダーとして指定します。
注記
HTML フォーム宣言は、クエリ文字列認証パラメータを受け入れません。
HTML 見出しの UTF-8 エンコードの例を次に示します。
<html> <head> ... <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> ... </head> <body>
リクエストヘッダーの UTF-8 エンコードの例を次に示します。
Content-Type: text/html; charset=UTF-8
HTML フォーム宣言
フォーム宣言には、アクション、メソッド、エンクロージャタイプの 3 つのコンポーネントが含まれます。これらの値が適切に設定されていないと、リクエストは失敗します。
アクションは、リクエストを処理する URL を指定します。これはバケットの URL に設定されていなければなりません。例えば、バケットの名前が awsexamplebucket1 で、リージョンが米国西部 (北カリフォルニア) の場合、URL は https://awsexamplebucket1.s3.us-west-1.amazonaws.com/ になります。
注記
キー名はフォームフィールドで指定されます。
メソッドは POST である必要があります。
エンクロージャタイプ (enctype) を指定する必要があり、ファイルアップロードとテキストエリアアップロードの両方に対して、multipart/form-data が設定されていなければなりません。詳細については、RFC 1867
例
以下の例は、「awsexamplebucket1」バケットのフォーム宣言を示しています。
<form action="https://awsexamplebucket1.s3.us-west-1.amazonaws.com/" method="post" enctype="multipart/form-data">
HTML フォームフィールド
以下の表に、HTML フォーム内で使用できるフィールドを示します。
注記
変数 ${filename} は、ユーザーによって指定されたファイル名に自動的に置き換えられ、すべてのフォームフィールドで認識されます。ブラウザまたはクライアントがファイルへの完全または部分的なパスを提供した場合、最後のスラッシュ (/) またはバックスラッシュ (\) 以降のテキストのみが使用されます。たとえば、「C:\Program Files\directory1\file.txt」は「file.txt」と解釈されます。ファイルまたはファイル名が指定されていない場合、変数は空の文字列に置き換えられます。
| フィールド名 | 説明 | 必須 |
|---|---|---|
AWSAccessKeyId |
ポリシー内の一連の制約を満たすリクエストに対して匿名ユーザーアクセスを付与するバケット所有者の AWS アクセスキー ID。リクエストにポリシードキュメントが含まれる場合、このフィールドは必須です。 |
条件付き |
acl |
Amazon S3 のアクセスコントロールリスト (ACL)。無効なアクセスコントロールリストが指定されると、エラーが生成されます。ACL の詳細については、「アクセスコントロールリスト (ACL)」を参照してください。 型: 文字列 デフォルト: プライベート 有効な値: |
いいえ |
Cache-Control, Content-Type, Content-Disposition,
Content-Encoding, Expires |
REST 固有ヘッダー。詳細については、「Put Object」を参照してください。 |
いいえ |
key |
アップロードされたキーの名前。 ユーザーによって指定されたファイル名を使用するには、${filename} 変数を使用します。たとえば、Betty がファイル lolcatz.jpg をアップロードし、開発者が /user/betty/${filename} を指定すると、そのファイルは /user/betty/lolcatz.jpg として保存されます。 詳細については、「オブジェクトメタデータの使用」を参照してください。 |
はい |
policy |
リクエストで許可されているものについて説明するセキュリティポリシー。セキュリティポリシーがないリクエストは匿名と見なされ、誰でも書き込むことができるバケットでのみ動作します。 |
いいえ |
success_action_redirect, redirect |
アップロードが成功したときにクライアントがリダイレクトされる URL。Amazon S3 は、バケット、キー、ETag の値をクエリ文字列パラメータとして URL に追加します。 success_action_redirect が指定されていない場合、Amazon S3 は、success_action_status フィールドで指定されている空のドキュメントタイプを返します。 Amazon S3 が URL を解釈できない場合、 フィールドは無視されます。 アップロードが失敗した場合、Amazon S3 はエラーを表示し、ユーザーを URL にリダイレクトしません。 詳細については、「リダイレクト」を参照してください。 注記リダイレクトフィールド名は廃止されています。このフィールド名のサポートは削除される予定です。 |
いいえ |
success_action_status |
アップロードが正常に行われたとき、success_action_redirect が指定されていない場合にクライアントに返されるステータスコード。 有効な値は、200、201、または 204 (デフォルト) です。 値が 200 または 204 に設定されている場合、Amazon S3 は空のドキュメントとステータスコード 200 または 204 を返します。 値が 201 に設定されている場合、Amazon S3 は XML ドキュメントとステータスコード 201 を返します。XML ドキュメントの内容については、「POST Object」を参照してください。 値が設定されていないか無効な値が設定されている場合は、Amazon S3 は空のドキュメントとステータスコード 204 を返します。 注記Adobe Flash Player のバージョンによっては、本文が空の HTTP レスポンスが適切に処理されないことがあります。Adobe Flash でアップロードをサポートするには、 |
いいえ |
signature |
HMAC 署名は、提供された AWSAccessKeyId に対応するシークレットアクセスキーを使用して構築されます。このフィールドは、ポリシードキュメントがリクエストに含まれる場合に必要です。 詳細については、「Amazon S3 用 Identity and Access Management」を参照してください。 |
条件付き |
x-amz-security-token |
セッション認証情報で使用されるセキュリティトークン リクエストで Amazon DevPay を使用する場合は、製品トークン用とユーザートークン用の 2 つの リクエストでセッション認証情報が使用される場合は、単一の |
いいえ |
| プレフィックスが x-amz-meta- のその他のフィールド名 |
ユーザーが指定したメタデータ。 Amazon S3 では、このデータは検証または使用されません。 詳細については、「PutObject」を参照してください。 |
いいえ |
| file |
ファイルまたはテキストコンテンツ。 ファイルまたはコンテンツはフォームの最後のフィールドでなければなりません。その下のフィールドはすべて無視されます。 複数のファイルを一度にアップロードすることはできません。 |
はい |
ポリシーの作成
ポリシーは、UTF-8 および Base64 エンコードされた JSON ドキュメントで、リクエストが満たさなければならない条件を指定します。また、コンテンツを認証するときにも使用されます。ポリシードキュメントは、どのように設計するかに応じて、アップロードごと、ユーザーごと、すべてのアップロードに対して、またはニーズに応じたその他の設計にしたがって使用できます。
注記
ポリシードキュメントはオプションですが、バケットを誰でも書き込むことができるようにするよりも、ポリシードキュメントを使用することを強くお勧めします。
ポリシードキュメントの例を次に示します。
{ "expiration": "2007-12-01T12:00:00.000Z", "conditions": [ {"acl": "public-read" }, {"bucket": "awsexamplebucket1" }, ["starts-with", "$key", "user/eric/"], ] }
ポリシードキュメントには、有効期限と条件が含まれます。
有効期限
有効期限要素は、ポリシーの有効期限日を ISO 8601 UTC 日付形式で指定します。たとえば「2007-12-01T12:00:00.000Z」は、2007 年 12 月 1 日の 12:00 UTC にポリシーが無効になることを指定します。ポリシーには有効期限が必ず必要です。
条件
ポリシードキュメントの条件は、アップロードされたオブジェクトのコンテンツを検証します。条件の一覧には、フォームで指定した各フォームフィールドが含まれていなければなりません (AWSAccessKeyId、署名、ポリシー、および x-ignore- プレフィックスが付いているフィールド名を除く)。
注記
同じ名前のフィールドが複数ある場合、そのフィールドの値はコンマで区切る必要があります。たとえば、「x-amz-meta-tag」という名前のフィールドが 2 つあり、最初のフィールドの値が「Ninja」、2 つ目のフィールドの値が「Stallman」の場合、ポリシードキュメントは Ninja,Stallman に設定します。
フォーム内のすべての変数は、ポリシーの検証前に展開されます。したがって、条件との照合は必ず、展開されたフィールドに対して行われます。たとえば、キーフィールドを user/betty/${filename} に設定した場合、ポリシーは [
"starts-with", "$key", "user/betty/" ] になる可能性があります。[
"starts-with", "$key", "user/betty/${filename}" ] は入力しないでください。詳細については、「条件一致」を参照してください。
以下の表にポリシードキュメント条件を示します。
| 要素名 | 説明 |
|---|---|
| acl |
ACL が満たす必要がある条件を指定します。 完全一致および |
| content-length-range |
アップロードされたコンテンツの最小サイズと最大サイズを指定します。 範囲一致をサポートします。 |
| Cache-Control、Content-Type、Content-Disposition、Content-Encoding、Expires |
REST 固有ヘッダー。 完全一致および |
| key |
アップロードされたキーの名前。 完全一致および |
| success_action_redirect、redirect |
アップロードが成功したときにクライアントがリダイレクトされる URL。 完全一致および |
| success_action_status |
アップロードが正常に行われたとき、success_action_redirect が指定されていない場合にクライアントに返されるステータスコード。 完全一致をサポートします。 |
| x-amz-security-token |
Amazon DevPay のセキュリティトークン。 Amazon DevPay を使用する各リクエストでは、製品トークン用とユーザートークン用の 2 つの |
| プレフィックスが x-amz-meta- のその他のフィールド名 |
ユーザーが指定したメタデータ。 完全一致および |
注記
ツールキットにより追加のフィールドが追加されている場合は (Flash では filename が追加される)、そのフィールドをポリシードキュメントに追加する必要があります。この機能を管理できる場合は、そのフィールドの機能が Amazon S3 に無視されるようにプレフィックスの x-ignore- をフィールドに追加します。これは、そのフィールドの機能の将来のバージョンには影響しません。
条件一致
以下の表に、条件一致タイプを示します。フォーム内で指定したフォームフィールドごとに 1 つの条件を指定する必要がありますが、1 つのフォームフィールドに複数の条件を指定し、より複雑な一致条件を作成することもできます。
| 条件 | 説明 |
|---|---|
|
完全一致 |
完全一致では、フィールドが特定の値と一致するかどうかを確認します。この例は、ACL が public-read に設定される必要があることを示しています:
この例は、ACL が public-read に設定される必要があることを別の方法で示しています:
|
|
先頭が一致 |
先頭の値を指定する場合は、starts-with を使用します。次の例は、キーが user/betty で開始する必要があることを示しています。
|
|
任意のコンテンツに一致 |
フィールド内の任意のコンテンツを許可するようにポリシーを設定するには、starts-with に空の値を使用します。次の例は、任意の success_action_redirect を許可します。
|
|
範囲を指定 |
範囲指定できるフィールドについては、範囲の上限値と下限値をコンマで区切ります。次の例は、1～10 メガバイトのサイズのファイルを許可します。
|
文字のエスケープ
以下の表に、ポリシードキュメント内でエスケープする必要のある文字を示します。
| エスケープシーケンス | 説明 |
|---|---|
|
\\ |
バックスラッシュ |
|
\$ |
ドル記号 |
|
\b |
Backspace |
|
\f |
フォームフィード |
|
\n |
改行 |
|
\r |
キャリッジリターン |
|
\t |
水平タブ |
|
\v |
垂直タブ |
|
\u |
すべての Unicode 文字 |
署名の作成
| ステップ | 説明 |
|---|---|
| 1 |
UTF-8 を使用してポリシーをエンコードします。 |
| 2 |
Base64 を使用して、それらの UTF-8 バイトをエンコードします。 |
| 3 |
HMAC SHA-1 を使用して、シークレットアクセスキーでポリシーに署名します。 |
| 4 |
Base64 を使用して、SHA-1 署名をエンコードします。 |
認証の一般的な情報については、「Amazon S3 用 Identity and Access Management」を参照してください。
リダイレクト
このセクションでは、リダイレクトを処理する方法について説明します。
一般的なリダイレクト
POST リクエストの完了時に、ユーザーは、フィールドで指定した場所にリダイレクトされます。success_action_redirectAmazon S3 が URL を解釈できない場合、success_action_redirect フィールドは無視されます。
success_action_redirect が指定されていない場合、Amazon S3 は success_action_status フィールドで指定されている空のドキュメントタイプを返します。
POST リクエストが失敗した場合、Amazon S3 はエラーを表示し、リダイレクトを行いません。
アップロード前のリダイレクト
<CreateBucketConfiguration> を使用してバケットが作成された場合、エンドユーザーをリダイレクトしなければならない可能性があります。これが発生した場合、ブラウザによっては、リダイレクトが正しく処理されないことがあります。比較的まれにですが、バケットの作成直後に発生する可能性があります。
