Python初始化

注意事项

• 初始化Python SDK前，您需要配置访问凭证，本文以从环境变量读取访问凭证为例，详情请参见配置访问凭证。

• 如果您希望获取关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。

• 如果您希望创建RAM用户的AccessKey，请参见创建AccessKey。

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

  • oss2.Service类用于列举存储空间。

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

  初始化oss2.Service和oss2.Bucket两个类时，需要指定Endpoint。其中oss2.Service类不支持自定义域名访问。

前置条件

1. 使用RAM用户AccessKey配置环境变量。

   Linux

   macOS

   Windows

   1. 在命令行界面执行以下命令来将环境变量设置追加到~/.bashrc 文件中。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

      1. 执行以下命令使变更生效。

         source ~/.bashrc

      2. 执行以下命令检查环境变量是否生效。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   1. 在终端中执行以下命令，查看默认Shell类型。

      echo $SHELL

      1. 根据默认Shell类型进行操作。

         Zsh

         Bash

         1. 执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
            echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

         2. 执行以下命令使变更生效。

            source ~/.zshrc

         3. 执行以下命令检查环境变量是否生效。

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

         1. 执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
            echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

         2. 执行以下命令使变更生效。

            source ~/.bash_profile

         3. 执行以下命令检查环境变量是否生效。

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

   CMD

   PowerShell

   1. 在CMD中运行以下命令。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

      1. 运行以下命令，检查环境变量是否生效。

         echo %OSS_ACCESS_KEY_ID%
         echo %OSS_ACCESS_KEY_SECRET%

   1. 在PowerShell中运行以下命令。

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

      1. 运行以下命令，检查环境变量是否生效。

         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

2. 参考上述方式修改系统环境变量后，请重启或刷新您的编译运行环境，包括IDE、命令行界面、其他桌面应用程序及后台服务，以确保最新的系统环境变量成功加载。

默认示例

以下代码示例演示了如何使用V4签名和V1签名初始化Python SDK。

请注意，以下代码示例使用Bucket外网域名以及RAM用户的AK信息。

# -*- 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) 

# -*- 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')                    

常见场景配置示例

以下提供了常见场景的配置示例，其中代码示例默认使用V4签名以及RAM用户的AK信息进行初始化。

内网域名配置示例

当您的应用部署在阿里云的ECS实例上，并且需要频繁访问同地域的OSS资源时，使用内网域名可以降低流量成本并提高访问速度。

以下是使用OSS内网域名配置OSSClient的示例代码。

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

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

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

自定义域名配置示例

当您有多个不同的OSS Bucket用于不同的目的时，可以通过为每个Bucket设置不同的子域名来更好地管理和组织资源。

以下是使用自定义域名配置OSSClient的示例代码。

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

# 从环境变量中获取访问凭证。运行本代码示例之前，请先配置环境变量。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# yourEndpoint请填写您的自定义域名。例如https://static.example.com。
endpoint = 'yourEndpoint'
# 填写Endpoint对应的Region信息，例如cn-hangzhou。
region = 'cn-hangzhou'

# 填写Bucket名称。请注意，设置is_cname=True表示开启CNAME选项
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', is_cname=True, 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"

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

关闭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协议。

以下代码用于指定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")

oss2.Bucket类支持配置的参数汇总

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

常见问题