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 |
A website user sends a request to upload a resume. The website server responds with a resume upload page. The resume is uploaded to the website server. The website server uploads the resume to Object Storage Service (OSS).
| A website user sends a request to upload a resume. The website server responds with a resume upload page. 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 of an object 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 for upload, 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
Object Storage Service (OSS) allows you to configure the access control list (ACL) 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. If you send a large number of requests to query these objects, latency may increase. If you upload a large number of objects, we recommend that you use random prefixes instead of sequential prefixes to specify object names. For more information, see OSS performance and scalability best practices.
Prevent 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 at any time. For more information, see Overview.
Include the x-oss-forbid-overwrite parameter in the upload request
You can add the x-oss-forbid-overwrite parameter to the header of the upload request and set this parameter to true. This way, if you upload an object that has the same name as an existing object, the object cannot be uploaded and OSS returns the FileAlreadyExists error. If you do not add this parameter to the request header or if you set this parameter to false, the uploaded object that has the same name as the existing object overwrites the existing object.
Use OSS SDKs
You can perform the following steps to perform form upload by using OSS SDK for Python:
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__)
Save the preceding code as a file named postobject.py.
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 that is used to access OSS. |
--key | The AccessKey secret of your Alibaba Cloud account that is used to access OSS. |
--out | The name of the output file. |
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 RESTful APIs
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.