Uploads an object to a specified bucket by using an HTML form.

Usage notes

  • Objects uploaded by using PostObject cannot be larger than 5 GB in size.
  • To initiate a PostObject request to a bucket, you must have write permissions on the bucket. If the ACL of the bucket to which you want to initiate a PostObject request is public read and write, you do not need to sign the PostObject request. Otherwise, Object Storage Service (OSS) verifies the signature information contained in the request.
  • Unlike PutObject, PostObject uses an AccessKey secret to calculate the signature for the policy form field. The calculated signature string is used as the value of the Signature form field. OSS checks this value to verify the validity of the signature.
  • The URL of the submitted form is the domain name of the bucket. You do not need to specify the object to upload in the URL. In other words, the request line is in the format of POST / HTTP/1.1 instead of POST /ObjectName HTTP/1.1.
  • OSS does not check the signature included in headers or URLs in PostObject requests.

Versioning

If you initiate a PostObject request to a bucket for which versioning is enabled, OSS generates a unique version ID for the uploaded object and returns the version ID as the x-oss-version-id header in the response.

If you initiate a PostObject request to a bucket for which versioning is suspended, OSS generates a version ID null for the uploaded object and returns the version ID as the x-oss-version-id header in the response. An object can have only one version whose version ID is null.

Request structure

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--

Request headers

Note The message body of a PostObject request is encoded in the multipart/form-data format. In PostObject operations, parameters are passed as form fields in the request message body, whereas parameters are passed as HTTP request headers in PutObject operations. The x-oss-tagging header cannot be specified in PostObject requests.
Header Type Required Description
Content-Type String No The type and encoding method of the object to upload. Browsers determine how to read and encode the object based on the value of the parameter.

The form submitted by the PostObject operation must be encoded in the multipart/form-data format. For example, the Content-Type header must be in the multipart/form-data;boundary=xxxxxx format.

In this format, boundary is a boundary string that is randomly generated by the form. You do not need to specify the boundary string. If you use OSS SDKs to create a form, the SDKs also generate a random boundary string.

x-oss-object-acl String No Specifies the access control list (ACL) of the uploaded object in the request header.

If you specify x-oss-object-acl in both of the request header and the form field, the ACL specified in the form field takes precedence over the ACL specified in the request header. Default value: default.

Valid values:
  • default: The ACL of the uploaded object is the same as that of the bucket in which the object is stored.
  • private: The ACL of the uploaded object is private. Only the owner of the object and authorized users can read and write this object.
  • public-read: The ACL of the object is public read. Only the owner of the object and authorized users can write this object. Other users can only read the object. Exercise caution when you set the object ACL to this value.
  • public-read-write: The ACL of the object is public read and write. All users can read and write this object. Exercise caution when you set the object ACL to this value.

For more information about object ACLs, see ACL.

This API operation must also include common request headers such as Host and Date. For more information, see Common request headers.

Request elements

Notice The keys of all form fields cannot exceed 8 KB in size. The values of all form fields cannot exceed 2 MB in size.
Element Type Required Description
Cache-Control String No The web page caching behavior that is specified when the object is downloaded. For more information, visit RFC2616.

Default value: null

Content-Disposition String No The name of the object when the object is downloaded. For more information, visit RFC 2616.

Default value: null

Content-Encoding String No The content encoding type of the object when the object is downloaded. For more information, visit RFC 2616.

Default value: null

Expires String No The time period after which the response is considered expired. For more information, see RFC 2616.

Default value: null

OSSAccessKeyId String Conditional The AccessKey ID of the account used by the bucket owner.

Default value: null

Constraint: This form field is required when the bucket ACL is not public read and write or when the policy or Signature form field is specified in the request.

policy String Conditional Specifies the validity of the form fields in the request. A request that does not contain the policy form field is considered an anonymous request, and can be used to access only buckets whose ACLs are public read and write.

Default value: null

Constraint: This form field is required when the bucket ACL is not public read and write or when the OSSAccessKeyId or Signature form field is specified in the request.

Notice The form and the policy field must be UTF-8-encoded. The policy field must be Base64-encoded.
Signature String Conditional Specifies the signature information that is calculated based on the AccessKey secret and the policy form field. OSS checks the signature information to verify the validity of the PostObject request. For more information, see Appendix: Signature.

Default value: null

Constraint: This form field is required when the bucket ACL is not public read and write or when the OSSAccessKeyId or policy form field is specified in the request.

Note Form fields are case-insensitive, but their values are case-sensitive.
x-oss-server-side-encryption-key-id String No The ID of the customer master key (CMK) hosted in Key Management Service (KMS). This header is valid only when x-oss-server-side-encryption is set to KMS.
x-oss-content-type String No You can add the x-oss-content-type header in the message body of a PostObject request to specify the content type of the object to upload. The content type specified by the x-oss-content-type header takes precedence over the content type specified by the form field that is automatically generated by browsers.

The content type of the object is determined by three headers in the following priority in descending order: x-oss-content-type > Content-Type in the form field > Content-Type.

