PostObject - Object Storage Service - Alibaba Cloud ドキュメントセンター

PostObject 操作を呼び出して、HTML フォームを使用して指定されたバケットにオブジェクトをアップロードできます。

注意事項

HTML フォームを使用してファイルをアップロードするには、oss:PutObject 権限が必要です。詳細については、「RAM ユーザーへのカスタムポリシーのアタッチ」をご参照ください。
PostObject 操作を使用してアップロードされるオブジェクトのサイズは 5 GB を超えることはできません。
PostObject リクエストには、バケットへの書き込み権限が必要です。バケットのアクセス制御リスト (ACL) が公開読み書きの場合、署名情報を含める必要はありません。それ以外の場合、Object Storage Service (OSS) はリクエスト内の署名を認証します。
PutObject 操作とは異なり、PostObject 操作では AccessKey Secret を使用してポリシーに署名します。計算された署名文字列は、Signature フォームフィールドの値として使用されます。OSS はこの値を認証して、署名の有効性を判断します。
送信されるフォームの URL はバケットのドメイン名です。URL でオブジェクトを指定する必要はありません。リクエストラインは POST / HTTP/1.1 であり、POST /ObjectName HTTP/1.1 ではありません。
POST リクエストのヘッダーまたは URL に署名情報が含まれている場合、OSS はこの情報をチェックしません。

バージョン管理

バージョン管理が有効なバケットに PostObject リクエストを送信すると、OSS は新しいオブジェクトの一意のバージョン ID を自動的に生成します。この ID は、レスポンスの x-oss-version-id ヘッダーで返されます。

バージョン管理が一時停止されているバケットに PostObject リクエストを送信すると、OSS は新しいオブジェクトの null バージョン ID を自動的に生成します。この ID は、レスポンスの x-oss-version-id ヘッダーで返されます。同じオブジェクトに対して許可される null バージョン ID は 1 つだけです。

リクエスト構文

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 形式でエンコードされます。パラメーターが HTTP リクエストヘッダーで渡される PutObject 操作とは異なり、PostObject 操作ではパラメーターがメッセージ本文のフォームフィールドとして渡されます。
PostObject 操作で x-oss-tagging リクエストヘッダーを含めてオブジェクトにタグを追加することはできません。PostObject 操作が完了した後、PutObjectTagging 操作を呼び出してオブジェクトにタグを追加できます。

名前

タイプ

必須

説明

Content-Type

String

いいえ

ファイルの種類と Web ページのエンコーディング。これにより、ブラウザがファイルを読み取ってエンコードする方法が決まります。

Post 操作で送信されるフォームは、multipart/form-data 形式でエンコードする必要があります。これは、Content-Type ヘッダーが multipart/form-data;boundary=xxxxxx 形式であることを意味します。

boundary はフォームによって生成されるランダムな文字列です。指定する必要はありません。SDK を使用してフォームを構築する場合、SDK もランダムな値を生成します。

この操作では、Host や Date などの共通リクエストヘッダーも使用します。詳細については、「共通リクエストヘッダー」をご参照ください。

フォーム要素

次の表では、V1 署名と V4 署名の両方に共通するフォーム要素について説明します。V4 署名に固有のフォーム要素については、「V4 署名フォーム」をご参照ください。V1 署名に固有のフォーム要素については、「V1 署名フォーム」をご参照ください。

重要

file フィールドは最後のフォームフィールドでなければなりません。他のフォームフィールドは任意の順序で配置できます。
フォームフィールドのキーのサイズは 8 KB を超えることはできず、値のサイズは 2 MB を超えることはできません。

