PostObject uses an HTML form to upload files to a specified bucket.
Based on the browser's use of HTTP POST to directly upload files to the Bucket of Object Storage Service, the latency can be reduced. The Post Object's message entity is encoded by multipart/form-data. In the Put Object operations , parameters are passed through the HTTP request header. In the Post operations, the parameters are passed as form fields in the message entity. This interface is compatible with S3, and only support the compatible S3 service domain name of OSS , refer to the server domain name.
Request Syntax
POST / HTTP/1.1 Host: <bucket>.s3.<region>.jdcloud-oss.com Content-Length: length Content-Type: multipart/form-data; boundary=your_boundary --your_boundary Content-Disposition: form-data; name="key" object_key --your_boundary Content-Disposition: form-data; name="X-Amz-Credential" <your accessKey>/<date>/<region>/s3/aws4_request --your_boundary Content-Disposition: form-data; name="X-Amz-Algorithm" AWS4-HMAC-SHA256 --your_boundary Content-Disposition: form-data; name="X-Amz-Date" date --your_boundary Content-Disposition: form-data; name="Policy" base64Encoded_policy --your_boundary Content-Disposition: form-data; name="X-Amz-Signature" signature --your_boundary Content-Disposition: form-data; name="file"; filename=<filename> Content-Type: content_type file_content --your_boundary Content-Disposition: form-data; name="submit" Upload to OSS --your_boundary--
Name | Description | Required |
---|---|---|
Content-Type | Standard http header; but the type must be multipart/form-data, and specify the boundary For example: Content-Type: multipart/form-data; boundary=your_boundary |
Yes |
Name | Type | Description | Required |
---|---|---|---|
Cache-Control | String | Refer to PutObject for standard http header and it is recorded as the object metadata information, Default Value: None |
No |
Content-Type | String | Refer to PutObject for standard http header and it is recorded as the object metadata information, Default Value: None |
No |
Content-Disposition | String | Refer to PutObject for standard http header and it is recorded as the object metadata information, Default Value: None |
No |
Content-Encoding | String | Refer to PutObject for standard http header and it is recorded as the object metadata information, Default Value: None |
No |
Expires | String | Refer to PutObject for standard http header and it is recorded as the object metadata information, Default Value: None |
No |
key | String | Uploaded Object Name.Support variable ${filename} (only support variable ${filename}); for example, specify the key as bucket/${filename}, at this moment you upload an image named test.jpg, then the key saved by oss is bucket/test.jpg Default Value: None |
Yes |
policy | String | Used to limit this request.t is JSON encoded by UTF-8 and Base64 Default Value: None |
Required for requests requiring signatures |
success_action_redirect | String | Client jump address when upload succeedsIf the success_action_redirect is not specified, or it is specified but OSS does not resolve successfully, then OSS will return according to the success_action_status settings (return 204 by default)If the file upload fails, then OSS will return the error without jumping Default Value: None |
No |
success_action_status | String | The status code returned when the file upload succeeds is specified, provided that success_action_redirect is not specified.If the value is 200 or 204, the content that OSS returns will be blank.If the value is 201, the status code returned will be 201, and http body content will be relevant object information in xml format Default Value: 204 Valid Value: 200, 201, 204 (by default) |
No |
x-amz-algorithm | String | Signature algorithm, the value is AWS4-HMAC-SHA256 Default Value: None |
Required for requests requiring signatures |
x-amz-credential | String | If S3 API is used, then the format is <your-access-key-id>/<date>/<region>/s3/aws4_request. Example:AKIAIOSFODNN7EXAMPLEYYYYYYYYYYYY/20180601/cn-north-1/s3/aws4_request Default Value: None |
Required for requests requiring signatures |
x-amz-date | String | ISO8601 time format, such as: 20180601T000000Z.The value of x-amz-date attribute in the policy should be the same as it Note that the time of computing signature at this moment is 20180601 Default Value: None |
Required for requests requiring signatures |
x-amz-signature | String | String to signature Default Value: None |
Required for requests requiring signatures |
x-amz-storage-class | String | Object Storage Type Default Value: STANDARD (Standard Storage) Valid Value: STANDARD (Standard Storage), GLACIER(Archive Storage), REDUCED_REDUNDANCY (Reduced Redundancy Storage) and STANDARD_IA (Infrequent Access Storage) |
No |
file | String | File or Text Content .The attribute must be placed at the end of the form, otherwise the attributes after the file will be ignored. Don't support multiple files to be uploaded at the same time Default Value: None |
Yes |
When and only when the return code is 201, the following will be returned.
Name | Type | Description |
---|---|---|
PostResponse | Container | Bucket name stored by the object Child Node: Bucket, Key, Etag |
+Bucket | String | Bucket name stored by the object Parent Node: PostResponse |
+Key | String | object name Parent Node: PostResponse |
+Etag | String | Created when each Object is generated, the Object created by the Post request can be used to check whether the Object content has changed Parent Node: PostResponse |
+Location | String | Newly created Object URL, note: The key in the location will conduct urlencode Parent Node: PostResponse |
1.Performing a Post operation requires write permission to the bucket. If the bucket is public-read-write, the signature information may not be uploaded. Otherwise, signature verification is required to be performed on the operation. If the post form does not provide sufficient attributes required by the signature request, then this request will be deemed as an anonymous request.
2.If the POST request includes Header signature information or URL signature information, OSS will not check them. (Namely, the PostObject in the Form will prevail).
3.The form lacks of necessary attributes. For instance, lack of key, return 400 InvalidArgument; lack of file, return 400 IncorrectNumberOfFilesInPostRequest.
4.Capital and lowercase letters not distinguished for form attributes, e.g.: x-amz-signature and X-Amz-Signature are of equal value, but the value of form field has case sensitivity.
5.The form size limit is 20K (excluding file size), if not, return 400, MaxPostPreDataLengthExceeded.
6.The total length of the body requested by Post is not allowed to exceed 5G. If the file length is too large, it will return an error code: EntityTooLarge, if you want to upload a file larger than 5G, it is recommended to use multipart upload.
7.If the key value specifies a variable (only support variable ${filename}), the uploaded file name now includes a path, namely "/" or "", then ${filename} will be replaced by the part behind the last one "/" or "". E.g.: If the uploaded file name is C:\Program Files\directory1\file.txt, then the ${filename} in the key attribute will be replaced to file.txt
8.Attributes cannot be identified by OSS will be neglected, but attributes in the form are also required to be limited in the policy, if not, it will return 403 AccessDenied.
9.If Content-MD5 is specified in user form field (MD5 in request header will not be verified), OSS will compute the Content-MD5 of the body and check the consistency; if there is inconsistency, it will return BadDigest error code.
10.If the form includes success_action_redirect, the jumped target address is url + ?bucket=&key=&ETag=etag. This query part will conduct urlencode.
11.The form and policy must use UTF-8 to encode. The policy is a piece of JSON encoded by using UTF-8 and Base-64.
12.Since there is no version management currently, if a user uploads a file with the same name, it will be replaced.
POST / HTTP/1.1 Host: testBucket.s3.cn-north-1.jdcloud-oss.com Content-Length: length Content-Type: multipart/form-data; boundary=123456789000 --123456789000 Content-Disposition: form-data; name="key" test.txt --123456789000 Content-Disposition: form-data; name="X-Amz-Credential" AKIAIOSFODNN7EXAMPLEYYYYYYYYYYYY/20180601/cn-north-1/s3/aws4_request --123456789000 Content-Disposition: form-data; name="X-Amz-Algorithm" AWS4-HMAC-SHA256 --123456789000 Content-Disposition: form-data; name="X-Amz-Date" 20180601T000000Z --123456789000 Content-Disposition: form-data; name="Policy" eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJ5b3VoZS10ZXN0In0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJwb3N0LyJdLHsic3VjY2Vzc19hY3Rpb25fc3RhdHVzIjoiMjAxIn0seyJ4LWFtei1jcmVkZW50aWFsIjoiQUtJQUkyTUtVS0ZFUjRMNEJaNFEvMjAxODA3MTUvdXMtd2VzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotZGF0ZSI6IjIwMTgwNzE1VDAzNTcyN1oifSxbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwiMCIsIjkiXV0sImV4cGlyYXRpb24iOiIyMDE4LTA3LTMwVDEyOjAwOjAwLjAwMFoifQ== --123456789000 Content-Disposition: form-data; name="X-Amz-Signature" 1b336b54bb3c7800f2137ee5b2d5d7ee676376800d388a17004ec2bee607897a --123456789000 Content-Disposition: form-data; name="file"; filename="d:/ test.txt" Content-Type: text/plain wrwe --123456789000 Content-Disposition: form-data; name="submit" Upload to OSS --123456789000--
<?xml version="1.0" encoding="utf-8"?> <PostResponse> <Bucket>testBucket</Bucket> <Key>test.txt</Key> <ETag>"1b6be8aac90401fe1cd5e4dd1c4b138f"</ETag> <Location>http://s3.cn-north-1.jdcloud-oss.com/testBucket/test.txt</Location> </PostResponse>
The Policy form field of the Post request is used to verify the validity of the request, which may control the post request permission. The policy is a piece of JSON format text encoded by using UTF-8 and Base-64, stating the conditions that Post request must meet. Although the post form field is an option when the public-read-write bucket is uploaded, it is strongly recommended that you should use this field to limit the Post request. Policy Example:
{ "expiration": "2018-12-01T12:00:00.000Z", "conditions": {"bucket": "myBucketName" }, ["starts-with", "$key", "user/yuyu/"], ] }
Post policy must include expiration and conditions.
The expiration time of policy requested by post, the time format is ISO8601 GMT. For example: "2018-06-01T12:00:00.000Z", means the specified Post request must occur before June 1, 2018 12:00.
Conditions are a list, which can be used to specify the legal value of form field of the specified Post request. See the following form for the conditions supported in the Policy:
Name | Description |
---|---|
bucket | Bucket Names Uploaded by the Object Support the matching types of exact matching |
content-length-range | The maximum length and minimum length limits of the uploaded content Support the matching types of content-length-range |
Cache-Control Content-Type Content-Disposition Content-Encoding Expires |
Standard http header, refer to the PutObject. Support the matching types of exact matching and starts-with |
key | Name of the Uploaded Object Support the matching types of exact matching and starts-with |
success_action_redirect | Url jump address when upload succeeds Support the matching types of exact matching and starts-with |
success_action_status | The status code returned when the file upload succeeds but the success_action_redirect is not specified Support the matching types of exact matching |
x-amz-algorithm | Signature algorithm, the value is AWS4-HMAC-SHA256 code Support the matching types of exact matching |
x-amz-credential | If S3 API is used, then the format is ///s3/aws4_requestExample: AKIAIOSFODNN7EXAMPLEYYYYYYYYYYYY/20180601/cn-north-1/s3/aws4_request Support the matching types of exact matching |
x-amz-date | ISO8601 time format, such as: 20180601T000000Z Note that the time of computing signature at this moment is 20180601, Support the matching types of exact matching |
x-amz-storage-class | The storage type of Object, the default value is "STANDARD" (standard storage). Support two storage types, "STANDARD" (standard storage) and "REDUCED_REDUNDANCY" (reduced redundancy storage) Support the matching types of exact matching |
Matching Method | Description |
---|---|
Exact Matching | The form attribute must exactly match the value For example, {"bucket": "example-bucket"}, then it is required that the files can only be uploaded to the bucket named "example-bucket". Another writing way: [ "eq", "$bucket", "example-bucket" ] |
Starts With | The prefix of the form attribute must be the specified value e.g. ["starts-with", "$key", "OSS/"] specifies that the name of the uploaded file must have the OSS/ prefix |
Match An Arbitrary Value | Used to allow to specify the value of form attribute to be any content, use Starts With and assign it as empty ("") For example: ["starts-with", "$success_action_redirect", ""] allows the success_action_redirect in the form to be any value |
Specified File Size | Only support content-length, the maximum and minimum values can be separated by commas For example, ["content-length-range", 1048579, 10485760], limits the uploaded content size to be 1M~10M |
Because $ represents variable in the Post policy, the escape character $ needs to be used when describing $. Besides, JSON will escape some characters. The following form describes the characters that need to be escaped in the Post policy.
Escape Character | Description |
---|---|
\/ | Slash |
|Backslash | |
\$ | USD Sign |
\b | Space |
\f | Form Feed |
\n | Line Feed |
\r | Carriage Return |
\t | Horizontal Tab |
\uxxxx | Unicode Character |
The expiration and condition elements in the policy are required. Otherwise, the policy verification will fail and be deemed as an anonymous request.
In addition to x-amz-signature, file, policy and x-ignore-*, other attributes in the uploaded form must be limited in the policy. Otherwise it will be deemed as anonymous access.
If the policy format does not conform to the specification, such as entering an invalid Condition Match Type, it will be processed as an anonymous request.
Policy conditions (except content-length-range) verification failing or the corresponding attributes not found in the form will be both deemed as anonymous access; and EntityTooLarge, EntityTooSmall will return if the content-length-range verification fails.
For Post requests that require verification, the HTML form must contain the policy and signature (X-Amz-Signature) information. The values in the policy control request are allowed. The specific processes of calculating signature:
Create a policy encoded by UTF-8.
Encode the policy with base64, and use the value as the StringToSign field of signature calculation.
Use the HMAC-SHA256 algorithm to conduct signature calculation to the character strings and other signature-required information acquired in step 2, such as AccessKeySecret.
Encode the final result in hexadecimal.
The following example provides how to use POST policy and the form to complete uploading a file to OSS.
{ "expiration": "<expiration> example:2018-08-30T12:00:00.000Z", "conditions": [ {"bucket": "<your bucket>"}, ["starts-with", "$key", "<your objectKey prefix>"], {"Content-Type": "<type> example:image/jpeg"}, {"X-Amz-Credential": "<your accessKey>/<date> example:20180709/<region>/s3/aws4_request"}, {"X-Amz-Algorithm": "AWS4-HMAC-SHA256"}, {"X-Amz-Date": "<date> example:20180709T053727Z"} ] }
<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <form action="http://<your bucket>.s3.<region>.jdcloud-oss.com/" method="post" enctype="multipart/form-data"> // Key to upload: <input type="input" name="key" value="<your objectKey>" /> Content-Type: <input type="input" name="Content-Type" value="<type> example:image/jpeg" /> <input type="text" name="X-Amz-Credential" value="<your accessKey>/<date> example:20180709/<region>/s3/aws4_request" /> <input type="text" name="X-Amz-Algorithm" value="AWS4-HMAC-SHA256" /> <input type="text" name="X-Amz-Date" value="<date> example:20180709T053727Z" /> <input type="hidden" name="Policy" value='<base64 policy>' /> <input type="hidden" name="X-Amz-Signature" value="<signature>" /> // File: <input type="file" name="file" /> <!-- The elements after this will be ignored --> <input type="submit" name="submit" value="Upload to JDcloud OSS" /> </form> </html>
Note: You need to replace the valid bucket names; dates, credential, policy, and signature can successfully upload files to OSS.