Post Object

Last Updated: May 09, 2017

The Post Object operation is used to upload a file to a specified bucket using the HTML form. As a substitute of Put Object, Post Object makes it possible to upload files to a bucket based on the browser. The message body of Post Object is encoded using multipart/form-data. In the Put Object operation, parameters are transferred through the HTTP request header. In the Post Object operation, parameters are transferred as the form fields in the message body.

Post Object

Request syntax

  1. POST / HTTP/1.1
  2. Host: BucketName.oss-cn-hangzhou.aliyuncs.com
  3. User-Agent: browser_data
  4. Content-LengthContentLength
  5. Content-Type: multipart/form-data; boundary=9431149156168
  6. --9431149156168
  7. Content-Disposition: form-data; name="key"
  8. key
  9. --9431149156168
  10. Content-Disposition: form-data; name="success_action_redirect"
  11. success_redirect
  12. --9431149156168
  13. Content-Disposition: form-data; name="Content-Disposition"
  14. attachment;filename=oss_download.jpg
  15. --9431149156168
  16. Content-Disposition: form-data; name="x-oss-meta-uuid"
  17. myuuid
  18. --9431149156168
  19. Content-Disposition: form-data; name="x-oss-meta-tag"
  20. mytag
  21. --9431149156168
  22. Content-Disposition: form-data; name="OSSAccessKeyId"
  23. access-key-id
  24. --9431149156168
  25. Content-Disposition: form-data; name="policy"
  26. encoded_policy
  27. --9431149156168
  28. Content-Disposition: form-data; name="Signature"
  29. signature
  30. --9431149156168
  31. Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
  32. Content-Type: image/jpeg
  33. file_content
  34. --9431149156168
  35. Content-Disposition: form-data; name="submit"
  36. Upload to OSS
  37. --9431149156168--

Form fields

Name Description Required or Optional
OSSAccessKeyId Specify the access key ID of the bucket owner.
Type: string
Default value: none
Restriction: This form field is required when the bucket does not allow public-read-write, or when the Policy (or Signature) form field is provided.
Conditional
policy Specify validity of the form fields in the request. A request that does not contain the Policy form field is treated as an anonymous request, and can only access buckets that allow public-read-write. For details, refer to 5.7.4.1 Post Policy.
Type: string
Default value: none
Restriction: This form field is required when the bucket does not allow public-read-write, or when the OSSAccessKeyId (or Signature) form field is provided.
Conditional
Signature Specify the signature information that is computed based on the Access Key Secret and Policy. The OSS checks the signature information to verify validity of the Post Object request. For details, refer to 5.7.4.2 Post Signature.
Type: string
Default value: none
Restriction: This form field is required when the bucket does not allow public-read-write, or when the OSSAccessKeyId (or Policy) form field is provided.
Conditional
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires REST request headers. For details, refer to the related descriptions in Put Object.
Type: string
Default value: none
Optional
file Specify the file or text content. It must be the last field in the form. The browser automatically sets Content-Type based on the file type, and overwrites the user setting. The OSS can only upload one file at a time.
Type: string
Default value: none
Required
key Specify the object name of the uploaded file. If the name of the uploaded file needs to be used as the object name, use the ${filename} variable. For example, if the user uploads the b.jpg file and the Key field is set to /user/a/${filename}, the final object name is /user/a/b.jpg. If the file name contains the path, remove the path from the file name. For example, if the user uploads the a/b/c/b.jpg file, use the file name b.jpg. If the Key field is set to /user/a/${filename}, the final object name is /user/a/b.jpg.
Type: string
Default value: none
Required
success_action_redirect Specify the URL to which the client is redirected after successful upload. If this form field is not specified, the returned result is specified by success_action_status. If upload fails, the OSS will return an error code, and the client will not be redirected to any URL.
Type: string
Default value: none
Optional
success_action_status Specify the status code returned to the client after the previous successful upload if success_action_redirect is not specified. Valid values include 200, 201, and 204 (default). If this field is set to 200 or 204, the OSS returns an empty file and a corresponding status code. If this field is set to 201, the OSS returns an XML file and the 201 status code. If this field is not specified or set to an invalid value, the OSS returns an empty file and the 204 status code.
Type: string
Default value: none
Optional
x-oss-meta-* Specify the user meta value set by the user. The OSS does not check or use this value.
Type: string
Default value: none
Optional
x-oss-server-side-encryption Specify the server-side encryption algorithm when the OSS creates an object.
Type: string
Valid value: AES256
Optional
x-oss-object-acl Specify the access permission when the OSS creates an object.
Type: string
Valid values: public-read, private, and public-read-write
Optional
x-oss-security-token If STS temporary authorization is used for this access, you need to specify the item to be the SecurityToken value. At the same time, OSSAccessKeyId should use a paired temporary AccessKeyId. The signature calculation is consistent with the general AccessKeyId signature.
Type: string
Default value: none
Optional

