Object Storage Service:PostObject

Usage notes

• To upload an object to a bucket by using an HTML form, you must have the oss:PutObject permission. For more information, see Common examples of RAM policies.

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

• Unlike the PutObject operation, the PostObject operation calculates the signature based on the AccessKey secret and 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.1 instead of POST /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 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 can have only one version 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

For more information about the common request headers contained in PostObject requests, such as Host and Date, see Common HTTP headers.

Request elements

Response headers

For more information about the common response headers contained in the response to a PostObject request, see Common HTTP headers.

Response elements

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  
  Server: AliyunOSS

Error codes

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 specifies the conditions that must be matched for a PostObject request. 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.

Example:

{
  "expiration": "2014-12-01T12:00:00.000Z",
  "conditions": [
    {"bucket": "johnsmith" },    
    ["content-length-range", 1, 10],
    ["eq", "$success_action_status", "201"],
    ["starts-with", "$key", "user/eric/"],
    ["in", "$content-type", ["image/jpg", "image/png"]],
    ["not-in", "$cache-control", ["no-cache"]]
  ]
}

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

  Parameter	Description	Matching mode
  bucket	The name of the bucket.	bucket
  content-length-range	The minimum and maximum sizes of the object that you want to upload. Unit: bytes.	content-length-range
  Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires	HTTP request headers. Important To prevent malicious modifications to the Content-Type header during form upload, we recommend that you specify the Content-Type header in the policy form field. You can use one of the following methods to specify the Content-Type header: Add the x-oss-content-type element to the message body of a PostObject request to specify the Content-Type header. Example: Content-Type: image/jpeg. For more information about the values of the Content-Type header 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 values of the Content-Type header 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 precedence over the content type specified by the file form field.	eq, starts-with, in, and not-in
  key	The name of the object.	eq, starts-with, in, and not-in
  success_action_redirect	The URL to which the client is redirected after the object is uploaded.	eq, starts-with, in, and not-in
  success_action_status	The HTTP status code to return after the object is uploaded if success_action_redirect is not specified.	eq, starts-with, in, and not-in
  x-oss-meta-*	The user metadata of the object that you want to upload. Note The policy field specifies the form fields that must be contained in the PostObject request. If you specify ["eq", "$x-oss-meta-biedb", "biedb-test001"], you must add the key form field x-oss-meta-biedb whose value is biedb-test001 to the form field. Otherwise, the Invalid according to Policy: Policy Condition failed: ["eq", "$x-oss-meta-biedb", "biedb-test001"] error is reported.	eq, starts-with, in, and not-in

  If the PostObject request contains additional form fields, OSS adds these form fields to the conditions of the policy and checks their validity.

• Condition matching modes

  Matching mode	Description
  content-length-range	The size of the object that you want to upload must be within the range of supported object sizes. For example, if the supported object size is 1 to 10 bytes, the condition must be ["content-length-range", 1, 10].
  eq	The value of a form field must be exactly the same as the value that is specified in the conditions. For example, if the value of the key form field is 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"].
  in	The elements that you want to include in the verification must be specified in the in condition string. For example, if you want to verify whether JPG and PNG images can be uploaded in a PostObject request, the condition must be ["in", "$content-type", ["image/jpg", "image/png"]].
  not-in	The elements that you want to exclude from the PostObject request must be specified in the not-in condition string. For example, if you want to specify an object caching behavior and exclude no-cache, the condition must be ["not-in", "$cache-control", ["no-cache"]].

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.

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 supported in the request.

You can perform the following steps to calculate the value of the Signature form field:

1. Create a UTF-8-encoded policy.

2. Encode the policy in Base64. The result is the value of the policy form field, and the value is used as the string to be signed.

3. Use the AccessKey secret to sign the string in the following format: Signature = base64(hmac-sha1(base64(policy), AccessKeySecret)).

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 is out of the size range specified for the content-length-range parameter.

• Solution: Add the content-length-range parameter to specify the minimum and maximum 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 of and solutions to the PostObject operation, see PostObject.