You can call this operation to upload an object to a specific bucket by using HTML form upload.

Note
  • To perform the PostObject operation on a bucket, you must have the write permissions on the bucket. If the ACL of the bucket is public read/write, you do not need to upload the signature information. If the ACL of the bucket is not public read/write, signature verification is required for this operation. Unlike PutObject, PostObject uses an AccessKey secret to calculate the signature for policy. The calculated signature string is used as the value for the Signature form field. OSS checks this value to verify the validity of the signature.
  • The URL of the submitted form can be the domain name of the bucket. You do not need to specify the object 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.
  • If the PostObject request contains the Header signature or the URL signature, OSS does not check these signatures.

Versioning

If you initiate a PostObject request to a versioning-enabled bucket, OSS automatically generates a unique version ID for the uploaded object and includes the version ID in the x-oss-version-id response header.

If you initiate a PostObject request to a versioning-suspended bucket, OSS automatically generates a null version ID for the uploaded object and includes the version ID in the x-oss-version-id response header. An object can only have one null version ID.

PostObject

  • 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
    Note The message body of a PostObject request is encoded in multipart/form-data format. In PostObject operations, parameters are passed as form fields in the request message body, whereas parameters are passed by HTTP request headers in PutObject operations.
    Header Type Required Description
    OSSAccessKeyId String Conditional Specifies the AccessKey ID of the bucket owner.

    This parameter is empty by default.

    Constraint: This form field is required when the bucket ACL is not public read/write or when the policy (or Signature) form field is provided.

    policy String Conditional Specifies the validity of the form fields in the request. A request that does not contain the policy form field is considered as an anonymous request, and can only be used to access buckets whose ACLs are public read/write.

    This parameter is empty by default.

    Constraint: This form field is required when the bucket ACL is not public read/write or when the OSSAccessKeyId (or Signature) form field is provided.

    Note The form and the policy form field must be encoded in UTF-8.
    Signature String Conditional Specifies the signature information that is calculated based on the AccessKey secret and the policy form field. OSS checks the signature information to verify the validity of the PostObject request. For more information, see the Post Signature section in this topic.

    This parameter is empty by default.

    Constraint: This form field is required when the bucket ACL is not public read/write or when the OSSAccessKeyId (or Policy) form field is provided.

    Note Form fields are case-insensitive, but their values are case-sensitive.
    Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires String No Specifies the HTTP request headers. For more information, see PutObject.

    This parameter is empty by default.

    The form submitted by the PostObject operation must be encoded in multipart/form-data format. For example, the Content-Type header must be in multipart/form-data;boundary=xxxxxx format, where boundary is a boundary string.

    file String Yes Specifies the file or text content. It must be the last field in the form. The browser automatically sets the Content-Type header based on the file type and overwrites the user setting. Only one file can be uploaded to OSS at a time.

    This parameter is empty by default.

    key String Yes Specifies the name of the object to upload. If the object name includes a path such as a/b/c/b.jpg, OSS automatically creates the corresponding directory.

    This parameter is empty by default.

    success_action_redirect String No Specifies the URL to which the client is redirected after the object is uploaded. If this form field is not specified, the returned result is specified by success_action_status. If the upload fails, OSS returns an error code, and the client is not redirected to any URL.

    This parameter is empty by default.

    success_action_status String No Specifies the status code returned to the client in the case that the success_action_redirect form field is not specified and the object is uploaded.

    This parameter is empty by default.

    Valid values: 200, 201, and 204. The default value is 204.

    Note
    • If the value of this form field is set to 200 or 204, OSS returns an empty file and the 200 or 204 status code.
    • If the value of this form field is set to 201, OSS returns an XML file and the 201 status code.
    • If the value of this form field is not specified or set to an invalid value, OSS returns an empty file and the 204 status code.
    x-oss-meta-* String No Specifies the metadata customized by the user.

    This parameter is empty by default.

    If the request contains a form field prefixed with x-oss-meta-, the form field is considered as the user metadata. Example: x-oss-meta-location.
    Note An object may have multiple similar parameters, but the total size of the user metadata cannot exceed 8 KB.
    x-oss-server-side-encryption String No Specifies the server-side encryption algorithm to use when OSS creates the object.

    Valid values: AES256 and KMS. You must activate KMS to use the KMS-based encryption algorithm. Otherwise, a KmsServiceNotEnabled error code is returned.

    If you specify this parameter, it is returned in the response header and the uploaded object is encrypted. When you download the encrypted object, the x-oss-server-side-encryption field is included in the response header and the value of this field is set to the algorithm used to encrypt the object.

    x-oss-server-side-encryption-key-id String No Specifies the ID of the customer master key (CMK) hosted in KMS.

    This parameter is valid only when the value of x-oss-server-side-encryption is set to KMS.

    x-oss-object-acl String No Specifies the ACL that is configured when OSS creates the object.

    Valid values: public-read, private, and public-read-write

    x-oss-security-token String No If an STS temporary security credential is used for this access, you must set this field to the SecurityToken value and set OSSAccessKeyId to the value of the paired temporary AccessKey ID. The method for calculating a signature based on a temporary AccessKey ID is the same as that based on a typical AccessKey ID.

    This parameter is empty by default.

    x-oss-forbid-overwrite String No Specifies whether the PostObject operation overwrites the object with the same name.
    • If x-oss-forbid-overwrite is not specified, the object with the same name is overwritten.
    • If x-oss-forbid-overwrite is set to true, the object with the same name cannot be overwritten. If x-oss-forbid-overwrite is set to false, the object with the same name can be overwritten.
    Note
    • The x-oss-forbid-overwrite request header is invalid when the versioning state of the target bucket is Enabled or Suspended. In this case, the PostObject operation overwrites the object with the same name.
    • Specifying the x-oss-forbid-overwrite request header may degrade the query per second (QPS) performance of OSS. If you want to use the x-oss-forbid-overwrite request header for a large number of operations (QPS > 1000), submit a ticket.
  • Response headers
    Header Type Description
    x-oss-server-side-encryption String If x-oss-server-side-encryption is specified in the request, the response header contains this field to indicate the encryption algorithm used.
  • Response elements
    Element Type Description
    PostResponse Container Specifies the container that stores the result of the PostObject request.

    Child node: Bucket, ETag, Key, and Location

    Bucket String Specifies the bucket name.

    Parent node: PostResponse

    ETag String Specifies the entity tag (ETag) that is created when an object is generated. For an object that is created through the PostObject operation, the ETag value is the object UUID, which can be used to check whether the object content has changed.

    Parent node: PostResponse

    Location String Specifies the URL of the new object that is created.

    Parent node: PostResponse

  • 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"
      44CF9590006BF252F707
      --9431149156168
      Content-Disposition: form-data; name="policy"
      eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
      --9431149156168
      Content-Disposition: form-data; name="Signature"
      kZoYNv66bsmc10+dcGKw5x2PRrk=
      --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
    Error code HTTP status code Description
    InvalidArgument 400 The error message returned because when any one of the OSSAccessKeyId, Policy, and Signature form fields is uploaded, the remaining two form fields are missing, regardless of whether the bucket ACL is public read/write.
    InvalidDigest 400 The error message returned because the Content-MD5 value of the request body that is calculated by OSS is not the same as the value of the Content-MD5 header field in the request.
    EntityTooLarge 400 The error message returned because the total size of the PostObject request body is greater than 5 GB.
    InvalidEncryptionAlgorithmError 400 The error message returned because a value other than AES256 or KMS is set for the x-oss-server-side-encryption header field.
    FileAlreadyExists 409 The error message returned because an object with the same name already exists when the request contains an x-oss-forbid-overwrite header and the value of this header is set to true.

