如何使用Python SDK V2配置客户端_对象存储(OSS)-阿里云帮助中心

注意事项

初始化OSS Client前，您需要配置访问凭证，本文以从环境变量读取访问凭证为例，更多配置示例请参见配置访问凭证。
关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。

前置条件

重要

在配置客户端前，您需要先使用RAM用户AccessKey完成配置环境变量。

创建有OSS管理权限的RAM用户AccessKey。

使用ROS脚本快速创建有OSS管理权限的RAM用户AccessKey

在资源编排ROS控制台的创建资源栈页面的安全确认下，勾选确认，然后单击创建。
创建完成后，在输出中，复制创建的AccessKey。

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

Linux

macOS

Windows

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

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

执行以下命令使变更生效。
```
source ~/.bashrc
```

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

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

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

echo $SHELL

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

Zsh

Bash

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

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

执行以下命令使变更生效。
```
source ~/.zshrc
```

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

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

执行以下命令来将环境变量设置追加到 ~/.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

执行以下命令使变更生效。
```
source ~/.bash_profile
```

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

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

CMD

PowerShell

在CMD中运行以下命令。

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

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

echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%

在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)

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

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

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

默认配置示例

重要

Python SDK V2默认使用V4签名，在初始化Client时，您需要指定阿里云通用Region ID作为发起请求地域的标识，本示例代码使用华东1（杭州）Region ID：cn-hangzhou。如需查询其它Region ID请参见OSS地域和访问域名。
Python SDK V2可以通过Endpoint参数，自定义服务请求的访问域名。当不指定时，SDK默认根据Region信息，构造公网访问域名。例如当Region为'cn-hangzhou'时，构造出来的访问域名为'https://oss-cn-hangzhou.aliyuncs.com'。
Python SDK V2构造访问域名时默认采用https协议，如需采用http协议，请在指定域名时指定为http，例如'http://oss-cn-hangzhou.aliyuncs.com'。

import alibabacloud_oss_v2 as oss

def main():
    # 从环境变量中加载凭证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 加载SDK的默认配置，并设置凭证提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 方式一： 只填写Region即可
    # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    cfg.region = 'cn-hangzhou'

    # # 方式二： 直接填写Region和Endpoint
    # # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    # cfg.region = 'cn-hangzhou'
    # # 填写Bucket所在地域对应的公网Endpoint。以华东1（杭州）为例，Endpoint填写为'https://oss-cn-hangzhou.aliyuncs.com',
    # # 如需指定为http协议，请在指定域名时填写为'http://oss-cn-hangzhou.aliyuncs.com'
    # cfg.endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'

    # 使用配置好的信息创建OSS客户端
    client = oss.Client(cfg)

    # 使用创建好的client执行后续操作...

# 当此脚本被直接运行时，调用main函数
if __name__ == "__main__":
    main()  # 脚本入口，当文件被直接运行时调用main函数

常见场景配置示例

内网域名配置示例

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

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

import alibabacloud_oss_v2 as oss

def main():
    # 从环境变量中加载凭证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 加载SDK的默认配置，并设置凭证提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 方式一： 填写Region并设置use_internal_endpoint为true
    # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    cfg = oss.config.load_default()
    cfg.region = 'cn-hangzhou'
    cfg.use_internal_endpoint = True

    # # 方式二： 直接填写Region和内网Endpoint
    # # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    # cfg.region = 'cn-hangzhou'
    # # 填写Bucket所在地域对应的内网Endpoint。以华东1（杭州）为例，Endpoint填写为'https://oss-cn-hangzhou-internal.aliyuncs.com'
    # cfg.endpoint = 'https://oss-cn-hangzhou-internal.aliyuncs.com'

    # 使用配置好的信息创建OSS客户端
    client = oss.Client(cfg)

    # 使用创建好的client执行后续操作...

# 当此脚本被直接运行时，调用main函数
if __name__ == "__main__":
    main()  # 脚本入口，当文件被直接运行时调用main函数

自定义域名配置示例

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

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

警告

您需要先将自定义域名绑定至Bucket默认域名，否则将引发报错！关于绑定自定义域名的详细操作，请参见绑定自定义域名至Bucket默认域名。

