Uploads an object to a bucket by using an HTML form.
Usage notes
- The size of the object that is uploaded by calling the PostObject operation cannot exceed 5 GB.
- To initiate a PostObject request to a bucket, you must have 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 contained in the request.
- Compared with 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 in the URL. In other words, the request
line is in the format of
POST / HTTP/1.1
instead ofPOST /ObjectName HTTP/1.1
. - OSS does not check the signature information that is contained in headers or URLs in PostObject requests.
Versioning
If you initiate a PostObject request to a versioned bucket, 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 versioning-suspended bucket, OSS generates a version ID of 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 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 message 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 message body, whereas the parameters are passed as HTTP request headers in the PutObject operation.
- Tags cannot be added to objects by passing in x-oss-tagging request headers 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
parameter.
The form submitted by 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 the boundary string. If you use an OSS SDK to create a form, the SDK also generates a random boundary string. |
x-oss-object-acl | String | No | The ACL of the object that you want to upload.
If you specify x-oss-object-acl in both the request header and the form field, the ACL that is specified in the form field takes priority over the ACL that is specified in the request header. Default value: default. Valid values:
For more information about object ACLs, see Object ACL. |
For more information about the common request headers contained in PostObject requests such as Host and Date, see Common request headers.
Request elements
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.
This parameter is empty by default. |
Content-Disposition | String | No | The name of the object when the object is downloaded. For more information, see RFC 2616.
This parameter is empty by default. |
Content-Encoding | String | No | The content encoding format of the object when the object is downloaded. For more
information, see RFC 2616.
This parameter is empty by default. |
Expires | String | No | The expiration time. For more information, see RFC 2616.
This parameter is empty by default. |
OSSAccessKeyId | String | Conditional | The AccessKey ID of the account used by the bucket owner.
This parameter is empty by default. Constraint: This form field is required if the bucket ACL is not public read/write or the policy or Signature form field is specified in the request. |
policy | String | Conditional | 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 only be used to access
buckets whose ACLs are public read/write.
This parameter is empty by default. Constraint: 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. Notice The form and the policy form field must be UTF-8-encoded. The policy form field must
also be Base64-encoded.
|
Signature | String | Conditional | 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.
This parameter is empty by default. Constraint: This form field is required if the bucket ACL is not public read/write or the OSSAccessKeyId or policy form field is specified in the request. Note Form fields are not case-sensitive, but their values are case-sensitive.
|
x-oss-server-side-encryption-key-id | String | No | The ID of the customer master key (CMK) managed by Key Management Service (KMS). This form field 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 form field to the message 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 priority over the content
type specified by the file form field that is automatically generated by browsers.
This parameter is empty by default. |
x-oss-forbid-overwrite | String | No | Specifies whether the PostObject operation is allowed to overwrite the existing object
that has the same name as the uploaded object.
When versioning is enabled or suspended for the bucket to which you want to upload the object, the x-oss-forbid-overwrite header 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 the x-oss-forbid-overwrite header, the queries per second (QPS) performance of OSS may be degraded. If you want to use the x-oss-forbid-overwrite header 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 both the request header and the form field.
If you specify x-oss-object-acl in both the request header and the form field, the ACL that is specified in the form field takes priority over the ACL that is specified in the request header. Default value: default. Valid values:
For more information about object ACLs, see Object ACL. |
x-oss-storage-class | String | No | The storage class of the object that you want to upload.
If you specify this form field 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 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:
For more information about storage classes, 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 destfolder/example.jpg , OSS automatically creates the corresponding directory.
This parameter is empty by default. |
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.
This parameter is empty by default. |
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. Default value: 204.
Valid values: 200, 201, and 204.
|
x-oss-meta-* | String | No | The user metadata of the object that you want to upload.
This parameter is empty by default. 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 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 for temporary access authorization. If you obtain temporary access
credentials from Security Token Service (STS) and use the temporary access credentials
for the request, you must set this form field to the value of the security token and
set OSSAccessKeyId to the value of the AccessKey ID in the temporary access credentials.
You can calculate the signature for a request that uses a temporary AccessKey ID the
same way you calculate the signature for a request that uses an AccessKey ID.
This parameter is empty by default. For more information about how to use STS to authorize a user to access OSS, 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 temporary access credentials. For more information, see STS SDK overview. |
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.
This parameter is empty by default. Notice This form field 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 that is used to encrypt the object at the server side. |
For more information about the common response headers contained 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 node: 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 rule. The ETag value of
an object can be used to check whether the object content is modified.
Parent node: PostResponse |
Location | String | The URL that is used to access the uploaded object.
Parent node: 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 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 size of the key or value of a form field exceeds the limit. |
InvalidArgument | 400 | The error message returned because 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 error message returned because 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 error message returned because the total size of the PostObject request body exceeds 5 GB. |
InvalidEncryptionAlgorithmError | 400 | The error message returned because the x-oss-server-side-encryption request header is set to a valueother than AES256 or KMS. The x-oss-server-side-encryption request header can be set only to 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, but an existing object has the same name as the object that you want to upload. |
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 that 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 that is 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 an object to a bucket whose ACL is public read/write. However, we recommend that you specify this form field to limit PostObject requests.
The following example shows the format of the policy form 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 must follow the ISO 8601 standard 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 the form fields in the PostObject request.
The following table describes the conditions that can be configured in the policy form field.
Parameter Description content-length-range The minimum and maximum sizes of the object that you want to upload. Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires HTTP request headers. This condition supports the eq and starts-with matching modes. Notice To prevent malicious modifications to the Content-Type header during form upload, we recommend that you include the Content-Type parameter in the policy form field. You can use one of the following methods to configure the Content-Type parameter:- Add x-oss-content-type to the message body of a PostObject request to specify Content-Type.
Example:
Content-Type: image/jpeg
. For more information about the Content-Type values that are supported by OSS, see How do I configure the Content-Type header?. - Use the file form field to specify Content-Type. Example:
Content-Type: image/png
. For more information about the Content-Type values that are supported by OSS, see How do I configure the Content-Type header?.
The content type specified by the x-oss-content-type form field takes priority over the content type specified by the file form field.
key The name of the object. This condition supports the eq 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 eq and starts-with matching modes. success_action_status The HTTP status code that is returned after the object is uploaded if success_action_redirect is not specified. This condition supports the eq and starts-with matching modes. x-oss-meta-* The user metadata of the object that you want to upload. This condition supports the eq and starts-with matching modes. Note The policy field specifies form fields that must be contained in the PostObject request. If you specify ["eq", "$x-oss-meta-biedb", "biedb-test001"], you must add the form field in which the key is x-oss-meta-biedb and the value of the key is biedb-test001 to form fields of the request. Otherwise, the error message Invalid according to Policy: Policy Condition failed: ["eq", "$x-oss-meta-biedb", "biedb-test001"] is returned.If the PostObject request contains additional form fields, OSS adds these form fields to the conditions of the policy and checks their validity.
- Add x-oss-content-type to the message body of a PostObject request to specify Content-Type.
Example:
- 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 the conditions. For example, if the value of the key form field must be a in the format of {"key":"a"}, the condition must be ["eq", "$key", "a"]. Starts With The value of a form field must start with the specified prefix. For example, if the value of the key form field starts with user/user1, the condition must be ["starts-with", "$key", "user/user1"]. Specified object size The size of the object that you want to upload must be within 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 ($) indicates 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 character | Description |
---|---|
\/ | Forward slash |
\\ | Backslash |
\" | Double quotation marks |
\$ | Dollar sign |
\b | Backspace |
\f | Form feed |
\n | New line |
\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:
- Create a policy encoded in UTF-8.
- 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.
- Use the AccessKey secret to sign the string in the following format:
Signature = base64(hmac-sha1(base64(policy), AccessKeySecret))
.
References
- For more information about how to transfer data from the 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 how to use OSS SDK for Java to call the PostObject operation, see Form upload.