Policy

The policy form field in a PostObject request is used to verify the validity of the request. The policy is a JSON text encoded in UTF-8 and Base64. It declares the conditions that a PostObject request must meet. Although the policy form field is optional for uploading objects to a bucket whose ACL is public read/write, we recommend that you use this field to limit PostObject requests.

Example

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

    Expiration specifies the expiration time of the policy. The time follows the ISO 8601 standard. The time 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
    Conditions is a list that specifies the valid values of 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 the policy is equivalent to the value of the form field before extension.

    The following table lists the conditions supported by the policy.

    Condition Description
    content-length-range Specifies the minimum and maximum sizes of the object to upload. This condition supports the content-length-range match mode.
    Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires Specifies the HTTP request headers. This condition supports the exact match and starts-with match modes.
    Notice We recommend that you include the Content-Type parameter in the policy form field to prevent malicious modification to the Content-Type header during form upload.
    key Specifies the name of the object to upload. This condition supports the exact match and starts-with match modes.
    success_action_redirect Specifies the URL to which the client is redirected after the object is uploaded. This condition supports the exact match and starts-with match modes.
    success_action_status Specifies the status code to return after the object is uploaded if success_action_redirect is not specified. This condition supports the exact match and starts-with match modes.
    x-oss-meta-* Specifies the metadata customized by the user. This condition supports the exact match and starts-with match modes.

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

  • Condition match modes
    Condition match mode Description
    Exact match The value of a form field must be exactly the same as the value that are declared in the conditions. For example, if the value of the key form field must be a, the condition 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 the key form field must start with /user/user1, the condition must be ["starts-with", "$key", "/user/user1"].
    Specified object size Specifies the range of acceptable object sizes. For example, if the acceptable object size is 1 to 10 bytes, the condition must be ["content-length-range", 1, 10].

    Escape characters

    In the policy form field of the PostObject request, the dollar sign ($) is used to indicate a variable. Therefore, the escape character describes the dollar sign ($). In addition, some characters in JSON strings are escaped. The following table describes escape characters in the JSON string of the policy form field of a PostObject request.

    Escape character Description
    \/ Forward slash
    \ Backslash
    \" Double quotation marks
    \$ Dollar sign
    \b Backspace
    \f Form feed
    \n Newline
    \r Carriage return
    \t Horizontal tab
    \uxxxx Unicode character

Signature

For a verified PostObject request, the HTML form must contain the policy and Signature form fields. The policy form field specifies which values are acceptable in the request.

The procedure to calculate the Signature form field is as follows:

  1. Create a UTF-8 encoded policy.
  2. Encode the policy in Base64. The encoding 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. The signing method is the same as the calculating method of the signature in the header, which is replacing the string-to-sign with the policy form field. For more information, see Add signatures to headers.

Demo

For the demo of transferring data from the web to OSS by using form upload, see JavaScript-based signatures on the client for object uploads.