Object Storage Service:Python simple upload

Notes

• In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.

• In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Initialization.

• If you upload an object that has the same name as an existing object, the existing object will be overwritten.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM Policy or Bucket Policy.

Common parameters

The following table lists the common parameters that you must configure when uploading an object.

Upload strings

The following code provides an example of how to upload a string to an object named exampleobject.txt in a bucket named examplebucket:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Specify the region in which the bucket is located. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"

# Specify the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Upload the object.
# You can configure the x-oss-storage-class and x-oss-object-acl headers for put_object to specify the storage class and access control list (ACL) of the object that you want to upload.
# headers = dict()
# headers["x-oss-storage-class"] = "Standard"
# headers["x-oss-object-acl"] = oss2.OBJECT_ACL_PRIVATE
# Specify the full path of the object and the string that you want to upload. Do not include the bucket name in the full path.
# result = bucket.put_object('exampleobject.txt', 'Hello OSS', headers=headers)
result = bucket.put_object('exampleobject.txt', 'Hello OSS')

# Display the returned HTTP status code.
print('http status: {0}'.format(result.status))
# Display the request ID. A request ID uniquely identifies a request. We recommend that you add this parameter to the logs.
print('request_id: {0}'.format(result.request_id))
# Display the ETag value returned by the put_object method. The ETag value of an object is used to identify the object content.
print('ETag: {0}'.format(result.etag))
# Display the HTTP response headers.
print('date: {0}'.format(result.headers['date']))

Upload bytes

The following code provides an example of how to upload bytes to an object named exampleobject.txt in a bucket named examplebucket:

# -*- coding: utf-8 -*-

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Specify the region in which the bucket is located. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"

# Specify the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Specify the full path of the object and the bytes that you want to upload. Do not include the bucket name in the full path.
bucket.put_object('exampleobject.txt', b'Hello OSS')

Upload Unicode characters

The following code provides an example of how to upload Unicode characters to an object named exampleobject.txt in a bucket named examplebucket. When you upload Unicode characters, OSS converts the characters into UTF-8-encoded bytes.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Specify the region in which the bucket is located. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"

# Specify the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Specify the full path of the object and the Unicode characters that you want to upload. Do not include the bucket name in the full path.
bucket.put_object('exampleobject.txt', u'Hello OSS')

Upload a network stream

The following code provides an example of how to upload a network stream to an object named exampleobject.txt in a bucket named examplebucket. OSS uploads network streams as iterable objects by using chunked encoding.

# -*- coding: utf-8 -*-
import oss2
import requests
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Specify the region in which the bucket is located. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"

# Specify the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# The requests.get method returns an iterable object. OSS SDK for Python uploads the object by using chunked encoding.
# Specify the address of the network stream.
input = requests.get('http://www.aliyun.com')
# Specify the full path of the object. Do not include the bucket name in the full path.
bucket.put_object('exampleobject.txt', input)

Upload local files

The following code provides an example of how to upload a local file named examplefile.txt to a bucket named examplebucket. The uploaded file is stored as exampleobject.txt.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Specify the region in which the bucket is located. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"
# Specify the name of the bucket. Example: examplebucket.
bucketName = "examplebucket"
# Create a bucket and specify its name and region.
bucket = oss2.Bucket(auth, endpoint, bucketName, region=region)

# The full path of the local file.
local_file_path = 'D:\\localpath\\examplefile.txt'  

# Specify the full path of the object. Do not include the bucket name in the full path. Example: exampleobject.txt.
objectName = 'exampleobject.txt'

# Use the put_object_from_file method to upload the local file to OSS
bucket.put_object_from_file(objectName, local_file_path)

To upload from a specific byte position in a local file, you can use the seek() method to move to the desired offset. The following example shows how to start uploading from byte position 1000.

# -*- coding: utf-8 -*-
import oss2
import os
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Specify the region in which the bucket is located. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"

# Specify the name of the bucket. Example: examplebucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# The file must be opened in binary mode.
# Specify the full path of the local file. By default, if you do not specify the full path, the local file is uploaded from the path of the project to which the sample program belongs.
with open('D:\\localpath\\examplefile.txt', 'rb') as fileobj:
    # Use the seek method to read data from byte 1,000 of the file. The data is uploaded from byte 1,000 to the last byte of the local file.
    fileobj.seek(1000, os.SEEK_SET)
    # Use the tell method to obtain the current position.
    current = fileobj.tell()
    # Specify the full path of the object. Do not include the bucket name in the full path.
    bucket.put_object('exampleobject.txt', fileobj)

FAQ

How do I obtain the object URL after an object is uploaded?

If you upload an object by using OSS SDKs, the object URL is not included in the response. For more information about how to obtain object URLs, see Download objects using presigned URLs.

How do I check whether the size of an uploaded object is the same as that of a local file?

1. CRC is enabled by default when you upload or download objects to ensure data integrity. If the size of the uploaded object differs from that of the local file, an error InconsistentError is returned.

2. Note that CRC is performed concurrently during data transfer, which may impact the upload speed. If your use case prioritizes transfer speed, you can disable CRC using the code example below.

   # -*- coding: utf-8 -*-
   import oss2
   import os
   from oss2.credentials import EnvironmentVariableCredentialsProvider
   
   # Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
   auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
   
   # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
   endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
   
   # Specify the region in which the bucket is located. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
   region = "cn-hangzhou"
   
   # Specify the name of the bucket and set enable_crc to False to disable CRC-64.
   bucket = oss2.Bucket(auth, endpoint, "yourBucketName", enable_crc=False, region=region)

References

• For the complete sample code that is used to perform simple upload, visit GitHub.

• For more information about the API operation that you can call to perform simple upload, see PutObject.