Response header

Name Description
x-oss-server-side-encryption If x-oss-server-side-encryption is specified in the request, the response contains this header, which indicates the encryption algorithm used.
Type: string

Response elements

Name Description
PostResponse Specify the container that saves the result of the Post Object request.
Type: container
Sub-nodes: Bucket, ETag, Key and Location
Bucket Specify the bucket name.
Type: string
Parent node: PostResponse
ETag Specify the entity tag (ETag) that is created when an object is generated. For an object created by Post Object, the ETag value is the UUID of the object, and can be used to check whether the content of the object has changed.
Type: string
Parent node: PostResponse
Location Specify the URL of the newly created object.
Type: string
Parent node: PostResponse

Detail analysis

  • To perform the Post Object operation, you must have the permission to write the bucket. If the bucket allows public-read-write, you can choose not to upload the signature information; otherwise, signature verification must be performed on the Post Object operation. Unlike Put Object, Post Object uses AccessKeySecret to compute the signature for the policy. The computed signature string is used as the value of the Signature form field. The OSS checks this value to verify validity of the signature.
  • No matter whether the bucket allows public-read-write, once any one of the OSSAccessKeyId, Policy, and Signature form fields is uploaded, the remaining two form fields are required. If the remaining two form fields are missing, the OSS will return the error code: InvalidArgument.
  • Form encoding submitted by the Post Object operation must be “multipart/form-data”. That is, Content-Type in the header must be in the multipart/form-data; boundary=xxxxxx format, where boundary is the boundary string.
  • The URL of the submitted form can be the domain name of the bucket. It is not necessary to specify the object in the URL. That is, the request line is POST / HTTP/1.1, and cannot be written as POST /ObjectName HTTP/1.1.
  • The policy specifies the valid values of form fields in the Post Object request. The OSS checks validity of the request based on the policy. If the request is invalid, the OSS will return the error code: AccessDenied. When checking validity of the policy, the OSS does not check irrelevant form fields in the policy.
  • The form and policy must be encoded with UTF-8. The policy is a JSON text encoded with UTF-8 and Base64.
  • The Post Object request can contain extra form fields. The OSS checks validity of these form fields based on the policy.
  • If you have uploaded the Content-MD5 request header, the OSS will calculate the body’s Content-MD5 and check if the two are consistent. If the two are different, the error code InvalidDigest will be returned.
  • If the Post Object request contains the Header signature or URL signature, the OSS does not check these signatures.
  • If the Put Object request carries a form field prefixed with x-oss-meta-,the form field is treated as the user meta, for example, x-oss-meta-location. A single object can have multiple similar parameters, but the total size of all user meta cannot exceed 8 KB.
  • The total length of the body in the Post Object request cannot exceed 5 GB. When the file length is too large, the system will return the error code: EntityTooLarge.
  • If the x-oss-server-side-encryption header is specified when you upload an object, the value of this header must be set to AES256. Otherwise, the system will return 400 and the error code: InvalidEncryptionAlgorithmError. After this header is specified, the response header will also contain this header, and the OSS stores the encryption algorithm of the uploaded object. When this object is downloaded, the response header will contain x-oss-server-side-encryption, the value of which is set to the encryption algorithm of this object.
  • Form fields are not case-sensitive, but their values are case-sensitive.

Example

Request example:

  1. POST / HTTP/1.1
  2. Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  3. Content-Length: 344606
  4. Content-Type: multipart/form-data; boundary=9431149156168
  5. --9431149156168
  6. Content-Disposition: form-data; name="key"
  7. /user/a/${filename}
  8. --9431149156168
  9. Content-Disposition: form-data; name="success_action_status"
  10. 200
  11. --9431149156168
  12. Content-Disposition: form-data; name="Content-Disposition"
  13. content_disposition
  14. --9431149156168
  15. Content-Disposition: form-data; name="x-oss-meta-uuid"
  16. uuid
  17. --9431149156168
  18. Content-Disposition: form-data; name="x-oss-meta-tag"
  19. metadata
  20. --9431149156168
  21. Content-Disposition: form-data; name="OSSAccessKeyId"
  22. 44CF9590006BF252F707
  23. --9431149156168
  24. Content-Disposition: form-data; name="policy"
  25. eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
  26. --9431149156168
  27. Content-Disposition: form-data; name="Signature"
  28. kZoYNv66bsmc10+dcGKw5x2PRrk=
  29. --9431149156168
  30. Content-Disposition: form-data; name="file"; filename="MyFilename.txt"
  31. Content-Type: text/plain
  32. abcdefg
  33. --9431149156168
  34. Content-Disposition: form-data; name="submit"
  35. Upload to OSS
  36. --9431149156168--

