OSS PostObject error and troubleshooting

Abstract: This article gives a detailed description on the message format of OSS PostObject, lists common problems and solutions and introduces common requests and implementations.
Introduction to PostObject
PostObject uploads files to OSS using form. In PostObject, message entity encodes through multipart/form-data. More details are shown in RFC 2388. In Put Object, parameters such as the header are requested to be transferred via HTTP, while in PostObject parameters are transferred as the form field of the body.
In PostObject, messages consist of header and body. \r\n--{boundary} is located between them and divides them apart. Body is composed of a series of form fields, with the following format: Content-Disposition: form-data; name="{key}"\r\n\r\n{value}\r\n--{boundary}. Common headers include Host, User-Agent, Content-Length, Content-Type, Content-MD5, etc.; “form field” fields include key, OSSAccessKeyId, Signature, Content-Disposition, object meta(x-oss-meta-*), x-oss-security-token and other HTTP Header(Cache-Control/Content-Type/Cache-Control/Content-Type/Content- Disposition/Content-Encoding/Expires/Content-Encoding/Expires), file, etc. File is the last in the form field.
PostObject Common errors
PostObject common errors are shown in the table below:


PutObject form field format
For the request format of PutObject, the following deserve special attention:
• Header must have Content-Type: multipart/form-data; boundary={boundary};
• \r\n--{boundary} is located between them and divides them apart.
• The form field format of Content-Disposition: form-data; name="{key}"\r\n\r\n{value}\r\n--{boundary};
• The form field file must be the last form field.
• The form field name must be case sensitive, that is policy, key, file, OSSAccessKeyId, OSSAccessKeyId, Content-Disposition;
• When a bucket is public-read-write, the following may not be specified: form field, OSSAccessKeyId, policy, Signature; when any of the following including OSSAccessKeyId, policy and Signature is specified, no matter whether a bucket is public-read-write or not, the other two must be specified.
The following is an example of PostObject:
POST / HTTP/1.1
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; zh-CN; rv:1.9.2.6)
Content-Type: multipart/form-data; boundary=9431149156168
Host: mingdi-hz.oss-cn-hangzhou.aliyuncs.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 5052

--9431149156168
Content-Disposition: form-data; name="key"

test-key
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"

attachment;filename=D:\img\1.png
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"

2NeL********j2Eb

Tips:
• In the above sample request, \r\n shows a new line, that is new lines. The following sample requests are similar:
If you have questions, please refer to the sample code:
C#
Java
Policy format in PutObject
In PutObject, the form field in request policy is used to verify the validity of the request, and it declares the PutObject request must meet the specified conditions. The qualifications are: After encoded with base64, UTF-8 JSON text is put into the form field policy. Policy must include expiration and conditions, of which conditions must have at least one item. The following is an example of policy before encoding.
{
    "expiration": "2018-01-01T12:00:00.000Z",
    "conditions": [
        ["content-length-range", 0, 104857600]
    ]
}

The expiration item specifies the requested overdue time, in the time format of ISO8601 GMT. For example, for 2018-01-01T12:00:00.000Z, the specified request must happen before 12:00am on January 1st, 2018.
The specified conditions supported by the post policy are as follows:


There are the following escape characters in Post Policy, and \ is used for escape.


PutObject signature
For verified Post request, it must include AccessKeyID, policy, Signature and other form fields. The calculation process of signature is as follows:
• Create a policy in UTF-8 encoding.
• Encode the policy with base64, and its value is to be filled in the policy form field. This value should be the character string to be signed.
• Sign the character string with AccessKeySecret (with hmac-sha1 at first, and then encoded with base64); signature method is the same for that of Header signature.
That is
Signature = base64(hmac-sha1(AccessKeySecret, base64(policy)))

Specify the calculated signature in the form field Signature, as shown below:
Content-Disposition: form-data; name="Signature"

{signature}
--9431149156168

If you have questions, please refer to the sample code:
C#
Java
Common questions
How to specify a key
The key is the object name, which is specified in the key in the form field, and an example is shown below:
Content-Disposition: form-data; name="key"

{key}
--9431149156168

How to specify object content
Specify object content through the file in the form file, and an example is shown below:
Content-Disposition: form-data; name="file"; filename="images.png"
Content-Type: image/png

{file-content}
--9431149156168

Notes:
• The file in the form field must be the last field in the form field. In other words, it must be placed after all form files;
• Filename is the name of the local file uploaded, not the object name.
How to specify content-type of the object type?
Content-type of the object type is specified in file in the form field, instead of the content-type in header and an example is shown below:
Content-Disposition: form-data; name="file"; filename="images.png"
Content-Type: image/png

{file-content}
--9431149156168

How to specify the verification content-md5 of object content?
Specify content-MD5 in the request header in PostObject. Please note the MD5 value is for the whole body, that is the MD5 of the all form fields. An example of a header request is shown below:
POST / HTTP/1.1
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; zh-CN; rv:1.9.2.6)
Content-Type: multipart/form-data; boundary=9431149156168
Content-MD5: tdqHe4hT/TuKb7Y4by+nJg==
Host: mingdi-hz.oss-cn-hangzhou.aliyuncs.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 5246

--9431149156168


How to specify signature?
For signature calculation method, please refer to the PutObject signature, and the signature is carried through the signature form field.
How to implement PostObject with STS Token of a temporary user
The usage of AccessKeyID and AccessKeySecret of a temporary user is the same with that of master user and sub-user. Token is carried into the x-oss-security-token of form field. The example is as follows:
Content-Disposition: form-data; name="Signature"

5L0+KaeugxYygfqWLJLoy0ehOmA=
--9431149156168
Content-Disposition: form-data; name="x-oss-security-token"

{Token}
--9431149156168

How to specify Content-Transfer-Encoding
Specify Content-Transfer-Encoding in the file of form field. An example of file of form field is as follows:
Content-Disposition: form-data; name="file"; filename="images.png"
Content-Type: image/png
Content-Transfer-Encoding: base64

{file-content}
--9431149156168

How to specify Object User Meta?
The Object User Meta is specified through the form field, and the example is as follows:
Content-Disposition: form-data; name="x-oss-meta-uuid"

{uuid}
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"

{tag}
--9431149156168

How to specify conditions, for example, expiration, Key, Bucket, size, header and so on.
Oss PostObject supports various specified conditions and can meet high security requirements. Specify conditions through the form field policy. Refer to the above policy format of PutObject for detailed description. The following is an example of policy:
{
    "expiration": "2018-01-01T12:00:00.000Z",
    "conditions": [
        ["eq", "$bucket", "md-hz"],
        ["starts-with", "$key", "md/conf/"],
        ["content-length-range", 0, 104857600]
    ]
}

For the above policy, PostObject operation by specified user: bucket must be md-hz，key must begin with md/conf/; the length of file to be uploaded must be less than 100M and the request time earlier than 2018-01-01T12:00:00.000Z.
How to specify HTTP Headers such as Cache-Control, Content-Type, Content-Disposition, Content-Encoding, and Expires?
Specify HTTP Headers such as Cache-Control, Content-Type, Content-Disposition, Content-Encoding, and Expires in the form field. The meanings of these HTTP Headers are shown in RFC2616. But Content-MD5 should be specified in Post Header.