All Products
Search
Document Center

Object Storage Service:Form upload

Last Updated:Jan 29, 2024

You can call the PostObject operation to upload an object whose size does not exceed 5 GB as an HTML form.

Scenarios

You can use form upload to upload objects on HTML web pages. For example, you can use form upload in web applications. The following table compares the upload process when form upload is used and not used on a job-search website.

Form upload not used

Form upload used

  1. A website user sends a request to upload a resume.

  2. The website server responds with a resume upload page.

  3. The resume is uploaded to the website server.

  4. The website server uploads the resume to Object Storage Service (OSS).

  1. A website user sends a request to upload a resume.

  2. The website server responds with a resume upload page.

  3. The resume is uploaded to OSS.

  • Form upload provides a simpler process in which objects are directly uploaded to OSS without being forwarded by the website server.

  • Form upload also allows you to use a simpler architecture in which you can upload a large number of objects without scaling out the website server. In form upload, objects are directly uploaded from the client to OSS. OSS ensures service quality when a large number of objects are uploaded.

Usage notes

  • Object size

    You can upload an object up to 5 GB in size by using form upload. If you want to upload an object that is larger than 5 GB in size, use multipart upload. For more information, see Multipart upload.

  • Naming conventions for objects

    • The name must be encoded in UTF-8.

    • The name must be 1 to 1,023 characters in length.

    • The name cannot start with a forward slash (/) or a backslash (\).

  • Lower PUT request fees

    If you want to upload a large number of objects and set the storage classes of the objects to Deep Cold Archive, you are charged high PUT request fees. We recommend that you set the storage classes of the objects to Standard when you upload the objects, and configure lifecycle rules to convert the storage classes of the Standard objects to Deep Cold Archive. This reduces PUT request fees.

  • Security and authorization

    OSS allows you to configure the access control lists (ACLs) for buckets and objects. This way, third-party users who are not granted the required permissions cannot upload data to your bucket. For more information, see Overview.

    OSS provides account-level authorization. This allows you to grant permissions to third-party users to upload objects to OSS buckets. For more information, see Authorized third-party upload.

  • Performance tuning of object upload

    If you upload a large number of objects and the names of the objects contain sequential prefixes such as timestamps and letters, multiple object indexes may be stored in a single partition. In this case, if you send a large number of requests to query these objects, latency may increase. We recommend that you use random prefixes instead of sequential prefixes to specify object names when you upload a large number of objects. For more information, see OSS performance and scalability best practices.

  • Methods used to prevent the existing objects from being overwritten by uploaded objects that have the same names

    By default, OSS overwrites existing objects with the uploaded objects that have the same names. You can use the following methods to prevent the existing objects from being unexpectedly overwritten:

    • Enable versioning for the bucket.

      If you enable versioning for a bucket, objects that are overwritten in the bucket are saved as previous versions. You can recover the previous versions of the objects. For more information, see Overview.

    • Include the x-oss-forbid-overwrite parameter in the upload request

      Include the x-oss-forbid-overwrite parameter in the upload request and set the parameter to true. If you upload an object that has the same name as an existing object in OSS, the object fails to be uploaded and the FileAlreadyExists error is returned. If you do not include this parameter in the upload request or if you set this parameter to false, the uploaded object that has the same name as the existing object overwrites the existing object.

Procedure

Use OSS SDKs