Default value: null

x-oss-forbid-overwrite String No Specifies whether the PostObject operation overwrites the existing object that has the same name.

When versioning is enabled or suspended for the bucket to which you want to upload the object, the x-oss-forbid-overwrite request header does not take effect. In this case, the object uploaded by using PostObject overwrites the existing object that has the same name.

  • If x-oss-forbid-overwrite is not specified or the value of x-oss-forbid-overwrite is set to false, the object uploaded by using PostObject overwrites the existing object that has the same name.
  • If the value of x-oss-forbid-overwrite is set to true, the object uploaded by using PostObject cannot overwrite the existing object that has the same name.

If you specify the x-oss-forbid-overwrite request header, the queries per second (QPS) performance of OSS may be degraded. If you want to use the x-oss-forbid-overwrite request header to perform a large number of operations (QPS greater than 1,000), submit a ticket.

x-oss-object-acl String No Specifies the ACL of the uploaded object in the form field. Default value: default. You can specify the ACL of the uploaded object in both the request header and the form field.

If you specify x-oss-object-acl in both of the request header and the form field, the ACL specified in the form field takes precedence over the ACL specified in the request header. Default value: default.

Valid values:
  • default: The ACL of the uploaded object is the same as that of the bucket in which the object is stored.
  • private: The ACL of the uploaded object is private. Only the owner of the object and authorized users can read and write this object.
  • public-read: The ACL of the object is public read. Only the owner of the object and authorized users can write this object. Other users can only read the object. Exercise caution when you set the object ACL to this value.
  • public-read-write: The ACL of the object is public read and write. All users can read and write this object. Exercise caution when you set the object ACL to this value.

For more information about object ACLs, see ACL.

x-oss-storage-class String No The storage class of the uploaded object.

If you specify this header when you upload an object, the storage class of the uploaded object is the specified header value regardless of the storage class of the bucket to which the object is uploaded. For example, if you set x-oss-storage-class to Standard when you upload an object to an IA bucket, the object is stored as a Standard object.

Valid values:
  • Standard
  • IA
  • Archive
  • ColdArchive

For more information about storage classes, see Overview.

key String Yes The name of the object to upload. If the object name includes a path such as destfolder/example.jpg, OSS automatically creates corresponding folders.

Default value: null

success_action_redirect String No The URL to which the client is redirected after the object is uploaded. If this form field is not specified, the returned result is specified by success_action_status. If the upload fails, OSS returns an error code, and the client is not redirected to a URL.

Default value: null

success_action_status String No The HTTP status code returned to the client when the success_action_redirect form field is not specified and the object is uploaded.

Default value: 204

Valid values: 200, 201, and 204.

  • If the value of this form field is set to 200 or 204, OSS returns an empty file and HTTP status code 200 or 204.
  • If the value of this form field is set to 201, OSS returns an XML file and HTTP status code 201.
  • If the value of this form field is not specified or set to an invalid value, OSS returns an empty file and HTTP status code 204.
x-oss-meta-* String No The metadata customized by the user.

Default value: null

If the request contains a form field prefixed with x-oss-meta-, the form field is considered the user metadata of the object. Example: x-oss-meta-location.
Note An object can have multiple parameters whose names contain the x-oss-meta- prefix. However, the total size of all user metadata of the object cannot exceed 8 KB.
x-oss-security-token String No The security token for temporary authorization. If a temporary Security Token Service (STS) security credential is used for the request, you must set this field to SecurityToken and set OSSAccessKeyId to the value of the AccessKey ID included in the security credential. You can calculate the signature for a request that uses a temporary AccessKey ID in the same way as you calculate the signature for a request that uses a constant AccessKey ID.

Default value: null

For more information about how to set up STS, see Use a temporary credential provided by STS to access OSS in OSS Developer Guide. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain a temporary access credential.

file String Yes The file or text content. Browsers automatically set the Content-Type header based on the file type and overwrite the content type specified by the user. You can upload only one object by using a PostObject request.

Default value: null

Notice This header must be the last field in the form.

Response headers

Header Type Description
x-oss-server-side-encryption String If x-oss-server-side-encryption is specified in the request, the response contains this header to indicate the algorithm used to encrypt the object at the server side.

The response headers involved in this API operation contain only common response headers. For more information, see Common response headers.

Response elements

Element Type Description
PostResponse Container The container that stores the result of the PostObject request.

Child nodes: Bucket, ETag, Key, and Location

Bucket String The name of the bucket.

Parent nodes: PostResponse

ETag String The entity tag (ETag) that is created when the object is generated. If an object is created by calling the PostObject operation, the ETag value is the object UUID, which can be used to check whether the object content is changed.

Parent nodes: PostResponse

Location String The URL used to access the uploaded object.

Parent nodes: PostResponse

