Object Storage Service:Simple upload (Python SDK V1)

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 a file with the same name already exists in the bucket and you have the required access permissions, the newly uploaded file overwrites the existing file.

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 policies.

Common parameters

The following table describes the common parameters used to upload files.

Upload a string

The following code provides an example of how to upload a string to the exampleobject.txt file in the examplebucket bucket.

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

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

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is 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 information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for v4 signatures.
region = "cn-hangzhou"

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

# Upload the file.
# To set the storage class (x-oss-storage-class) and access permissions (x-oss-object-acl) when uploading the file, set the relevant headers in put_object.
# 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. The full path cannot include the bucket name.
# result = bucket.put_object('exampleobject.txt', 'Hello OSS', headers=headers)
result = bucket.put_object('exampleobject.txt', 'Hello OSS')

# HTTP status code.
print('http status: {0}'.format(result.status))
# Request ID. The request ID uniquely identifies this request. Add this parameter to your program logs for easier troubleshooting.
print('request_id: {0}'.format(result.request_id))
# The ETag is a property specific to the return value of the put_object method. It identifies the content of an object.
print('ETag: {0}'.format(result.etag))
# HTTP response header.
print('date: {0}'.format(result.headers['date']))

Upload bytes

The following code provides an example of how to upload bytes to the exampleobject.txt file in the examplebucket bucket.

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

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

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

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is 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 information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for v4 signatures.
region = "cn-hangzhou"

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

# Specify the full path of the object and the byte content. The full path cannot include the bucket name.
bucket.put_object('exampleobject.txt', b'Hello OSS')

Upload a Unicode character

The following code provides an example of how to upload a Unicode character to the exampleobject.txt file in the examplebucket bucket. When you upload a Unicode character, OSS automatically converts it to UTF-8 encoded bytes before the upload.

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

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

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is 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 information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for v4 signatures.
region = "cn-hangzhou"

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

# Specify the full path of the object and the Unicode character. The full path cannot include the bucket name.
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 the exampleobject.txt file in the examplebucket bucket. OSS treats the network stream as an iterable object and uploads it using chunked encoding.

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

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

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is 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 information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for v4 signatures.
region = "cn-hangzhou"

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

# requests.get returns an iterable object. The Python SDK then uploads the object using chunked encoding.
# Specify the network stream URL.
input = requests.get('http://www.aliyun.com')
# Specify the full path of the object. The full path cannot include the bucket name.
bucket.put_object('exampleobject.txt', input)

Upload a local file

The following code provides an example of how to upload the local file examplefile.txt to the examplebucket bucket and save it as exampleobject.txt.

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

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

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is 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 information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for v4 signatures.
region = "cn-hangzhou"
# Specify the bucket name, for example, examplebucket.
bucketName = "examplebucket"
# Create a bucket instance and specify the bucket name and region information.
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. The full path cannot include the bucket name. For 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)

If you want to upload a local file starting from a specific byte position, you can use the seek() method to jump to the target position. The following code provides an example of how to start an upload from the 1000th byte.

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

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

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is 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 information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for v4 signatures.
region = "cn-hangzhou"

# Set yourBucketName to the bucket name, for example, examplebucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Open the file in binary mode.
# Specify the full path of the local file. If you do not specify a local path, the file is uploaded from the local path of the project that contains the sample program.
with open('D:\\localpath\\examplefile.txt', 'rb') as fileobj:
    # The seek() method specifies to start reading or writing from the 1000th byte. The upload starts from the specified 1000th byte and continues to the end of the file.
    fileobj.seek(1000, os.SEEK_SET)
    # The tell() method returns the current position.
    current = fileobj.tell()
    # Specify the full path of the object. The full path cannot include the bucket name.
    bucket.put_object('exampleobject.txt', fileobj)

FAQ

References

• For the complete sample code for simple uploads, see the GitHub example.

• For more information about the API operation for simple uploads, see PutObject.