import alibabacloud_oss_v2 as oss

def main():
    # 从环境变量中加载凭证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 加载SDK的默认配置，并设置凭证提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    cfg.region = 'cn-hangzhou'

    # 请填写您的自定义域名。例如www.example-***.com
    cfg.endpoint = 'https://www.example-***.com'

    # 请注意，设置true开启CNAME选项，否则无法使用自定义域名
    cfg.use_cname = True

    # 使用配置好的信息创建OSS客户端
    client = oss.Client(cfg)

    # 使用创建好的client执行后续操作...

# 当此脚本被直接运行时，调用main函数
if __name__ == "__main__":
    main()  # 脚本入口，当文件被直接运行时调用main函数

传输加速域名配置示例

以下是使用传输加速域名配置OSSClient的示例代码。

import alibabacloud_oss_v2 as oss

def main():
    # 从环境变量中加载凭证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 加载SDK的默认配置，并设置凭证提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 方式一： 填写Region并设置use_accelerate_endpoint为true
    # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    cfg.region = 'cn-hangzhou'
    cfg.use_accelerate_endpoint = True

    # # 方式二： 直接填写Region和传输加速Endpoint
    # # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    # cfg.region = 'cn-hangzhou'
    # # 填写Bucket所在地域对应的传输加速Endpoint。以华东1（杭州）为例，Endpoint填写为'https://oss-accelerate.aliyuncs.com'
    # cfg.endpoint = 'https://oss-accelerate.aliyuncs.com'

    # 使用配置好的信息创建OSS客户端
    client = oss.Client(cfg)

    # 使用创建好的client执行后续操作...

# 当此脚本被直接运行时，调用main函数
if __name__ == "__main__":
    main()  # 脚本入口，当文件被直接运行时调用main函数

专有域配置示例

以下是使用专有域配置OSSClient的示例代码。

import alibabacloud_oss_v2 as oss

def main():
    # 从环境变量中加载凭证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 加载SDK的默认配置，并设置凭证提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    cfg.region = 'cn-hangzhou'

    # 请填写您的专有域。例如：https://service.corp.example.com
    cfg.endpoint = 'https://service.corp.example.com'

    # 使用配置好的信息创建OSS客户端
    client = oss.Client(cfg)

    # 使用创建好的client执行后续操作...

# 当此脚本被直接运行时，调用main函数
if __name__ == "__main__":
    main()  # 脚本入口，当文件被直接运行时调用main函数

连接超时配置示例

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

import alibabacloud_oss_v2 as oss
from typing import Dict, Any

def main():
    # 从环境变量中加载凭证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 加载默认的配置信息
    cfg = oss.config.load_default()

    # 设置建立连接的超时时间, 默认值 10秒
    cfg.connect_timeout = 30

    # 设置应用读写数据的超时时间, 默认值 20秒
    cfg.readwrite_timeout = 30

    # 设置凭证提供者
    cfg.credentials_provider = credentials_provider

    # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    cfg.region = 'cn-hangzhou'

    # 使用配置好的信息创建OSS客户端
    client = oss.Client(cfg)

    # 使用创建好的client执行后续操作...

# 当此脚本被直接运行时，调用main函数
if __name__ == "__main__":
    main()  # 脚本入口，当文件被直接运行时调用main函数

HTTPClient配置示例

当常用配置参数无法满足场景需求时，您可以使用cfg.http_client替换默认的 HTTP 客户端。

import alibabacloud_oss_v2 as oss
from typing import Dict, Any

def main():
    # 从环境变量中加载凭证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 加载默认的配置信息
    cfg = oss.config.load_default()

    # 设置HTTP客户端的参数
    kwargs: Dict[str, Any] = {}

    # 设置最大连接数，默认值 20
    kwargs["max_connections"] = 100

    # 创建HTTP客户端，并传入关键字参数
    cfg.http_client = oss.transport.RequestsHttpClient(**kwargs)

    # 设置凭证提供者
    cfg.credentials_provider = credentials_provider

    # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
    cfg.region = 'cn-hangzhou'

    # 使用配置好的信息创建OSS客户端
    client = oss.Client(cfg)

    # 使用创建好的client执行后续操作...