名前	タイプ	必須	説明
Cache-Control	String	いいえ	オブジェクトのダウンロード時の Web ページのキャッシュ動作を指定します。詳細については、「RFC 2616」をご参照ください。デフォルト値：なし。
Content-Disposition	String	いいえ	オブジェクトがダウンロードされるときのオブジェクトの名前を指定します。詳細については、「RFC 2616」をご参照ください。デフォルト値：なし。
Content-Encoding	String	いいえ	オブジェクトがダウンロードされるときのオブジェクトのコンテンツエンコード形式を指定します。詳細については、「RFC 2616」をご参照ください。デフォルト値：なし。
Expires	String	いいえ	有効期限。詳細については、「RFC 2616」をご参照ください。デフォルト値：なし。
policy	String	はい、条件付き	ポリシーはリクエストフォームフィールドの有効性を指定します。policy フォームフィールドを含まないリクエストは匿名リクエストと見なされ、公開読み書きバケットへのアクセスにのみ使用できます。デフォルト値：なし。制約：バケットが公開読み書きでない場合、または OSSAccessKeyId または Signature フォームフィールドが指定されている場合、policy フォームフィールドは必須です。重要フォームとポリシーは UTF-8 でエンコードする必要があります。policy フォームフィールドは Base64 でエンコードする必要もあります。
x-oss-server-side-encryption-key-id	String	いいえ	KMS によって管理されるカスタマーマスターキー (CMK)。この要素は、x-oss-server-side-encryption が KMS に設定されている場合にのみ有効です。
x-oss-content-type	String	いいえ	ブラウザは自動的に file フォームフィールドに Content-Type を追加します。これに対処するため、OSS は Post リクエスト本文に x-oss-content-type を追加することをサポートしています。この要素を使用すると Content-Type を指定でき、最も高い優先度を持ちます。優先順位：x-oss-content-type > file フォームフィールドの Content-Type デフォルト値：なし。
x-oss-forbid-overwrite	String	いいえ	PostObject 操作中に同じ名前のオブジェクトを上書きするかどうかを指定します。宛先バケットがバージョン管理が有効または一時停止状態の場合、x-oss-forbid-overwrite リクエストヘッダーは無効です。これは、同じ名前のオブジェクトを上書きできることを意味します。 x-oss-forbid-overwrite を指定しないか、x-oss-forbid-overwrite を false に設定した場合、同じ名前のオブジェクトを上書きできます。 x-oss-forbid-overwrite を true に設定した場合、同じ名前のオブジェクトは上書きできません。 x-oss-forbid-overwrite リクエストヘッダーを設定すると、QPS パフォーマンスが低下します。x-oss-forbid-overwrite リクエストヘッダーを必要とする操作が多い場合 (QPS > 1,000)、ビジネスに影響を与えないように、テクニカルサポートにご連絡ください。
x-oss-object-acl	String	いいえ	file フォームフィールド内のオブジェクトのアクセス権限を指定します。この要素は file フォームフィールドで指定できます。有効な値： default (デフォルト)：オブジェクトはバケットのアクセス権限を継承します。 private：オブジェクトは非公開リソースです。オブジェクト所有者と承認されたユーザーのみがオブジェクトに対する読み書き権限を持ちます。他のユーザーはオブジェクトにアクセスできません。 public-read：オブジェクトは公開読み取りリソースです。オブジェクト所有者と承認されたユーザーのみがオブジェクトに対する読み書き権限を持ちます。他のユーザーはオブジェクトに対する読み取り権限のみを持ちます。この権限は注意して使用してください。 public-read-write：オブジェクトは公開読み書きリソースです。すべてのユーザーがオブジェクトに対する読み書き権限を持ちます。この権限は注意して使用してください。アクセス権限の詳細については、「オブジェクト ACL」をご参照ください。
x-oss-storage-class	String	いいえ	オブジェクトのストレージクラスを指定します。どのストレージクラスのバケットでも、オブジェクトをアップロードするときにこのパラメーターを指定すると、アップロードされたオブジェクトは指定されたストレージクラスに格納されます。たとえば、IA バケットにオブジェクトをアップロードするときに x-oss-storage-class を Standard として指定すると、オブジェクトは Standard オブジェクトとして格納されます。有効な値： Standard：標準 IA：低頻度アクセス Archive：アーカイブストレージ ColdArchive：コールドアーカイブ DeepColdArchive：ディープコールドアーカイブ重要アップロード時にストレージクラスをディープコールドアーカイブに設定すると、PUT リクエスト料金が高くなります。オブジェクトをアップロードする際はストレージクラスを標準に設定し、ライフサイクルルールを設定して標準オブジェクトのストレージクラスをディープコールドアーカイブに移行することをお勧めします。これにより、PUT リクエスト料金を削減できます。詳細については、「ストレージクラス」をご参照ください。
key	String	はい	アップロードするオブジェクトの名前。名前をエンコードしないでください。名前が `destfolder/example.jpg` のようなパスを含む場合、OSS は対応するフォルダを自動的に作成します。デフォルト値：なし。
success_action_redirect	String	いいえ	アップロード成功後にクライアントがリダイレクトされる URL。このフォームフィールドが指定されていない場合、返される結果は success_action_status フォームフィールドによって指定されます。アップロードが失敗した場合、OSS はエラーコードを返し、リダイレクトは実行しません。デフォルト値：なし。
success_action_status	String	いいえ	success_action_redirect フォームフィールドが指定されていない場合、このフォームフィールドはアップロード成功後にクライアントに返されるステータスコードを指定します。有効な値：200、201、および 204 (デフォルト)。このフィールドが 200 または 204 に設定されている場合、OSS は空のドキュメントと対応するステータスコードを返します。このフィールドが 201 に設定されている場合、OSS は XML ファイルと 201 ステータスコードを返します。このフィールドが設定されていないか、無効な値に設定されている場合、OSS は空のドキュメントと 204 ステータスコードを返します。
x-oss-meta-*	String	いいえ	ユーザーが指定したユーザーメタ。デフォルト値：なし。リクエストに x-oss-meta- というプレフィックスが付いたフォームフィールドが含まれている場合、そのフィールドはユーザーメタと見なされます。たとえば、`x-oss-meta-location` です。説明オブジェクトには複数のこのようなパラメーターを含めることができますが、すべてのユーザーメタの合計サイズは 8 KB を超えることはできません。
x-oss-security-token	String	いいえ	セキュリティトークン。このパラメーターは、Security Token Service (STS) を使用して署名付き URL を構築する場合にのみ必要です。STS の AssumeRole 操作を呼び出すことでセキュリティトークンを取得できます。デフォルト値：なし。
file	String	はい	ファイルまたはテキストコンテンツ。コンテンツをエンコードしないでください。ブラウザはファイルタイプに基づいて Content-Type を自動的に設定し、設定を上書きします。OSS は一度に 1 つのファイルしかアップロードできません。デフォルト値：なし。重要 file フィールドは最後のフォームフィールドでなければなりません。