Examples

  • Sample requests
    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"
    44CF9590006BF252F707
    --9431149156168
    Content-Disposition: form-data; name="policy"
    eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
    --9431149156168
    Content-Disposition: form-data; name="Signature"
    kZoYNv66bsmc10+dcGKw5x2PRrk=
    --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--
  • Sample responses
    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  
    Server: AliyunOSS

Error codes

Error code HTTP status code Description
FieldItemTooLong 400 The error message returned because the key or value of the form fields exceeds the limit.
InvalidArgument 400 The error message returned because one of the OSSAccessKeyId, policy, and Signature form fields is specified and the remaining two form fields are not specified in the request.
InvalidDigest 400 The error message returned because the Content-MD5 value of the request body that is calculated by OSS is not the same as the value of the Content-MD5 header field in the request.
EntityTooLarge 400 The error message returned because the total size of the PostObject request body exceeds 5 GB in size.
InvalidEncryptionAlgorithmError 400 The error message returned because the x-oss-server-side-encryption header field is set to a value other than AES256 and KMS. The x-oss-server-side-encryption header can be set to only AES256 or KMS.
IncorrectNumberOfFilesInPOSTRequest 400 The error message returned because the key form field is not specified in the request.
FileAlreadyExists 409 The error message returned because the request contains the x-oss-forbid-overwrite=true header and an existing object that has the same name already exists.
KmsServiceNotEnabled 403 The error message returned because x-oss-server-side-encryption is set to KMS but KMS is not activated in advance.
FileImmutable 409 The error message returned because the data you want to delete or modify is protected by a retention policy.

Appendix: Policy

The policy form field in a PostObject request is used to verify the validity of the request. The value of the policy form field is a JSON string encoded in UTF-8 and Base64. This value declares the conditions that a PostObject request must meet. The policy form field is optional when you upload objects to a bucket whose ACL is public read and write. However, we recommend that you specify this field to limit PostObject requests.

The following example shows the format of the policy field:

{ "expiration": "2014-12-01T12:00:00.000Z",
  "conditions": [
    {"bucket": "johnsmith" },
    ["starts-with", "$key", "user/eric/"]
  ]
}

The policy form field must contain the expiration and conditions parameters.

  • Expiration

    The expiration parameter specifies the expiration time of the request. The time complies to ISO 8601 and must be in GMT. For example, 2014-12-01T12:00:00.000Z indicates that the PostObject request must be sent before 12:00 on December 1, 2014.

  • Conditions
    The conditions parameter is a list that specifies the valid values of form fields in the PostObject request.
    Note The value of a form field is extended after OSS checks the policy. Therefore, the valid value of the form field set in policy is equivalent to the value of the form field before extension.

    The following table describes the conditions that can be configured in the policy field.

    Condition Description
    content-length-range The minimum and maximum sizes of the object to upload. This condition supports the content-length-range matching mode.
    Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires HTTP request headers. This condition supports the exact matching and starts-with matching modes.
    Notice To prevent malicious modification to the Content-Type header during form upload, we recommend that you include the Content-Type parameter in the policy form field.
    key The name of the object to upload. This condition supports the exact matching and starts-with matching modes.
    success_action_redirect The URL to which the client is redirected after the object is uploaded. This condition supports the exact matching and starts-with matching modes.
    success_action_status The HTTP status code to return after the object is uploaded if success_action_redirect is not specified. This condition supports the exact matching and starts-with matching modes.
    x-oss-meta-* The user metadata of the object to upload. This condition supports the exact matching and starts-with matching modes.

    If the PostObject request contains additional form fields, OSS adds these form fields to the conditions of the policy and checks their validity.

  • Condition matching modes
    Matching mode Description
    Exact matching The value of a form field must be exactly the same as the value that is declared in conditions. For example, if the value of the key form field must be a, the condition can be {"key": "a"} or ["eq", "$key", "a"].
    Starts With The value of a form field must start with the specified value. For example, if the value of the key form field must start with /user/user1, the condition must be ["starts-with", "$key", "/user/user1"].
    Specified object size Specifies the range of allowed object sizes. For example, if the acceptable object size is 1 to 10 bytes, the condition must be ["content-length-range", 1, 10].

In the policy form field of a PostObject request, the dollar sign ($) is used to indicate a variable. To describe the dollar sign ($), you must use the following escape character: \$. The following table describes the escape characters used in the JSON string of the policy form field in a PostObject request.

Escape characters Description
\/ Forward slash
\\ Backslash
\" Double quotation marks
\$ Dollar sign
\b Backspace
\f Form feed
\n Line feed
\r Carriage return
\t Horizontal tab
\uxxxx Unicode character

Appendix: Signature

To verify a PostObject request, you must include the policy and Signature form fields in the HTML form. The policy form field specifies the values that are acceptable in the request.

You can perform the following steps to calculate the value of the Signature form field:

  1. Create a UTF-8-encoded policy.
  2. Encode the policy in Base64. The result is the value of the policy form field, and this value is used as the string to sign.
  3. Use AccessKeySecret to sign the string by using the following method: Signature = base64(hmac-sha1(base64(policy), AccessKeySecret)).

Reference