# 当此脚本被直接运行时，调用main函数
if __name__ == "__main__":
    main()  # 脚本入口，当文件被直接运行时调用main函数

配置参数汇总

参数名	说明	示例

参数名	说明	示例
region	(必选)请求发送的区域, 必选	oss.config.Config(region="cn-hangzhou")
credentials_provider	(必选)设置访问凭证	oss.config.Config(credentials_provider=provider)
endpoint	访问域名	oss.config.Config(endpoint="oss-cn-hangzhou.aliyuncs.com")
http_client	HTTP客户端	oss.config.Config(http_client=customClient)
retry_max_attempts	HTTP请求时的最大尝试次数, 默认值为 3	oss.config.Config(retry_max_attempts=5)
retryer	HTTP请求时的重试实现	oss.config.Config(retryer=customRetryer)
connect_timeout	建立连接的超时时间, 默认值为 10 秒	oss.config.Config(connect_timeout=20)
readwrite_timeout	应用读写数据的超时时间, 默认值为 20 秒	oss.config.Config(readwrite_timeout=30)
insecure_skip_verify	是否跳过SSL证书校验，默认检查SSL证书	oss.config.Config(insecure_skip_verify=true)
enabled_redirect	是否开启HTTP重定向, 默认不开启	oss.config.Config(enabled_redirect=true)
proxy_host	设置代理服务器	oss.config.Config(proxy_host="http://user:passswd@proxy.example-***.com")
signature_version	签名版本，默认值为v4	oss.config.Config(signature_version="v1")
disable_ssl	不使用https请求，默认使用https	oss.config.Config(disable_ssl=true)
use_path_style	使用路径请求风格，即二级域名请求风格，默认为bucket托管域名	oss.config.Config(use_path_style=true)
use_cname	是否使用自定义域名访问，默认不使用	oss.config.Config(use_cname=true)
use_dualstack_endpoint	是否使用双栈域名访问，默认不使用	oss.config.Config(use_dualstack_endpoint=true)
use_accelerate_endpoint	是否使用传输加速域名访问，默认不使用	oss.config.Config(use_accelerate_endpoint=true)
use_internal_endpoint	是否使用内网域名访问，默认不使用	oss.config.Config(use_internal_endpoint=true)
disable_upload_crc64_check	上传时关闭CRC64校验，默认开启CRC64校验	oss.config.Config(disable_upload_crc64_check=true)
disable_download_crc64_check	下载时关闭CRC64校验，默认开启CRC64校验	oss.config.Config(disable_download_crc64_check=true)
additional_headers	指定额外的签名请求头，V4签名下有效	oss.config.Config(additional_headers=["content-length"])
user_agent	指定额外的User-Agent信息	oss.config.Config(user_agent="user identifier")

常见问题

如果您希望通过与OSS同地域的其他阿里云产品访问OSS，如何提升传输速度？

当您的使用场景对上传速度有要求时，建议您通过与OSS同地域的其他阿里云产品（如ECS服务器）访问OSS，并且请改成使用内网 Endpoint进行访问，请参见 ECS实例通过OSS内网地址访问OSS资源。

如何查看RAM用户的AK信息？

如需查看RAM用户的AK，请直接登录RAM控制台选择具体用户查看AK信息。
RAM用户的AccessKey Secret仅在创建时显示，之后无法查看，若已经遗忘了的话无法找回。您可以直接访问RAM控制台选择具体用户，并创建新的AccessKey进行轮换。具体操作请参见创建AccessKey。

如果遇到报错问题该如何查询具体的错误类型？

关于错误类型的查询，OSS文档提供了EC错误码供您参阅，例如关于认证方面的常见报错问题，可参见02-AUTH。

Python配置客户端

注意事项

前置条件

默认配置示例

常见场景配置示例

内网域名配置示例

自定义域名配置示例

传输加速域名配置示例

专有域配置示例

连接超时配置示例

HTTPClient配置示例

配置参数汇总

常见问题

如果您希望通过与OSS同地域的其他阿里云产品访问OSS，如何提升传输速度？

如何查看RAM用户的AK信息？

如果遇到报错问题该如何查询具体的错误类型？

相关文档