レスポンスヘッダー

名前	タイプ	例	説明
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。このレスポンスヘッダーは、バージョン管理が有効なバケットにファイルをアップロードした場合にのみ返されます。

この操作は、Date や x-oss-request-id などの共通レスポンスヘッダーも返します。詳細については、「共通レスポンスヘッダー」をご参照ください。

レスポンス要素

名前	タイプ	説明
PostResponse	コンテナー	Post リクエストの結果を格納するコンテナー。子ノード：Bucket、ETag、Key、Location
Bucket	String	バケットの名前。親ノード：PostResponse
ETag	String	ETag (エンティティタグ) は、各オブジェクトが生成されるときに作成されます。Post リクエストによって作成されたオブジェクトの場合、ETag は特定の計算ルールに基づいて生成された一意の値ですが、オブジェクトのコンテンツの MD5 ハッシュではありません。ETag は、オブジェクトのコンテンツが変更されたかどうかを確認するために使用できます。親ノード：PostResponse
Location	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

SDK

この操作は、次の SDK を使用して呼び出すことができます：

エラーコード

エラーコード	HTTP ステータスコード	説明
FieldItemTooLong	400	フォームフィールドのキーのサイズは 8 KB を超えることはできず、フォームフィールドの値のサイズは 2 MB を超えることはできません。
InvalidArgument	400	バケットが公開読み書きであるかどうかに関係なく、OSSAccessKeyId、policy、または Signature フォームフィールドのいずれかがアップロードされた場合、他の 2 つのフォームフィールドは必須です。それらが欠落している場合、このエラーが返されます。
InvalidDigest	400	Content-MD5 ヘッダー付きのリクエストをアップロードすると、OSS は本文の Content-MD5 を計算し、一貫性をチェックします。一致しない場合、このエラーが返されます。
EntityTooLarge	400	リクエスト本文の合計長は 5 GB を超えることはできません。ファイルが大きすぎる場合、このエラーが返されます。
InvalidEncryptionAlgorithmError	400	アップロード中に x-oss-server-side-encryption リクエストヘッダーを指定する場合、その値を AES256 または KMS に設定する必要があります。別の値に設定すると、このエラーが返されます。
IncorrectNumberOfFilesInPOSTRequest	400	Post リクエスト内のファイルの数が無効です。Post リクエストには 1 つの file フォームフィールドしか含めることができません。
FileAlreadyExists	409	リクエストヘッダーに x-oss-forbid-overwrite=true が含まれている場合、同じ名前のオブジェクトは上書きできません。ファイルが既に存在する場合、このエラーが返されます。
KmsServiceNotEnabled	403	x-oss-server-side-encryption が KMS として指定されていますが、事前に KMS スイートを購入していません。
FileImmutable	409	保護されているバケット内のデータを削除または変更しようとすると、このエラーコードが返されます。
MethodNotAllowed	405	HTTP リクエストメソッドがサーバーでサポートされていないか、許可されていません。リクエストメソッドとヘッダーを確認して、ヘッダー情報が正しく、サービスがリクエストメソッドをサポートしていることを確認してください。URL を確認して、プロトコル、ドメイン名、パスが正しいことを確認してください。

POST ポリシー

policy フォームフィールドは、JSON 形式で定義されたセキュリティポリシーです。このフィールドは、HTML フォームを使用して OSS にファイルをアップロードするための権限の制限と制約を指定します。ポリシーは、バケット名、オブジェクトプレフィックス、有効期間、許可される HTTP メソッド、アップロードサイズとコンテンツタイプの制限など、複数のパラメーターを使用してアップロード操作を制限します。

POST リクエストの V4 署名のポリシーの詳細については、「POST リクエスト V4 署名ポリシー」をご参照ください。
POST リクエストの V1 署名のポリシーの詳細については、「POST リクエスト V1 署名ポリシー」をご参照ください。

POST 署名

POST 署名は、アップロードリクエストのセキュリティを保証します。PostObject 操作を使用する場合、OSS は各アップロードリクエストに署名を含めて、リクエストの正当性とセキュリティを検証することを要求します。

POST リクエストの V4 署名の詳細については、「POST リクエスト V4 署名」をご参照ください。
POST リクエストの V1 署名の詳細については、「POST リクエスト V1 署名」をご参照ください。

よくある質問

「Your proposed upload exceeds the maximum allowed size」というエラーが返された場合の対処方法

原因：アップロードされたファイルのサイズが content-length-range で指定された範囲外です。
解決策：content-length-range を使用して、アップロードされるファイルの最小および最大許容サイズをバイト単位で指定します。たとえば、1 GB のファイルをアップロードするには、content-length-range を ["content-length-range", 1, 1073741824] に設定できます。

Object Storage Service:PostObject