Post object

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

Form Field

Response

Response Elements

When and only when the return code is 201, the following will be returned.

Detail Analysis:

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.

Example:

Request:

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

Response:

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

Post Policy

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.

expiration

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

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:

Conditions Matching Method

Escape Character

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.

Detailed Analysis of Post Policy

1. The expiration and condition elements in the policy are required. Otherwise, the policy verification will fail and be deemed as an anonymous request.

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

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

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

Calculate Signature

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:

1. Create a policy encoded by UTF-8.

2. Encode the policy with base64, and use the value as the StringToSign field of signature calculation.

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

4. Encode the final result in hexadecimal.

Form Upload Example:

The following example provides how to use POST policy and the form to complete uploading a file to OSS.

Policy Example

{
	"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.