Form upload

Last Updated: Nov 27, 2017

Use cases

It refers to the situation where a user uploads an object by using the Post Object request in the OSS API. The object to be uploaded cannot be larger than 5 GB. This method embeds forms in HTML web pages to upload objects. A typical scenario is websites. Here we take a job-search website as an example:

Without using form upload Using form upload
Process comparison 1. A website user uploads a resume
2. The website server responds to the upload page
3. The resume is uploaded to the server
4. The server uploads the resume to OSS
1. A website user uploads a resume
2. The website server responds to the upload page
3. The resume is uploaded to OSS

Upload restrictions

  • Size limit: The object cannot be larger than 5 GB when form upload is used.
  • Naming restrictions:
    • It uses UTF-8 encoding
    • The length must be 1-1,023 bytes
    • It cannot start with “/“ or “\”

Advantages of form upload

  • The step of file forwarding is bypassed.
  • In the traditional way without using form upload, files are uploaded to the website server first, which becomes the bottleneck and needs to be resized in case of huge uploads. With form upload, files are uploaded directly from the client to OSS. OSS undertakes the stress from huge uploads and guarantees the service quality.

Upload security and authorization

  • To prevent unauthorized third parties from uploading objects to the developer’s bucket, OSS provides bucket- and object-level access control. For more information, see OSS Fine-grained Access Control.

  • To grant upload permission to a third party, users can use the PostObject interface. For more information, see PostObject.

Basic steps of form upload

  1. Construct a Post policy.

    The policy form field of the Post request is used to verify the validity of the request. For example, it can specify the size and name of objects to be uploaded, and the URL the client jumps to and the status code the client receives after a successful upload. For more information, see Post Policy.

    In the following example of policy, the expiration time for uploads by website users is 2115-01-27T10:56:19Z (To complete the test successfully, we set a long expiration period, which is not recommended in actual use) and the maximum file size is 104857600 bytes.

    1. This example uses Python code and the policy is a string in JSON format.
    2. policy="{\"expiration\":\"2115-01-27T10:56:19Z\",\"conditions\":[[\"content-length-range\", 0, 104857600]]}"
  2. Encode the policy string using Base64.
  3. Use the OSS AccessKeySecret to sign the Base64-encoded policy.
  4. Construct an HTML page for uploads.
  5. Open the HTML page and select the file to upload.

Complete Python code:

  1. #coding=utf8
  2. import md5
  3. import hashlib
  4. import base64
  5. import hmac
  6. from optparse import OptionParser
  7. def convert_base64(input):
  8. return base64.b64encode(input)
  9. def get_sign_policy(key, policy):
  10. return base64.b64encode(, policy, hashlib.sha1).digest())
  11. def get_form(bucket, endpoint, access_key_id, access_key_secret, out):
  12. #1. Construct a Post policy
  13. policy="{\"expiration\":\"2115-01-27T10:56:19Z\",\"conditions\":[[\"content-length-range\", 0, 1048576]]}"
  14. print("policy: %s" % policy)
  15. #2. Encode the policy string using Base64
  16. base64policy = convert_base64(policy)
  17. print("base64_encode_policy: %s" % base64policy)
  18. #3. Use the OSS AccessKeySecret to sign the Base64-encoded policy
  19. signature = get_sign_policy(access_key_secret, base64policy)
  20. #4. Construct an HTML page for uploads
  21. form = '''
  22. <html>
  23. <meta http-equiv=content-type content="text/html; charset=UTF-8">
  24. <head><title>OSS form upload (PostObject)</title></head>
  25. <body>
  26. <form action="http://%s.%s" method="post" enctype="multipart/form-data">
  27. <input type="text" name="OSSAccessKeyId" value="%s">
  28. <input type="text" name="policy" value="%s">
  29. <input type="text" name="Signature" value="%s">
  30. <input type="text" name="key" value="upload/${filename}">
  31. <input type="text" name="success_action_redirect" value="">
  32. <input type="text" name="success_action_status" value="201">
  33. <input name="file" type="file" id="file">
  34. <input name="submit" value="Upload" type="submit">
  35. </form>
  36. </body>
  37. </html>
  38. ''' % (bucket, endpoint, access_key_id, base64policy, signature)
  39. f = open(out, "wb")
  40. f.write(form)
  41. f.close()
  42. print("form is saved into %s" % out)
  43. if __name__ == '__main__':
  44. parser = OptionParser()
  45. parser.add_option("", "--bucket", dest="bucket", help="specify ")
  46. parser.add_option("", "--endpoint", dest="endpoint", help="specify")
  47. parser.add_option("", "--id", dest="id", help="access_key_id")
  48. parser.add_option("", "--key", dest="key", help="access_key_secret")
  49. parser.add_option("", "--out", dest="out", help="out put form")
  50. (opts, args) = parser.parse_args()
  51. if opts.bucket and opts.endpoint and and opts.key and opts.out:
  52. get_form(opts.bucket, opts.endpoint,, opts.key, opts.out)
  53. else:
  54. print "python %s --bucket=your-bucket --id=your-access-key-id --key=your-access-key-secret --out=out-put-form-name" % __file__

Save this code segment as and use Python to run it.

  1. Usage:
  2. python --bucket=Your bucket --endpoint=The bucket's OSS domain name --id=Your AccessKeyId --key=Your AccessKeySecret --out=Output file name
  3. Example:
  4. python --bucket=oss-sample --id=tphpxp --key=ZQNJzf4QJRkrH4 --out=post.html


  • In the constructed form, success_action_redirect value= indicates the page to jump to after a successful upload. You can replace it with your own page.
  • In the constructed form, success_action_status value=201 indicates that Status Code 201 is returned after a successful upload. This can be replaced as needed.
  • If the generated HTML file is post.html, open post.html and select the file to upload. In this example, the client jumps to the OSS homepage after a successful upload.

Function usage reference

Best practices

Thank you! We've received your feedback.