Uploads an object to a bucket by using an HTML form.
Usage notes
To upload an object to a bucket by using an HTML form, you must have the
oss:PutObjectpermission. For more information, see Attach a custom policy to a RAM user.The size of the object that you want to upload by calling the PostObject operation cannot exceed 5 GB.
To initiate a PostObject request to a bucket, you must have the write permissions on the bucket. If the access control list (ACL) of the bucket to which you want to initiate a PostObject request is public-read-write, you do not need to sign the PostObject request. Otherwise, Object Storage Service (OSS) verifies the signature information in the request.
Unlike the PutObject operation, the PostObject operation 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 that you want to upload to the bucket in the URL. The request line is in the format of
POST / HTTP/1.1instead ofPOST /ObjectName HTTP/1.1.OSS does not check the signature information in headers or URLs in PostObject requests.
Versioning
If you initiate a PostObject request to a versioning-enabled bucket, OSS generates a unique version ID for the uploaded object and returns the version ID as the value of the x-oss-version-id header in the response.
If you initiate a PostObject request to a versioning-suspended bucket, OSS generates a version ID of null for the uploaded object and returns the version ID as the value of the x-oss-version-id header in the response. An object in a versioning-suspended bucket cannot have multiple versions whose ID is null.
Request syntax
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
The body of a PostObject request is encoded in the multipart/form-data format. In the PostObject operation, the parameters are passed as form fields in the request body, whereas the parameters are passed as HTTP request headers in the PutObject operation.
You cannot add tags to objects by passing the x-oss-tagging request header during the PostObject operation. You can call the PutObjectTagging operation to add tags to objects after the PostObject operation is complete.
Header | Type | Required | Description |
Content-Type | String | No | The type of the object that you want to upload and the encoding format of the web page. Browsers determine how to read and encode the object based on the value of the header. The form submitted in the PostObject operation must be encoded in the In this format, boundary is a boundary string that is randomly generated by the form. You do not need to specify a boundary string. If you use an OSS SDK to create a form, the SDK also generates a random boundary string. |
For more information about the common request headers in a PostObject request, such as Host and Date, see Common request headers.
Form elements
The following table describes the common form elements of both V1 and V4 signatures in PostObject requests. For more information about the unique form elements of a V4 signature in a PostObject request, see Form. For more information about the unique form elements of a V1 signature in a PostObject request, see Form.
The last form field must be file. No particular order is required for other form fields.
The key of a form field cannot exceed 8 KB, and the value of a form field cannot exceed 2 MB.
Element | Type | Required | Description |
Cache-Control | String | No | The caching behavior of the web page when the object is downloaded. For more information, see RFC 2616. By default, this element is left empty. |
Content-Disposition | String | No | The name of the object when the object is downloaded. For more information, see RFC 2616. By default, this element is left empty. |
Content-Encoding | String | No | The content encoding format of the object when the object is downloaded. For more information, see RFC 2616. By default, this element is left empty. |
Expires | String | No | The time when the cached data expires. For more information, see RFC 2616. By default, this element is left empty. |
policy | String | Conditional | The validity of the form fields in the request. A request that does not contain the policy form field is considered as an anonymous request and can be used only to access buckets whose ACLs are public-read-write. By default, this element is left empty. Condition: This form field is required if the bucket ACL is not public-read-write or the OSSAccessKeyId or Signature form field is specified in the request. Important The form and the policy form field must be UTF-8-encoded. The policy form field must also be Base64-encoded. |
x-oss-server-side-encryption-key-id | String | No | The ID of the customer master key (CMK) that is managed by Key Management Service (KMS). You can configure this element only when the x-oss-server-side-encryption element is set to KMS. |
x-oss-content-type | String | No | You can add the x-oss-content-type form field to the body of a PostObject request to specify the content type of the object that you want to upload. The content type specified by the x-oss-content-type form field takes precedence over the content type specified by the file form field that is automatically generated by browsers. The content types are prioritized in the following order: x-oss-content-type form field > Content-Type specified in the file form field that is automatically generated by browsers. By default, this element is left empty. |
x-oss-forbid-overwrite | String | No | Specifies whether the PostObject operation overwrites an existing object that has the same name. When versioning is enabled or suspended for the bucket to which you want to upload the object, x-oss-forbid-overwrite does not take effect. In this case, the object that is uploaded by calling the PostObject operation overwrites the existing object that has the same name.
If you specify x-oss-forbid-overwrite, the queries per second (QPS) performance of OSS may be degraded. If you want to use x-oss-forbid-overwrite to perform a large number of operations (QPS greater than 1,000), contact technical support. |
x-oss-object-acl | String | No | The ACL of the object that you want to upload. You can specify the ACL of the object that you want to upload in the form field. Valid values:
For more information, see Object ACLs. |
x-oss-storage-class | String | No | The storage class of the object. If you specify the x-oss-storage-class header when you upload an object, the storage class of the uploaded object is the specified value regardless of the storage class of the bucket to which the object is uploaded. For example, if you set the x-oss-storage-class header to Standard when you upload an object to an Infrequent Access (IA) bucket, the object is stored as a Standard object. Valid values:
For more information, see Overview. |
key | String | Yes | The name of the object that you want to upload. You do not need to encode the object name. If the object name contains a path, such as By default, this element is left empty. |
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 the success_action_status form field. If the upload fails, OSS returns an error code, and the client is not redirected to the URL. By default, this element is left empty. |
success_action_status | String | No | The HTTP status code that is returned to the client when the success_action_redirect form field is not specified and the object is uploaded. Valid values: 200, 201, and 204 (default).
|
x-oss-meta-* | String | No | The user metadata of the object. By default, this element is left empty. If the request contains a form field whose name contains the x-oss-meta- prefix, the form field is considered as the user metadata of the object. Example: Note An object can have multiple form fields 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 that is obtained from STS. This parameter is required only when you use a security token to construct a signature for the URL. You can call the AssumeRole operation of STS to obtain a security token. By default, this element is left empty. |
file | String | Yes | The file or text content. You do not need to encode the content. Browsers automatically add the Content-Type form field based on the file type and overwrite the content type specified in the Content-Type header. You can upload only one object by using a PostObject request. By default, this element is left empty. Important The last form field must be file. |
Response headers
Header | Type | Example | Description |
x-oss-server-side-encryption | String | KMS | The algorithm that is used to encrypt the object on the server side. If x-oss-server-side-encryption is specified in the request, the response contains this header. |
Content-MD5 | String | 1B2M2Y8AsgTpgAmY7PhC**** | The MD5 hash of the object. Important The MD5 hash of the object is obtained after the client uploads the object. The MD5 hash of the object is not the MD5 hash in the response body. |
x-oss-hash-crc64ecma | String | 316181249502703**** | The CRC-64 value of the object. |
x-oss-version-id | String | CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** | The version ID of the object. This header is returned only if you upload the object to a versioning-enabled bucket. |
For more information about the common response headers, such as Date and x-oss-request-id, in the response to a PostObject request, 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 uploaded. If an object is created by calling the PostObject operation, the ETag value is not the MD5 hash of the object content but a unique value calculated based on a specific rule. The ETag value of an object can be used to check whether the object content is modified. Parent nodes: PostResponse |
Location | String | The URL that is 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" 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--Sample success 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 x-oss-hash-crc64ecma: 316181249502703**** Content-MD5: 1B2M2Y8AsgTpgAmY7PhC**** Server: AliyunOSS
Error codes
Error code | HTTP status code | Description |
FieldItemTooLong | 400 | The size of the form field key exceeds 8 KB or the size of the form field value exceeds 2 MB. |
InvalidArgument | 400 | One of the OSSAccessKeyId, policy, and Signature form fields is specified but the other two form fields are not specified in the request regardless of whether the ACL of the bucket is public-read-write. |
InvalidDigest | 400 | The Content-MD5 value that is calculated by OSS based on the request body is different from the Content-MD5 value that is specified in the request header. |
EntityTooLarge | 400 | The total size of the PostObject request body exceeds 5 GB. |
InvalidEncryptionAlgorithmError | 400 | The x-oss-server-side-encryption header is set to a value other than AES256 or KMS. The x-oss-server-side-encryption header can be set only to AES256 or KMS. |
IncorrectNumberOfFilesInPOSTRequest | 400 | The PostObject request contains more than one file form field. A PostObject request can contain only one file form field. |
FileAlreadyExists | 409 | The request contains the x-oss-forbid-overwrite=true element, but an object that has the same name already exists. |
KmsServiceNotEnabled | 403 | The x-oss-server-side-encryption header is set to KMS but KMS is not activated in advance. |
FileImmutable | 409 | The data that you want to delete or modify is protected by a retention policy. |
POST policy
The policy form field in a PostObject request is used to specify the expiration time and conditions of the PostObject request that you initiate to upload an object by using an HTML form. The value of the policy form field is a JSON string that restricts a PostObject request by specifying multiple parameters, such as the bucket name to which you want to upload the object, the prefix in the object name, the validity period of the request, the allowed HTTP methods, and the object size and content.
POST signature
To ensure the validity and security of a PostObject request, you must include a signature in the PostObject request.
For more information about the V4 signature in a PostObject request, see (Recommended) Include a V4 signature in a PostObject request.
For more information about the V1 signature in a PostObject request, see Include a V1 signature in a PostObject request.
FAQ
What do I do if the "Your proposed upload exceeds the maximum allowed size." error message is returned?
Cause: The size of the uploaded object exceeds the size range specified in the content-length-range parameter.
Solution: Use the content-length-range parameter to specify the minimum and maximum allowed sizes of the uploaded object. Unit: bytes. For example, if the size of the object that you want to upload is 1 GB, you can set the content-length-range parameter to ["content-length-range", 1, 1073741824].
References
For more information about how to transfer data from a web client to OSS by using form upload, see Add signatures on the client by using JavaScript and upload data to OSS.
For more information about the common errors that occur when you call PostObject and corresponding solutions, see PostObject.