HTMLフォームを使用してオブジェクトをバケットにアップロードします。
使用上の注意
HTMLフォームを使用してオブジェクトをバケットにアップロードするには、
oss:PutObject
権限が必要です。 詳細については、「RAMユーザーへのカスタムポリシーのアタッチ」をご参照ください。PostObject操作を呼び出してアップロードするオブジェクトのサイズは、5 GBを超えることはできません。
バケットへのPostObjectリクエストを開始するには、バケットに対する書き込み権限が必要です。 PostObjectリクエストを開始するバケットのアクセス制御リスト (ACL) がpublic-read-writeの場合、PostObjectリクエストに署名する必要はありません。 それ以外の場合、Object Storage Service (OSS) はリクエスト内の署名情報を検証します。
PutObject操作とは異なり、PostObject操作はAccessKeyシークレットを使用してポリシーフォームフィールドの署名を計算します。 計算された署名文字列は、署名フォームフィールドの値として使用されます。 OSSはこの値をチェックして、署名の有効性を検証します。
送信されたフォームのURLは、バケットのドメイン名です。 URLでバケットにアップロードするオブジェクトを指定する必要はありません。 リクエスト行の形式は、
POST /ObjectName HTTP/1.1
ではなくPOST / HTTP/1.1
です。OSSは、PostObjectリクエストのヘッダーまたはURLの署名情報をチェックしません。
バージョン管理
バージョン管理が有効なバケットに対してPostObjectリクエストを開始すると、アップロードされたオブジェクトに対して一意のバージョンIDが生成され、レスポンスのx-OSS-version-IDヘッダーの値としてバージョンidが返されます。
バージョン管理が一時停止されたバケットに対してPostObjectリクエストを開始すると、OSSはアップロードされたオブジェクトのバージョンID nullを生成し、レスポンスのx-oss-version-IDヘッダーの値としてバージョンidを返します。 バージョン管理が一時停止されたバケット内のオブジェクトは、IDがnullの複数のバージョンを持つことはできません。
リクエスト構文
POST / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
User-Agent: browser_data
Content-Length: ContentLength
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
key
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
attachment;filename=oss_download.jpg
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
myuuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
mytag
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
access-key-id
--9431149156168
Content-Disposition: form-data; name="policy"
encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"
signature
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg
file_content
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--
リクエストヘッダー
PostObjectリクエストの本文は、multipart/form-data形式でエンコードされます。 PostObject操作では、パラメーターはフォームフィールドとしてリクエスト本文に渡されますが、パラメーターはHTTPリクエストヘッダーとしてPutObject操作で渡されます。
PostObject操作中にx-oss-taggingリクエストヘッダーを渡してオブジェクトにタグを追加することはできません。 PostObject操作の完了後、PutObjectTagging操作を呼び出してオブジェクトにタグを追加できます。
ヘッダー | タイプ | 必須 | 説明 |
コンテンツタイプ | String | 任意 | アップロードするオブジェクトのタイプと、webページのエンコード形式。 ブラウザは、ヘッダーの値に基づいてオブジェクトの読み取り方法とエンコード方法を決定します。 PostObject操作で送信されるフォームは、 この形式では、境界はフォームによってランダムに生成される境界文字列です。 境界文字列を指定する必要はありません。 OSS SDKを使用してフォームを作成する場合、SDKはランダムな境界文字列も生成します。 |
PostObjectリクエストの一般的なリクエストヘッダー (ホストや日付など) の詳細については、「一般的なリクエストヘッダー」をご参照ください。
フォーム要素
次の表に、PostObjectリクエストのV1シグネチャとV4シグネチャの両方の一般的なフォーム要素を示します。 PostObjectリクエストのV4署名の一意のフォーム要素の詳細については、「フォーム」をご参照ください。 PostObjectリクエストのV1署名の一意のフォーム要素の詳細については、「フォーム」をご参照ください。
最後のフォームフィールドはファイルでなければなりません。 他のフォームフィールドに特別な注文は必要ありません。
フォームフィールドのキーは8 KBを超えることはできません。また、フォームフィールドの値は2 MBを超えることはできません。
要素 | タイプ | 必須 | 説明 |
キャッシュ制御 | String | 任意 | オブジェクトがダウンロードされたときのwebページのキャッシュ動作。 詳細については、「RFC 2616」をご参照ください。 デフォルトでは、この要素は空のままです。 |
コンテンツ処理 | String | 任意 | オブジェクトがダウンロードされたときのオブジェクトの名前。 詳細については、「RFC 2616」をご参照ください。 デフォルトでは、この要素は空のままです。 |
コンテンツエンコーディング | String | 任意 | オブジェクトがダウンロードされたときのオブジェクトのコンテンツエンコード形式。 詳細については、「RFC 2616」をご参照ください。 デフォルトでは、この要素は空のままです。 |
有効期限 | String | 任意 | キャッシュされたデータの有効期限。 詳細については、「RFC 2616」をご参照ください。 デフォルトでは、この要素は空のままです。 |
policy | String | 条件付き | リクエスト内のフォームフィールドの有効性。 ポリシーフォームフィールドを含まないリクエストは、匿名のリクエストと見なされ、ACLがパブリック読み書きであるバケットにのみアクセスできます。 デフォルトでは、この要素は空のままです。 条件: このフォームフィールドは、バケットACLがpublic-read-writeでない場合、またはOSSAccessKeyIdまたはSignatureフォームフィールドがリクエストで指定されている場合に必要です。 重要 フォームとポリシーフォームフィールドをUTF-8-encodedする必要があります。 ポリシーフォームフィールドもBase64-encodedする必要があります。 |
x-oss-server-side-encryption-key-id | String | 任意 | key Management Service (KMS) によって管理されるカスタマーマスターキー (CMK) のID。 この要素は、x-oss-server-side-encryption要素がKMSに設定されている場合にのみ設定できます。 |
x-oss-content-type | String | 任意 | x-oss-content-typeフォームフィールドをPostObjectリクエストの本文に追加して、アップロードするオブジェクトのコンテンツタイプを指定できます。 x-oss-content-typeフォームフィールドで指定されたコンテンツタイプは、ブラウザーによって自動的に生成されるファイルフォームフィールドで指定されたコンテンツタイプよりも優先されます。 コンテンツタイプの優先順位は、x-oss-content-typeフォームフィールド> ブラウザによって自動的に生成されるファイルフォームフィールドで指定されたcontent-Typeの順です。 デフォルトでは、この要素は空のままです。 |
x-oss-forbid-overwrite | String | 任意 | PostObject操作で、同じ名前の既存のオブジェクトを上書きするかどうかを指定します。 オブジェクトをアップロードするバケットのバージョン管理が有効または一時停止されている場合、x-oss-forbid-overwriteは有効になりません。 この場合、PostObject操作を呼び出してアップロードされたオブジェクトは、同じ名前の既存のオブジェクトを上書きします。
x-oss-forbid-overwriteを指定すると、OSSの1秒あたりのクエリ (QPS) パフォーマンスが低下する可能性があります。 x-oss-forbid-overwriteを使用して多数の操作 (QPSが1,000を超える) を実行する場合は、テクニカルサポートにお問い合わせください。 |
x-oss-object-acl | String | 任意 | アップロードするオブジェクトのACL。 フォームフィールドでアップロードするオブジェクトのACLを指定できます。 有効な値:
詳細については、「オブジェクトACL」をご参照ください。 |
x-oss-storage-class | String | 任意 | オブジェクトのストレージクラス。 オブジェクトをアップロードするときにx-oss-storage-classヘッダーを指定した場合、オブジェクトがアップロードされるバケットのストレージクラスに関係なく、アップロードされたオブジェクトのストレージクラスは指定された値になります。 たとえば、低頻度アクセス (IA) バケットにオブジェクトをアップロードするときにx-oss-storage-classヘッダーを標準に設定すると、オブジェクトは標準オブジェクトとして保存されます。 有効な値:
詳細については、「概要」をご参照ください。 |
キー | String | 必須 | アップロードするオブジェクトの名前。 オブジェクト名をエンコードする必要はありません。 オブジェクト名に デフォルトでは、この要素は空のままです。 |
success_action_redirect | String | 任意 | オブジェクトのアップロード後にクライアントがリダイレクトされるURL。 このフォームフィールドが指定されていない場合、返される結果はsuccess_action_statusフォームフィールドによって指定されます。 アップロードが失敗した場合、OSSはエラーコードを返し、クライアントはURLにリダイレクトされません。 デフォルトでは、この要素は空のままです。 |
success_action_status | String | 任意 | success_action_redirectフォームフィールドが指定されておらず、オブジェクトがアップロードされた場合にクライアントに返されるHTTPステータスコード。 有効な値: 200、201、204 (デフォルト) 。
|
x-oss-meta-* | String | 任意 | オブジェクトのユーザーメタデータ。 デフォルトでは、この要素は空のままです。 リクエストにx-oss-meta-プレフィックスを含む名前のフォームフィールドが含まれている場合、そのフォームフィールドはオブジェクトのユーザーメタデータと見なされます。 例: 説明 オブジェクトは、名前にx-oss-meta-プレフィックスを含む複数のフォームフィールドを持つことができます。 ただし、オブジェクトのすべてのユーザーメタデータの合計サイズは8 KBを超えることはできません。 |
x-oss-security-token | String | 任意 | STSから取得されるセキュリティトークン。 このパラメーターは、セキュリティトークンを使用してURLの署名を作成する場合にのみ必要です。 STSのAssumeRole操作を呼び出して、セキュリティトークンを取得できます。 デフォルトでは、この要素は空のままです。 |
ファイル | String | 必須 | ファイルまたはテキストの内容。 コンテンツをエンコードする必要はありません。 ブラウザは、ファイルタイプに基づいてContent-Typeフォームフィールドを自動的に追加し、content-typeヘッダーで指定されたコンテンツタイプを上書きします。 PostObjectリクエストを使用してアップロードできるオブジェクトは1つだけです。 デフォルトでは、この要素は空のままです。 重要 最後のフォームフィールドはファイルでなければなりません。 |
レスポンスヘッダー
ヘッダー | タイプ | 例 | 説明 |
x-oss-server-side-encryption | String | KMS | サーバー側でオブジェクトを暗号化するために使用されるアルゴリズム。 リクエストにx-oss-server-side-encryptionが指定されている場合、レスポンスにはこのヘッダーが含まれます。 |
Content-MD5 | String | 1B2M2Y8AsgTpgAmY7PhC **** | オブジェクトのMD5ハッシュ。 重要 オブジェクトのMD5ハッシュは、クライアントがオブジェクトをアップロードした後に取得されます。 オブジェクトのMD5ハッシュは、レスポンスボディのMD5ハッシュではありません。 |
x-oss-hash-crc64ecma | String | 316181249502703 **** | オブジェクトのCRC-64値。 |
x-oss-version-id | String | CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0 **** | オブジェクトのバージョンID。 このヘッダーは、バージョン管理が有効なバケットにオブジェクトをアップロードした場合にのみ返されます。 |
PostObjectリクエストへのレスポンスの一般的なレスポンスヘッダー (Dateやx-oss-request-idなど) の詳細については、「一般的なレスポンスヘッダー」をご参照ください。
レスポンス要素
要素 | タイプ | 説明 |
PostResponse | Container | PostObjectリクエストの結果を格納するコンテナー。 子ノード: バケット、ETag、キー、および場所 |
Bucket | String | バケットの名前です。 親ノード: PostResponse |
ETag | String | オブジェクトのアップロード時に作成されるエンティティタグ (ETag) 。 PostObject操作を呼び出してオブジェクトが作成された場合、ETag値はオブジェクトコンテンツのMD5ハッシュではなく、特定のルールに基づいて計算された一意の値になります。 オブジェクトのETag値を使用して、オブジェクトの内容が変更されているかどうかを確認できます。 親ノード: PostResponse |
場所 | String | アップロードされたオブジェクトへのアクセスに使用されるURL。 親ノード: PostResponse |
例
リクエストの例
POST / HTTP/1.1 Host: oss-example.oss-cn-hangzhou.aliyuncs.com Content-Length: 344606 Content-Type: multipart/form-data; boundary=9431149156168 --9431149156168 Content-Disposition: form-data; name="key" /user/a/objectName.txt --9431149156168 Content-Disposition: form-data; name="success_action_status" 200 --9431149156168 Content-Disposition: form-data; name="Content-Disposition" content_disposition --9431149156168 Content-Disposition: form-data; name="x-oss-meta-uuid" uuid --9431149156168 Content-Disposition: form-data; name="x-oss-meta-tag" metadata --9431149156168 Content-Disposition: form-data; name="OSSAccessKeyId" 44CF9590006BF252**** --9431149156168 Content-Disposition: form-data; name="policy" eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ== --9431149156168 Content-Disposition: form-data; name="Signature" kZoYNv66bsmc10+dcGKw5x2P**** --9431149156168 Content-Disposition: form-data; name="file"; filename="MyFilename.txt" Content-Type: text/plain abcdefg --9431149156168 Content-Disposition: form-data; name="submit" Upload to OSS --9431149156168--
正常に処理された場合のレスポンス例
HTTP/1.1 200 OK x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e Date: Fri, 24 Feb 2014 06:03:28 GMT ETag: "5B3C1A2E053D763E1B002CC607C5****" Connection: keep-alive Content-Length: 0 x-oss-hash-crc64ecma: 316181249502703**** Content-MD5: 1B2M2Y8AsgTpgAmY7PhC**** Server: AliyunOSS
エラーコード
エラーコード | HTTPステータスコード | 説明 |
FieldItemTooLong | 400 | フォームフィールドキーのサイズが8 KBを超えるか、フォームフィールド値のサイズが2 MBを超えています。 |
InvalidArgument | 400 | OSSAccessKeyId、policy、およびSignatureフォームフィールドの1つが指定されていますが、バケットのACLがpublic-read-writeであるかどうかに関係なく、他の2つのフォームフィールドはリクエストで指定されていません。 |
InvalidDigest | 400 | リクエストボディに基づいてOSSによって計算されるContent-MD5値は、リクエストヘッダーに指定されているContent-MD5値とは異なります。 |
EntityTooLarge | 400 | PostObjectリクエストボディの合計サイズが5 GBを超えています。 |
InvalidEncryptionAlgorithmError | 400 | x-oss-server-side-encryptionヘッダーが以外の値に設定されています。 AES256またはKMS。 x-oss-server-side-encryptionヘッダーは、AES256またはKMSにのみ設定できます。 |
IncorrectNumberOfFilesInPOSTRequest | 400 | PostObjectリクエストには、複数のファイルフォームフィールドが含まれています。 PostObjectリクエストには、ファイルフォームフィールドを1つだけ含めることができます。 |
FileAlreadyExists | 409 | リクエストにはx-oss-forbid-overwrite=true要素が含まれていますが、同じ名前のオブジェクトはすでに存在しています。 |
KmsServiceNotEnabled | 403 | x-oss-server-side-encryptionヘッダーはKMSに設定されていますが、KMSは事前にアクティブ化されていません。 |
FileImmutable | 409 | 削除または変更するデータは、保持ポリシーによって保護されます。 |
POSTポリシー
PostObjectリクエストのポリシーフォームフィールドは、HTMLフォームを使用してオブジェクトをアップロードするために開始するPostObjectリクエストの有効期限と条件を指定するために使用されます。 ポリシーフォームフィールドの値は、オブジェクトをアップロードするバケット名、オブジェクト名のプレフィックス、リクエストの有効期間、許可されたHTTPメソッド、オブジェクトのサイズとコンテンツなど、複数のパラメーターを指定することでPostObjectリクエストを制限するJSON文字列です。
POST署名
PostObjectリクエストの有効性とセキュリティを確保するには、PostObjectリクエストに署名を含める必要があります。
PostObjectリクエストのV4署名の詳細については、「 (推奨) PostObjectリクエストにV4署名を含める」をご参照ください。
PostObjectリクエストのV1署名の詳細については、「PostObjectリクエストにV1署名を含める」をご参照ください。
よくある質問
「提案されたアップロードが最大許容サイズを超えた」というエラーメッセージが返された場合はどうすればよいですか?
原因: アップロードされたオブジェクトのサイズが、content-length-rangeパラメーターで指定されたサイズ範囲を超えています。
解決策: content-length-rangeパラメーターを使用して、アップロードされるオブジェクトの最小サイズと最大サイズを指定します。 単位はバイトです。 たとえば、アップロードするオブジェクトのサイズが1 GBの場合、content-length-rangeパラメーターを ["content-length-range", 1, 1073741824] に設定できます。
関連ドキュメント
フォームアップロードを使用してwebクライアントからOSSにデータを転送する方法の詳細については、「JavaScriptを使用してクライアントに署名を追加し、データをOSSにアップロードする」をご参照ください。
PostObjectおよび対応するソリューションを呼び出すときに発生する一般的なエラーの詳細については、「PostObject」をご参照ください。