Response example:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e
  3. Date: Fri, 24 Feb 2014 06:03:28 GMT
  4. ETag: 5B3C1A2E053D763E1B002CC607C5A0FE
  5. Connection: keep-alive
  6. Content-Length: 0
  7. Server AliyunOSS

Post Policy

The policy form field requested by POST is used to verify the validity of the request. The policy is a JSON text encoded with UTF-8 and Base64. It states the conditions that a Post Object request must meet. Although the post form field is optional for uploading public-read-write buckets, we strongly suggest using this field to limit POST requests.

Policy example

  1. { "expiration": "2014-12-01T12:00:00.000Z",
  2. "conditions": [
  3. {"bucket": "johnsmith" },
  4. ["starts-with", "$key", "user/eric/"]
  5. ]
  6. }

In the Post Object request, the policy must contain expiration and conditions.

Expiration

Expiration specifies the expiration time of the policy, which is expressed in ISO8601 GMT. For example, “2014-12-01T12:00:00.000Z” means that the Post Object request must be sent before 12:00 on December 1, 2014.

Conditions

Conditions is a list that specifies the valid values of form fields in the Post Object request.Note: The value of a form field is extended after the OSS checks the policy. Therefore, the valid value of the form field set in the policy is equivalent to the value of the form field before extension. For example, if the key form field is set to user/user1/${filename} and the file name of the user is a.txt, the policy form field in the Post Object request must be set to [“eq”,”$key”,”user/user1/\${filename}”], instead of [“eq”,”$key”,”$key”,”user/user1/a.txt].The following table lists the conditions supported by the policy:

Name Description
content-length-range Specify the acceptable maximum and minimum sizes of the uploaded file. This condition supports the content-length-range match mode.
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires HTTP request headers. This condition supports the exact match and starts-with match modes.
key Specify the object name of the uploaded file. This condition supports the exact match and starts-with match modes.
success_action_redirect Specify the URL to which the client is redirected after successful upload. This condition supports the exact match and starts-with match modes.
success_action_status Specify the status code returned after successful upload if success_action_redirect is not specified. This condition supports the exact match and starts-with match modes.
x-oss-meta-* Specify the user meta set by the user. This condition supports the exact match and starts-with match modes.

If the Post Object request contains other form fields, these extra form fields can be added to Conditions of the policy. The OSS does not check validity of the form fields that are not contained in the conditions.

Condition match modes

Conditions match modes Description
Exact match The value of a form field must be exactly the same as the value declared in the conditions. For example, if the value of the key form field must be a, the conditions must be: {“key”: “a”}, or: [“eq”, “$key”, “a”]
Starts With The value of a form field must start with the specified value. For example, if the value of key must start with /user/user1, the conditions must be: [“starts-with”, “$key”, “/user/user1”]
Specified file size Specify the maximum and minimum sizes of the files that can be uploaded. For example, if the acceptable file size is 1–10 bytes, the conditions must be: [“content-length-range”, 1, 10]

Escape characters

In the policy form field of the Post Object request, $ is used to indicate a variable. Therefore, to describe $, the escape character must be used. In addition, some characters in JSON strings are escaped. The following chart describes characters in the JSON string of the policy form field of a Post Object request.

Escape characters Description
\/ Slash
\ Backslash
\” Double quotation marks
\$ Dollar sign
\b Space
\f Form feed
\n Newline
\r Carriage return
\t Horizontal tab
\uxxxx Unicode character

Post Signature

For a verified Post Object request, the HTML form must contain policy and signature. Policy specifies which values are acceptable in the request. The procedure for computing signature is as follows:

  1. Create a UTF-8 encoded policy.
  2. Encode the policy with Base64. The encoding result is the value of the policy form field, and this value is used as the string to be signed.
  3. Use AccessKeySecret to sign the string. The signing method is the same as the computing method of the signature in the Header, that is, replacing the string to be signed with the policy form field.

Demo sample

  • Demo of passing parameters from the web form field to the OSS: Click here
Thank you! We've received your feedback.