You can perform the following steps to perform form upload by using OSS SDK for Python:

  1. Write the following code:

    #coding=utf8
    import hashlib
    import base64
    import hmac
    from optparse import OptionParser
    
    def convert_base64(input):
        return base64.b64encode(input.encode(encoding='utf-8')).decode('utf-8')
    
    def get_sign_policy(key, policy):
        return base64.b64encode(hmac.new(key.encode(encoding='utf-8'), policy.encode(encoding='utf-8'), hashlib.sha1).digest()).decode('utf-8')
    
    def get_form(bucket, endpoint, access_key_id, access_key_secret, out):
        # Create a POST policy. 
        # The policy form field in a PostObject request is used to verify the validity of the request. For example, you can configure a policy to specify the size and name of the object that you want to upload, the URL to which the client is redirected, and the HTTP status code that the client receives after the object is uploaded. 
        policy="{\"expiration\":\"2115-01-27T10:56:19Z\",\"conditions\":[[\"content-length-range\", 0, 1048576]]}"
        print("policy: %s" % policy)
        # Encode the policy string in Base64. 
        base64policy = convert_base64(policy)
        print("base64_encode_policy: %s" % base64policy)
        # Add a signature to the Base64-encoded policy by using the AccessKey secret of the account that is used to access OSS. 
        signature = get_sign_policy(access_key_secret, base64policy)
        # Create an HTML page for the upload. 
        form = '''
        <html>
            <meta http-equiv=content-type content="text/html; charset=UTF-8">
            <head><title>OSS form upload (by calling the PostObject operation)</title></head>
            <body>
                <form  action="http://%s.%s" method="post" enctype="multipart/form-data">
                    <input type="text" name="OSSAccessKeyId" value="%s">
                    <input type="text" name="policy" value="%s">
                    <input type="text" name="Signature" value="%s">
                    <input type="text" name="key" value="upload/${filename}">
                    # Specify the page to which the client is redirected after the object is uploaded. You can replace the page specified in the code with an actual page. 
                    <input type="text" name="success_action_redirect" value="https://oss.aliyun.com">
                    # Specify that HTTP status code 201 is returned after the object is uploaded. You can specify a returned HTTP status code based on your requirements. 
                    <input type="text" name="success_action_status" value="201">
                    <input name="file" type="file" id="file">
                    <input name="submit" value="Upload" type="submit">
                </form>
            </body>
        </html>
        ''' % (bucket, endpoint, access_key_id, base64policy, signature)
        f = open(out, "wb")
        f.write(form.encode(encoding='utf-8'))
        f.close()
        print("form is saved into %s" % out)
    if __name__ == '__main__':
        parser = OptionParser()
        parser.add_option("", "--bucket", dest="bucket", help="specify ")
        parser.add_option("", "--endpoint", dest="endpoint", help="specify")
        parser.add_option("", "--id", dest="id", help="access_key_id")
        parser.add_option("", "--key", dest="key", help="access_key_secret")
        parser.add_option("", "--out", dest="out", help="out put form")
        (opts, args) = parser.parse_args()
        if opts.bucket and opts.endpoint and opts.id and opts.key and opts.out:
            get_form(opts.bucket, opts.endpoint, opts.id, opts.key, opts.out)
        else:
            print("python %s --bucket=your-bucket --endpoint=oss-cn-hangzhou.aliyuncs.com --id=your-access-key-id --key=your-access-key-secret --out=out-put-form-name" % __file__)
  2. Save the preceding code as a file named postobject.py.

  3. Run the python postobject.py command in the path of your Python project to run the sample code and configure parameters.

    The following example shows a sample command:

    python postobject.py --bucket=examplebucket --endpoint=oss-cn-hangzhou.aliyuncs.com --id=LTAI5t7h6SgiLSganP2m**** --key=KZo149BD9GLPNiDIEmdQ7dyNKG**** --out=post.html

    The following table describes the parameters in the preceding command.

    Parameter

    Description

    --bucket

    The name of the bucket to which you want to upload an object.

    --endpoint

    The endpoint of the region in which the bucket is located.

    --id

    The AccessKey ID of your Alibaba Cloud account or RAM user that is used to access OSS.

    --key

    The AccessKey secret of your Alibaba Cloud account or RAM user that is used to access OSS.

    --out

    The name of the output file.

  4. Open post.html, select the object that you want to upload, and then click Upload.

    After the object is uploaded, the client is automatically redirected to the page specified in the sample code.

Use the OSS API

If your business requires a high level of customization, you can directly call RESTful APIs. To directly call an API, you must include the signature calculation in your code. For more information, see PostObject.