PostObject

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

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

Request elements

Response headers

For more information about the common response headers contained in the response to a PostObject request, see Common response 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 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 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.

  Note The value of a form field is extended after OSS checks the policy. Therefore, the valid value of the form field set in policy is equivalent to the value of the form field before extension.

  The following table describes the conditions that can be configured in the policy field.

  Element	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 exact matching 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.
  key	The name of the object. This condition supports the exact matching 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 exact matching and starts-with matching modes.
  success_action_status	The HTTP status code to return after the object is uploaded if success_action_redirect is not specified. This condition supports the exact matching and starts-with matching modes.
  x-oss-meta-*	The user metadata of the object that you want to upload. This condition supports the exact matching and starts-with matching modes.

  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
  Exact matching	The value of a form field must be exactly the same as the value that is declared in 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 value. For example, if the value of the key form field must start 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.

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:

1. Create a policy encoded in UTF-8.
2. 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.
3. Use the AccessKey secret to sign the string in the following format: Signature = base64(hmac-sha1(base64(policy), AccessKeySecret)).

References

• For a demo of transferring 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 a demo on how to use OSS SDK for Java to call the PostObject operation, see Form upload.