如何初始化Python SDK_对象存储(OSS)-阿里云帮助中心

本文介绍如何初始化Python SDK。

前提条件

初始化Python SDK前，您需要配置访问凭证。详情请参见配置访问凭证。

背景信息

使用Python SDK时，大部分操作都是通过oss2.Service和oss2.Bucket两个类进行。

oss2.Service类用于列举存储空间。
oss2.Bucket类用于上传、下载、删除文件以及对存储空间进行各种配置。

初始化oss2.Service和oss2.Bucket两个类时，需要指定Endpoint。其中oss2.Service类不支持自定义域名访问。关于Endpoint的更多信息，请参见OSS地域和访问域名和自定义访问域名。

初始化oss2.Service类

具体操作，请参见列举存储空间。

初始化oss2.Bucket类

V4签名（推荐）

推荐使用更安全的V4签名算法。使用V4签名初始化时，除指定Endpoint以外，您还需要指定阿里云通用Region ID作为发起请求地域的标识，示例值为cn-hangzhou。同时声明oss2.ProviderAuthV4。OSS Python SDK 2.18.4及以上版本支持V4签名。

以使用OSS域名初始化时使用V4签名为例，其他通过自定义域名、匿名初始化的场景可参考以下示例执行相应修改。

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

# 从环境变量中获取访问凭证。运行本代码示例之前，请先配置环境变量。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'yourEndpoint'
# 填写Endpoint对应的Region信息，例如cn-hangzhou。
region = 'cn-hangzhou'

# 填写Bucket名称。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

V1签名（不推荐）

重要

阿里云对象存储OSS自2025年03月01日起不再对新用户（即新UID ）开放使用V1签名，并将于2025年09月01日起停止更新与维护且不再对新增Bucket开放使用V1签名。请尽快切换到V4签名，避免影响服务。更多信息，请参见公告说明。

使用OSS域名初始化

以下代码用于使用OSS域名初始化。关于不同地域的OSS域名，请参见OSS地域和访问域名。

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

# 从环境变量中获取访问凭证。运行本代码示例之前，请先配置环境变量。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'yourEndpoint'

# 填写Bucket名称。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket')

使用自定义域名初始化

以下代码用于使用自定义域名初始化。关于使用自定义域名访问OSS的更多信息，请参见绑定自定义域名至Bucket默认域名。

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

# 从环境变量中获取访问凭证。运行本代码示例之前，请先配置环境变量。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# 填写自定义域名，例如example.com。
cname = 'http://example.com'

# 填写Bucket名称，并设置is_cname=True来开启CNAME。CNAME是指将自定义域名绑定到存储空间。
bucket = oss2.Bucket(auth, cname, 'examplebucket', is_cname=True)

使用匿名访问初始化

重要

匿名用户只能读取public-read（公共读）的Bucket以及读取和写入public-read-write（公共读写）的Bucket，不能进行Service相关的操作、Bucket相关的操作、列举文件等。

假设examplebucket存储空间的ACL为public-read-write，以下代码用于使用匿名访问初始化。

# -*- coding: utf-8 -*-
import oss2

# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'yourEndpoint'

# 填写Bucket名称，例如examplebucket。    
bucket_name = 'examplebucket'

# 使用匿名访问初始化。
bucket = oss2.Bucket(oss2.AnonymousAuth(), endpoint, bucket_name)

oss2.Bucket类支持配置的参数

初始化oss2.Bucket类时支持配置的参数请参见下表。

参数	示例值	描述	方法
is_cname	True	Endpoint是否为自定义域名。取值范围如下： True：Endpoint为自定义域名。 False（默认）：Endpoint为OSS域名。	oss2.Bucket(auth, cname, 'examplebucket', is_cname=True, region=region)
session	mytestsession	会话名，默认值为None，表示新开会话。如果设置此参数为已有会话名，则复用传入的会话。	oss2.Bucket(auth, endpoint, 'examplebucket', session=oss2.Session(), region=region)
connect_timeout	30	连接超时时间，默认值为60，单位为秒。	oss2.Bucket(auth, endpoint, 'examplebucket', connect_timeout=30, region=region)
app_name	mytool	应用名，默认值为空。如果此参数不为空，则在User Agent中加入对应值。重要由于该字符串会作为HTTP Header的值进行传输，因此该字符串必须遵循HTTP标准。	oss2.Bucket(auth, endpoint, 'examplebucket', app_name='mytool', region=region)
enable_crc	False	是否开启CRC数据校验。 True（默认）：开启 False：关闭	oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False, region=region)

oss2.Bucket类配置示例

oss2.Bucket类常见配置示例如下。

设置连接超时时间

以下代码用于设置连接超时时间。

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

# 强烈建议不要把访问凭证保存到工程代码里，否则可能导致访问凭证泄露，威胁您账号下所有资源的安全。本代码示例以从环境变量中获取访问凭证为例。运行本代码示例之前，请先配置环境变量。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
region = "cn-hangzhou"

# 填写Bucket名称，并设置连接超时时间为30秒。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', connect_timeout=30,region=region)

关闭CRC数据校验

上传和下载文件时默认开启CRC数据校验，确保上传和下载过程的数据完整性。

警告

强烈建议不要关闭CRC数据校验功能。如果关闭此功能，则阿里云不保证上传和下载过程数据的完整性。

以下代码用于关闭CRC数据校验。

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

# 强烈建议不要把访问凭证保存到工程代码里，否则可能导致访问凭证泄露，威胁您账号下所有资源的安全。本代码示例以从环境变量中获取访问凭证为例。运行本代码示例之前，请先配置环境变量。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
region = "cn-hangzhou"

# 填写Bucket名称，并设置enable_crc=False来关闭CRC数据校验。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False,region=region)

设置连接池大小

以下代码用于设置连接池大小。

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

# 强烈建议不要把访问凭证保存到工程代码里，否则可能导致访问凭证泄露，威胁您账号下所有资源的安全。本代码示例以从环境变量中获取访问凭证为例。运行本代码示例之前，请先配置环境变量。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
region = "cn-hangzhou"

# 设置连接池的大小，默认值为10。
session = oss2.Session(pool_size=20)

# 填写Bucket名称。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', session=session,region=region)

指定TLS版本

不同版本的TLS协议有不同的安全性和性能特点，请根据具体的应用场景选择合适版本的TLS协议。

说明

Python SDK 2.18.1及以上版本支持指定TLS版本。

以下代码用于指定TLS版本为1.2。

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

# 从环境变量中获取访问凭证。运行本代码示例之前，请先配置环境变量。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 自定义ssl adapter。
class SSLAdapter(HTTPAdapter):
    def init_poolmanager(self, *args, **kwargs):
        # 设置TLS版本为1.2。
        kwargs["ssl_version"] = ssl.PROTOCOL_TLSv1_2
        return super().init_poolmanager(*args, **kwargs)

# 创建session对象，并通过session自定义adapter。
session = oss2.Session(adapter=SSLAdapter())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
region = "cn-hangzhou"

# 填写Bucket名称，例如examplebucket。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', session=session, region=region)

# 上传文件。
bucket.put_object("example.txt", "hello")