すべてのプロダクト
Search

このプロダクト

    Object Storage Service:PostObject

    ドキュメントセンター

    Object Storage Service:PostObject

    最終更新日:Dec 06, 2024

    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操作で送信されるフォームは、multipart/form-data形式でエンコードする必要があります。 Content-Typeヘッダーは、multipart/form-data;boundary=xxxxxx形式である必要があります。

    この形式では、境界はフォームによってランダムに生成される境界文字列です。 境界文字列を指定する必要はありません。 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が指定されていない場合、またはx-oss-forbid-overwriteがfalseに設定されている場合、PostObject操作を呼び出してアップロードされたオブジェクトは、同じ名前の既存のオブジェクトを上書きします。

    • x-oss-forbid-overwriteがtrueに設定されている場合、PostObject操作を呼び出してアップロードされたオブジェクトは、同じ名前の既存のオブジェクトを上書きしません。

    x-oss-forbid-overwriteを指定すると、OSSの1秒あたりのクエリ (QPS) パフォーマンスが低下する可能性があります。 x-oss-forbid-overwriteを使用して多数の操作 (QPSが1,000を超える) を実行する場合は、テクニカルサポートにお問い合わせください。

    x-oss-object-acl

    String

    任意

    アップロードするオブジェクトのACL。 フォームフィールドでアップロードするオブジェクトのACLを指定できます。

    有効な値：

    • デフォルト: オブジェクトのACLは、オブジェクトが格納されているバケットのACLと同じです。 デフォルト値です。

    • private: オブジェクトのACLがprivateです。 オブジェクトの読み取りおよび書き込み権限を持つのは、オブジェクトの所有者および許可されたユーザーのみです。

    • public-read: オブジェクトのACLはpublic-readです。 オブジェクトの読み取りおよび書き込み権限を持つのは、オブジェクトの所有者および許可されたユーザーのみです。 他のユーザーには、オブジェクトに対する読み取り権限のみがあります。 オブジェクトのACLをこの値に設定する場合は注意してください。

    • public-read-write: オブジェクトのACLはpublic-read-writeです。 すべてのユーザーは、オブジェクトに対する読み取りおよび書き込み権限を持っています。 オブジェクトのACLをこの値に設定する場合は注意してください。

    詳細については、「オブジェクトACL」をご参照ください。

    x-oss-storage-class

    String

    任意

    オブジェクトのストレージクラス。

    オブジェクトをアップロードするときにx-oss-storage-classヘッダーを指定した場合、オブジェクトがアップロードされるバケットのストレージクラスに関係なく、アップロードされたオブジェクトのストレージクラスは指定された値になります。 たとえば、低頻度アクセス (IA) バケットにオブジェクトをアップロードするときにx-oss-storage-classヘッダーを標準に設定すると、オブジェクトは標準オブジェクトとして保存されます。

    有効な値：

    • Standard

    • IA

    • アーカイブ

    • ColdArchive

    • DeepColdArchive

      重要

      多数のオブジェクトをアップロードし、オブジェクトのストレージクラスをDeep Cold Archiveに設定する場合は、高いPUTリクエスト料金が請求されます。 オブジェクトのアップロード時にオブジェクトのストレージクラスを標準に設定し、標準オブジェクトのストレージクラスをDeep Cold Archiveに変換するようにライフサイクルルールを設定することを推奨します。 これにより、PUTリクエスト料金が削減されます。

    詳細については、「概要」をご参照ください。

    キー

    String

    必須

    アップロードするオブジェクトの名前。 オブジェクト名をエンコードする必要はありません。 オブジェクト名にdestfolder/example.jpgなどのパスが含まれている場合、OSSは対応するディレクトリを作成します。

    デフォルトでは、この要素は空のままです。

    success_action_redirect

    String

    任意

    オブジェクトのアップロード後にクライアントがリダイレクトされるURL。 このフォームフィールドが指定されていない場合、返される結果はsuccess_action_statusフォームフィールドによって指定されます。 アップロードが失敗した場合、OSSはエラーコードを返し、クライアントはURLにリダイレクトされません。

    デフォルトでは、この要素は空のままです。

    success_action_status

    String

    任意

    success_action_redirectフォームフィールドが指定されておらず、オブジェクトがアップロードされた場合にクライアントに返されるHTTPステータスコード。

    有効な値: 200、201、204 (デフォルト) 。

    • このフォームフィールドが200または204に設定されている場合、OSSは空のファイルとHTTPステータスコードの200または204を返します。

    • このフォームフィールドが201に設定されている場合、OSSはXMLファイルとHTTPステータスコード201を返します。

    • このフォームフィールドが指定または無効な値に設定されていない場合、OSSは空のファイルとHTTPステータスコード204を返します。

    x-oss-meta-*

    String

    任意

    オブジェクトのユーザーメタデータ。

    デフォルトでは、この要素は空のままです。

    リクエストにx-oss-meta-プレフィックスを含む名前のフォームフィールドが含まれている場合、そのフォームフィールドはオブジェクトのユーザーメタデータと見なされます。 例: x-oss-meta-location

    説明

    オブジェクトは、名前に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

    コンテナー

    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リクエストに署名を含める必要があります。

    よくある質問

    「提案されたアップロードが最大許容サイズを超えた」というエラーメッセージが返された場合はどうすればよいですか?

    • 原因: アップロードされたオブジェクトのサイズが、content-length-rangeパラメーターで指定されたサイズ範囲を超えています。

    • 解決策: content-length-rangeパラメーターを使用して、アップロードされるオブジェクトの最小サイズと最大サイズを指定します。 単位はバイトです。 たとえば、アップロードするオブジェクトのサイズが1 GBの場合、content-length-rangeパラメーターを ["content-length-range", 1, 1073741824] に設定できます。

    関連ドキュメント