最低Python版本
请注意，V2版本要求Python版本最低为3.8。
导入路径
V2版本使用新的代码仓库(alibabacloud-oss-python-sdk-v2)，同时也对代码结构进行了调整，按照功能模块组织，以下是这些模块路径和说明：
模块路径 | 说明 |
alibabacloud_oss_v2 | SDK核心，接口 和 高级接口实现 |
alibabacloud_oss_v2.credentials | 访问凭证相关 |
alibabacloud_oss_v2.retry | 重试相关 |
alibabacloud_oss_v2.signer | 签名相关 |
alibabacloud_oss_v2.transport | HTTP客户端相关 |
alibabacloud_oss_v2.crypto | 客户端加密相关 |
V2版示例
import alibabacloud_oss_v2
配置加载
V2 版本简化了配置设置方式，全部迁移到 config下，可以以编程方式覆盖缺省配置。
V2 默认使用 V4签名，所以必须配置区域（Region）。
V2 支持从区域（Region）信息构造访问域名(Endpoint), 当访问的是公网域名时，可以不设置Endpoint。
V1版示例
from oss2 import http
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"
bucket = oss2.Bucket(auth, endpoint, "example_bucket", region=region, connect_timeout=(20, 60))
V2版示例
import alibabacloud_oss_v2 as oss
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
cfg.connect_timeout = 20
cfg.readwrite_timeout = 60
cfg.insecure_skip_verify = True
cfg.region = "cn-hangzhou"
client = oss.Client(cfg)
创建Client
V2 版本把Client的创建函数从Bucket包修改为Client包。
V1版示例
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)
调用API操作
基础API接口都合并为单一操作方法'<OperationName>'，操作的请求参数为'<OperationName>Request'，操作的返回值为'<OperationName>Result'。这些操作方法都迁移到Client下。如下格式：
def <OperationName>(self, request: models.<OperationName>Request, **kwargs) -> models.<OperationName>Result:
关于API接口的详细使用说明，请参考基础接口。
V1版示例
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"
bucket = oss2.Bucket(auth, endpoint, "example_bucket", region=region)
result = bucket.put_object('exampleobject.txt', 'example data')
V2版示例
import alibabacloud_oss_v2 as oss
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
cfg = oss.config.load_default()
cfg.region = "cn-hangzhou"
cfg.credentials_provider = credentials_provider
client = oss.Client(cfg)
result = client.put_object(oss.PutObjectRequest(
bucket="example_bucket",
key="exampleobject.txt",
body="example data",
))
预签名
V2版本把预签名接口名字从SignURL修改为Presign，同时把接口迁移到Client下。接口形式如下：
def presign(self, request: PresignRequest, **kwargs) -> PresignResult:
对于request参数，其类型与API接口中的'<OperationName>Request'一致。
对于返回结果，除了返回预签名URL外，还返回HTTP方法，过期时间和被签名的请求头，如下：
class PresignResult:
def __init__(
self,
method: Optional[str] = None,
url: Optional[str] = None,
expiration: Optional[datetime.datetime] = None,
signed_headers: Optional[MutableMapping] = None,
) -> None:
self.method = method
self.url = url
self.expiration = expiration
self.signed_headers = signed_headers
关于预签名的详细使用说明，请参考预签名接口。
以生成下载对象的预签名URL为例，如何从V1迁移到V2。
V1版示例
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"
bucket = oss2.Bucket(auth, endpoint, "example_bucket", region=region)
object_name = "exampleobject.txt"
url = bucket.sign_url("GET", object_name, 60, slash_safe=True)
print('预签名URL的地址为：', url)
V2版示例
import datetime
from typing import Dict, Any
import requests
import alibabacloud_oss_v2 as oss
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
cfg.region = "cn-hangzhou"
client = oss.Client(cfg)
kwargs: Dict[str, Any] = {}
kwargs["expires"] = datetime.timedelta(minutes=10)
pre_result = client.presign(oss.GetObjectRequest(
bucket="example_bucket",
key="exampleobject.txt",
), **kwargs)
print(f'url: {pre_result.url}')
断点续传接口
V2版本使用传输管理器'Uploader'，'Downloader' 和'Copier'分别管理对象的上传，下载和拷贝。 同时移除了原有的断点续传接口Bucket.UploadFile，Bucket.DownloadFile和Bucket.CopyFile。
接口对比如下：
使用场景 | v2 | v1 |
上传文件 | Uploader.upload_file | bucket.put_object_from_file |
上传流 | Uploader.upload_from | 不支持 |
下载到文件 | Downloader.download_file | bucket.get_object_to_file |
拷贝对象 | Copier.copy | bucket.copy_object |
默认参数的变化：
场景 | v2 | v1 |
上传-分片默认值 | 6 MiB | 通过参数设置 |
上传-并发默认值 | 3 | 1 |
上传-阈值 | 分片大小 | 无 |
上传-记录checkpoint | 支持 | 支持 |
下载-分片默认值 | 6 MiB | 通过参数设置 |
下载-并发默认值 | 3 | 1 |
下载-阈值 | 分片大小 | 无 |
下载-记录checkpoint | 支持 | 支持 |
拷贝-分片默认值 | 64 MiB | 无 |
拷贝-并发默认值 | 3 | 1 |
拷贝-阈值 | 200 MiB | 无 |
拷贝-记录checkpoint | 不支持 | 支持 |
说明
表格中的阈值（上传/下载拷贝）表示对象/文件大小大于该值时，使用分片方式（上传/下载/拷贝）。
关于传输管理器的详细使用说明，请参考传输管理器。
客户端加密
V2版本使用EncryptionClient来提供客户端加密功能，同时也对API 接口做了精简，采用了和Client一样的接口命名规则和调用方式。另外，该版本仅保留基于RSA自主管理的主密钥的参考实现。
对于KMS的实现，可以参考sample/encryption_kms.py。
关于客户端加密的详细使用说明，请参考客户端加密。
下面以使用主密钥RSA上传对象为例，展示如何从 V1 迁移到 V2。
V1版本
import os
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.crypto import RsaProvider
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
key_pair = {'private_key': 'yourPrivateKey', 'public_key': 'yourPublicKey'}
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"
bucket = oss2.CryptoBucket(auth, endpoint, 'example_bucket',
crypto_provider=RsaProvider(key_pair), region=region)
bucket.put_object('exampleobject.txt', 'example data')
V2版本
import argparse
import alibabacloud_oss_v2 as oss
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
cfg.region = "cn-hangzhou"
client = oss.Client(cfg)
mc = oss.crypto.MasterRsaCipher(
mat_desc={"desc": "your master encrypt key material describe information"},
public_key="yourRsaPublicKey",
private_key="yourRsaPrivateKey"
)
encryption_client = oss.EncryptionClient(client, mc)
data = b'example data'
result = encryption_client.put_object(oss.PutObjectRequest(
bucket="example_bucket",
key="exampleobject.txt",
body=data,
))
重试
V2版本默认开启对HTTP请求的重试行为。从V1版本迁移到V2时，您需要移除原有的重试代码，避免放大重试次数。
相关文档
关于Python SDK V1迁移到V2的更多内容，请参见迁移指南。
