Object Storage Service:Simple upload

Precautions

• 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 access permissions on the file, the uploaded file overwrites the existing file.

Permissions

By default, an Alibaba Cloud account has full permissions on resources in the account. In contrast, RAM users and RAM roles associated with an Alibaba Cloud account initially have no permissions. To manage resources by using a RAM user or role, you must grant the required permissions via RAM policies or Bucket policies.

Common parameters

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

Upload strings

The following code provides an example on 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 for 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 file.
# 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. The full path cannot contain the bucket name.
# result = bucket.put_object('exampleobject.txt', 'Hello OSS', headers=headers)
result = bucket.put_object('exampleobject.txt', 'Hello OSS')

# Show the 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))
# Obtain 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))
# Obtain the HTTP response headers.
print('date: {0}'.format(result.headers['date']))

Upload bytes

The following code provides an example on 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 for 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. The full path cannot contain the bucket name.
bucket.put_object('exampleobject.txt', b'Hello OSS')

Upload unicode characters

The following code provides an example on 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 for 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. The full path cannot contain the bucket name.
bucket.put_object('exampleobject.txt', u'Hello OSS')

Upload a network stream

The following code provides an example on 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 for 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. The full path cannot contain the bucket name.
bucket.put_object('exampleobject.txt', input)

Upload local file

The following code provides an example on how to upload a local file named examplefile.txt to a bucket named examplebucket and save the file 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 for 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, such as examplebucket.
bucketName = "examplebucket"
# Create a bucket instance and specify the name and region of the bucket.
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 contain the bucket name. Example: exampleobject.txt.
objectName = 'exampleobject.txt'

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

If you want to upload from a specific byte position of a local file, you can use the seek() method to jump to the target byte position. The following code provides an example on how to upload data from byte 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 for 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, such as 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. If the path of the local file is not specified, 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 of the local file until the entire file is uploaded.
    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. The full path cannot contain the bucket name.
    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 the object URL, see Use a signed URL to download an object.

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 an uploaded object is different from that of the local file, an InconsistentError error is reported.

2. However, the CRC check is performed during data transmission and calculation, which affects the upload speed. If your business scenario requires faster transmission, you can disable CRC check by using the following code:

   # -*- 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 for 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=False to disable CRC check 
   bucket = oss2.Bucket(auth, endpoint, "yourBucketName", enable_crc=False, region=region)

References

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

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