すべてのプロダクト
Search

このプロダクト

    Object Storage Service:PostObject

    ドキュメントセンター

    Object Storage Service:PostObject

    最終更新日:Apr 01, 2026

    PostObject オペレーションを使用すると、HTML フォームを介して指定したバケットにオブジェクトをアップロードできます。

    注意事項

    • HTML フォームを介してオブジェクトをアップロードするには、oss:PutObject 権限が必要です。詳細については、「RAM ユーザーへのカスタムポリシーのアタッチ」をご参照ください。

    • PostObject オペレーションでアップロード可能なオブジェクトの最大サイズは 5 GB です。

    • POST リクエストでは、バケットに対する書き込み権限が必要です。バケットが公開読み書き（public-read-write）の場合、署名は不要です。それ以外の場合は、Object Storage Service (OSS) がこのオペレーションの署名を検証します。

    • PutObject オペレーションとは異なり、PostObject オペレーションでは AccessKey Secret を使用してポリシーに署名します。この署名は、フォームフィールド Signature の値となります。

    • フォーム送信先の URL はバケットのエンドポイントです。URL 内でオブジェクトを指定する必要はありません。リクエスト行は POST / HTTP/1.1 である必要があります（POST /ObjectName HTTP/1.1 ではありません）。

    • POST リクエストでヘッダーまたは URL 内に署名が含まれている場合、OSS はその情報を検証しません。

    バージョン管理

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

    バージョン管理が一時停止されたバケットに対して PostObject リクエストを送信すると、OSS はアップロードされたオブジェクトに null バージョン ID を割り当て、レスポンスヘッダー x-oss-version-id でそのバージョン 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 形式でエンコードされます。PutObject オペレーションではパラメーターを HTTP リクエストヘッダーで渡しますが、PostObject オペレーションでは、パラメーターをメッセージボディ内のフォームフィールドとして渡します。

    • PostObject オペレーションでは、x-oss-tagging リクエストヘッダーを含めることでオブジェクトにタグを付与することはできません。PostObject オペレーションの完了後、PutObjectTagging API を呼び出してオブジェクトにタグを付与できます。

    パラメーター

    型

    必須

    説明

    Content-Type

    String

    いいえ

    オブジェクトのタイプおよび Web ページのエンコード形式を指定します。この情報により、ブラウザがオブジェクトをどのように読み取るかが決定されます。

    POST フォームは multipart/form-data としてエンコードする必要があります。Content-Type ヘッダーは multipart/form-data;boundary=xxxxxx のフォーマットである必要があります。

    boundary は、フォームによってランダムに生成される境界文字列です。この文字列を明示的に指定する必要はありません。SDK を使用してフォームを構築する場合、SDK が自動的にランダムな値を boundary に設定します。

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

    フォームフィールド

    以下の表は、V1 署名および V4 署名の両方で使用される POST リクエストに共通するフォームフィールドを示しています。V4 署名専用のフォームフィールドについては、「V4 署名フォーム」をご参照ください。V1 署名専用のフォームフィールドについては、「V1 署名フォーム」をご参照ください。

    重要

    • file フィールドは最後に配置する必要があります。他のフォームフィールドの順序は任意です。

    • 任意のフォームフィールドのキーは 8 KB を超えてはならず、値は 2 MB を超えてはなりません。

    パラメーター

    型

    必須

    説明

    Cache-Control

    String

    いいえ

    オブジェクトをダウンロードする際のキャッシュ動作を指定します。詳細については、「RFC 2616」をご参照ください。

    デフォルト値：なし

    Content-Disposition

    String

    いいえ

    オブジェクトをダウンロードする際の名前を指定します。詳細については、「RFC 2616」をご参照ください。

    デフォルト値：なし

    Content-Encoding

    String

    いいえ

    オブジェクトをダウンロードする際のコンテンツエンコード形式を指定します。詳細については、「RFC 2616」をご参照ください。

    デフォルト値：なし

    Expires

    String

    いいえ

    有効期限を指定します。詳細については、「RFC 2616」をご参照ください。

    デフォルト値：なし

    policy

    String

    条件付き

    ポリシーは、リクエストフォームが満たす必要がある条件を指定します。ポリシーフォームフィールドを含まないリクエストは匿名リクエストと見なされ、公開読み書き（public-read-write）バケットにのみアクセスできます。

    デフォルト値：なし

    制約：バケットが公開読み書き（public-read-write）でない場合、またはリクエストに OSSAccessKeyId または Signature フォームフィールドが含まれる場合、ポリシーフォームフィールドは必須です。

    重要

    フォームおよびポリシーは UTF-8 エンコーディングである必要があります。また、ポリシーフォームフィールドは Base64 エンコーディングも必要です。

    x-oss-server-side-encryption-key-id

    String

    いいえ

    KMS が管理するカスタマーマスターキーを示します。このオプションは、x-oss-server-side-encryption が KMS に設定されている場合にのみ有効です。

    x-oss-content-type

    String

    いいえ

    オブジェクトの Content-Type を指定します。ブラウザは、ファイルフォームフィールドに対して自動的に Content-Type を追加します。これを解決するために、OSS では POST リクエストのボディに x-oss-content-type フォームフィールドを追加して Content-Type を明示的に指定できます。このフィールドが最も高い優先度を持ちます。

    優先度順： x-oss-content-type > ファイルフォームフィールドの 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 処理性能が低下します。多数の操作（QPS > 1000）で x-oss-forbid-overwrite リクエストヘッダーを使用する場合は、業務への影響を避けるためテクニカルサポートまでお問い合わせください。

    x-oss-object-acl

    String

    いいえ

    オブジェクトのアクセス制御リスト（ACL）を指定します。

    有効な値：

    • default（デフォルト）：オブジェクトの ACL はバケットの ACL と同じです。

    • 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

    いいえ

    セキュリティトークンです。これは、セキュリティトークンサービス（STS）を使用して署名付き URL を生成する場合にのみ必要です。STS の AssumeRole オペレーションを呼び出すことでセキュリティトークンを取得できます。

    デフォルト値: なし

    x-oss-object-worm-mode

    String

    いいえ

    オブジェクトの保持ポリシーモードを指定します。値は COMPLIANCE に設定します。このフィールドは、バケットで オブジェクトレベルの保持ポリシー（ObjectWorm） が有効化されている場合にのみ有効です。このフィールドを設定する場合は、x-oss-object-worm-retain-until-date も設定する必要があります。

    x-oss-object-worm-retain-until-date

    String

    いいえ

    ISO 8601 形式で指定するオブジェクトの保持期間の満了日です。このフィールドは、バケットで オブジェクトレベルの保持ポリシー（ObjectWorm） が有効化されている場合にのみ有効です。保持期間の満了日までは、オブジェクトを削除または上書きできません。このフィールドを指定しない場合、バケットのデフォルト保持ルール（設定済みの場合）がアップロードされたオブジェクトに適用されます。

    file

    String

    はい

    オブジェクトのコンテンツです。コンテンツをエンコードする必要はありません。ブラウザはファイルタイプに基づいて自動的に Content-Type を設定し、ユーザーによる設定をオーバーライドします。一度にアップロードできるオブジェクトは 1 つのみです。

    デフォルト値：なし

    重要

    file フォームフィールドはフォーム内で最後に配置する必要があります。

    レスポンスヘッダー

    パラメーター

    型

    例

    説明

    x-oss-server-side-encryption

    String

    KMS

    リクエストで x-oss-server-side-encryption ヘッダーが指定されている場合、レスポンスにはこのヘッダーが含まれ、使用されるサーバ側暗号化アルゴリズムが示されます。

    Content-MD5

    String

    1B2M2Y8AsgTpgAmY7PhC****

    オブジェクトの MD5 ハッシュです。

    重要

    これは、クライアントがアップロードを完了した後のオブジェクトの MD5 ハッシュであり、レスポンスボディの MD5 ハッシュではありません。

    x-oss-hash-crc64ecma

    String

    316181249502703****

    オブジェクトの CRC-64 ハッシュです。

    x-oss-version-id

    String

    CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

    オブジェクトのバージョン ID です。このヘッダーは、バージョン管理が有効化されたバケットにオブジェクトをアップロードした場合にのみ返されます。

    このオペレーションでは、Date や x-oss-request-id などのその他の共通レスポンスヘッダーも含まれます。詳細については、「共通レスポンスヘッダー」をご参照ください。

    レスポンス要素

    パラメーター

    型

    説明

    PostResponse

    Container

    POST リクエストの結果を格納するコンテナです。

    子ノード：Bucket、ETag、Key、Location

    Bucket

    String

    バケット名です。

    親ノード：PostResponse

    ETag

    String

    OSS はオブジェクト生成時に ETag（Entity Tag）を作成します。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 を使用して、この API オペレーションを呼び出すことができます。

    エラーコード

    エラーコード

    HTTP ステータスコード

    説明

    FieldItemTooLong

    400

    フォームフィールドのキーのサイズが 8 KB を超えるか、フォームフィールドの値のサイズが 2 MB を超えています。

    InvalidArgument

    400

    バケットが公開読み書き（public-read-write）かどうかに関係なく、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 リクエストには file フォームフィールドが 1 つだけ含まれる必要があります。

    FileAlreadyExists

    409

    リクエストに x-oss-forbid-overwrite=true が含まれており、同じ名前のオブジェクトの上書きが禁止されています。オブジェクトがすでに存在する場合、このエラーが返されます。

    KmsServiceNotEnabled

    403

    x-oss-server-side-encryption が KMS に設定されていますが、KMS サービスが有効化されていません。

    FileImmutable

    409

    保持ポリシーで保護されたデータを削除または変更しようとした場合に返されるエラーコードです。

    MethodNotAllowed

    405

    HTTP リクエストメソッドがサーバーでサポートされていないか、許可されていません。リクエストメソッドおよびヘッダーが正しいこと、およびサーバーがそのメソッドをサポートしていることを確認してください。プロトコル、ドメイン、パスを含む URL を確認してください。

    POST ポリシー

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

    POST 署名

    POST 署名は、PostObject メソッドを使用するすべてのアップロードリクエストに含める必要がある署名であり、アップロードリクエストの正当性およびセキュリティを保証します。

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

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

    よくある質問

    最大許容サイズエラー

    • 原因：content-length-range で指定された範囲外のサイズのオブジェクトがアップロードされました。

    • 解決方法：content-length-range を使用して、アップロード可能な最小および最大サイズ（バイト単位）を指定します。たとえば、1 GB のオブジェクトをアップロードする場合、content-length-range を ["content-length-range", 1, 1073741824] に設定できます。

    参照