对象存储 OSS：OSS Python SDK V1

准备环境

yum install python-devel

yum install python-devel

yum install python-devel

apt-get install python-dev

apt-get install python-dev

安装SDK

根据开发环境选择合适的安装方式。建议使用最新版本的SDK，确保代码示例正常运行。

配置访问凭证

使用 RAM 用户的 AccessKey 配置访问凭证。

1. 在 RAM 控制台，创建使用永久 AccessKey 访问的 RAM 用户，保存 AccessKey，然后为该用户授予 AliyunOSSFullAccess 权限。

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

   Linux

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

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

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

      source ~/.bashrc

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

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

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

      echo $SHELL

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

      Zsh

      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

      Bash

      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

   Windows

   CMD

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

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

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

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   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)

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

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

初始化客户端

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

• oss2.Service类用于列举存储空间，不支持自定义域名访问。

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

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

# OSS Python SDK V1 初始化客户端示例代码

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():

    # 从环境变量中加载访问凭证（需要设置OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    # 设置OSS服务地域
    region = "cn-hangzhou"
    # 设置Endpoint，以华东1（杭州）的外网访问Endpoint为例
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    # 设置Bucket名称
    bucket_name = "example-bucket"

    # 初始化OSS Bucket实例
    bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
    
    # 列举Bucket下的文件列表
    print("=== 列举Bucket下的文件 ===")
    try:
        # 使用list_objects方法列举文件
        result = bucket.list_objects()
        
        # 遍历文件列表，只输出文件名
        for obj in result.object_list:
            print(obj.key)
        
        # 输出统计信息
        print(f"\n共列举文件数: {len(result.object_list)}")
        if result.is_truncated:
            print("注意: 结果被截断，还有更多文件未列出")
            
    except oss2.exceptions.OssError as e:
        print(f"OSS错误: {e}")
        raise
    except Exception as e:
        print(f"发生错误: {e}")
        raise


if __name__ == "__main__":
    # 程序入口点
    try:
        main()
    except Exception as e:
        print(f"运行过程中发生错误: {e}")
        raise

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

# OSS Python SDK V1 初始化Service客户端示例代码

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():

    # 从环境变量中加载访问凭证（需要设置OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    # 设置OSS服务地域
    region = "cn-hangzhou"
    # 设置Endpoint，以华东1（杭州）的外网访问Endpoint为例
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

    # 初始化OSS Service实例
    service = oss2.Service(auth, endpoint, region=region)
    
    # 列举所有Bucket
    print("=== 列举所有Bucket ===")
    try:
        # 使用BucketIterator列举Bucket
        buckets = [b.name for b in oss2.BucketIterator(service)]
        
        # 遍历Bucket列表，只输出Bucket名称
        for bucket in buckets:
            print(bucket)
        
        # 输出统计信息
        print(f"\n共列举Bucket数: {len(buckets)}")
            
    except oss2.exceptions.OssError as e:
        print(f"OSS错误: {e}")
        raise
    except Exception as e:
        print(f"发生错误: {e}")
        raise


if __name__ == "__main__":
    # 程序入口点
    try:
        main()
    except Exception as e:
        print(f"运行过程中发生错误: {e}")
        raise

使用内网域名

初始化OSS客户端时，将Endpoint指定为内网访问域名即可实现内网访问。

# 以华东1（杭州）的内网访问Endpoint为例
endpoint = "oss-cn-hangzhou-internal.aliyuncs.com"

# 初始化OSS客户端实例
bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)

使用自定义域名

将Endpoint指定为自定义域名，并在初始化客户端时通过is_cname=True参数启用CNAME选项，即可实现自定义域名访问。

使用自定义域名前，需确保已将自定义域名绑定到Bucket。具体操作参见通过自定义域名访问OSS。

# 设置自定义域名
endpoint = "http://example.com"

# 初始化OSS客户端实例
bucket = oss2.Bucket(auth, endpoint, bucket_name, is_cname=True, region=region)

超时控制

初始化OSS客户端时，使用connect_timeout参数设置超时时长，单位为秒，默认值为60秒。

# 初始化OSS Bucket实例
bucket = oss2.Bucket(auth, endpoint, bucket_name, connect_timeout=30, region=region)

设置连接池大小

初始化OSS客户端时，通过配置session的pool_size参数调整连接池大小。

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

# 初始化OSS Bucket实例
bucket = oss2.Bucket(auth, endpoint, bucket_name, session=session, region=region)

指定TLS版本

可通过自定义SSLAdapter创建Session来指定特定的TLS版本。

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

import ssl
from requests.adapters import HTTPAdapter

# 自定义适配器，用于指定TLS版本
class SSLAdapter(HTTPAdapter):
    def init_poolmanager(self, *args, **http_client_config):
        # 指定TLS版本为1.2
        http_client_config["ssl_version"] = ssl.PROTOCOL_TLSv1_2
        return super(SSLAdapter, self).init_poolmanager(*args, **http_client_config)
        
# 通过SSLAdapter创建Session
session = oss2.Session(adapter=SSLAdapter())

# 初始化OSS Bucket实例
bucket = oss2.Bucket(auth, endpoint, bucket_name, session=session, region=region)

关闭CRC数据校验

可通过enable_crc=False参数关闭CRC数据校验功能。

# 初始化OSS Bucket实例
bucket = oss2.Bucket(auth, endpoint, bucket_name, enable_crc=False, region=region)

签名版本

以下示例代码采用V1签名初始化客户端。V4签名客户端初始化示例代码参见初始化客户端。

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

# OSS Python SDK V1 初始化客户端示例代码

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():

    # 从环境变量中加载访问凭证（需要设置OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

    # 设置Endpoint，以华东1（杭州）的外网访问Endpoint为例
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    # 设置Bucket名称
    bucket_name = "example-bucket"

    # 初始化OSS Bucket实例
    bucket = oss2.Bucket(auth, endpoint, bucket_name)
    
    # 列举Bucket下的文件列表
    print("=== 列举Bucket下的文件 ===")
    try:
        # 使用list_objects方法列举文件
        result = bucket.list_objects()
        
        # 遍历文件列表，只输出文件名
        for obj in result.object_list:
            print(obj.key)
        
        # 输出统计信息
        print(f"\n共列举文件数: {len(result.object_list)}")
        if result.is_truncated:
            print("注意: 结果被截断，还有更多文件未列出")
            
    except oss2.exceptions.OssError as e:
        print(f"OSS错误: {e}")
        raise
    except Exception as e:
        print(f"发生错误: {e}")
        raise


if __name__ == "__main__":
    # 程序入口点
    try:
        main()
    except Exception as e:
        print(f"运行过程中发生错误: {e}")
        raise

自定义应用名

通过设置应用名可在User Agent中添加自定义标识。初始化OSS客户端时，通过app_name参数设置应用名称，默认为空。

应用名称作为HTTP Header值进行传输，必须符合HTTP标准规范。

# 初始化OSS Bucket实例
bucket = oss2.Bucket(auth, endpoint, bucket_name, app_name="client_test", region=region)

使用RAM用户的AK

适用于应用程序部署运行在安全、稳定且不易受外部攻击的环境中，需要长期访问OSS且无法频繁轮转凭证的场景。通过阿里云主账号或RAM用户的AK（Access Key ID、Access Key Secret）初始化凭证提供者。该方式需要手动维护AK，存在安全性风险和维护复杂度增加的风险。

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

# OSS Python SDK V1 初始化客户端示例代码

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():

    # 填写RAM用户的AccessKey ID和AccessKey Secret
    access_key_id = 'yourAccessKeyID'
    access_key_secret = 'yourAccessKeySecret'
    # 使用RAM用户的访问密钥配置访问凭证
    auth = oss2.AuthV4(access_key_id, access_key_secret)
    # 设置OSS服务地域
    region = "cn-hangzhou"
    # 设置Endpoint，以华东1（杭州）的外网访问Endpoint为例
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    # 设置Bucket名称
    bucket_name = "example-bucket-hz"

    # 初始化OSS Bucket实例
    bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
    
    # 列举Bucket下的文件列表
    print("=== 列举Bucket下的文件 ===")
    try:
        # 使用list_objects方法列举文件
        result = bucket.list_objects()
        
        # 遍历文件列表，只输出文件名
        for obj in result.object_list:
            print(obj.key)
        
        # 输出统计信息
        print(f"\n共列举文件数: {len(result.object_list)}")
        if result.is_truncated:
            print("注意: 结果被截断，还有更多文件未列出")
            
    except oss2.exceptions.OssError as e:
        print(f"OSS错误: {e}")
        raise
    except Exception as e:
        print(f"发生错误: {e}")
        raise


if __name__ == "__main__":
    # 程序入口点
    try:
        main()
    except Exception as e:
        print(f"运行过程中发生错误: {e}")
        raise

使用STS临时访问凭证

适用于应用程序需要临时访问OSS的场景。通过STS服务获取的临时身份凭证（Access Key ID、Access Key Secret和Security Token）初始化凭证提供者。该方式需要手动维护STS Token，存在安全性风险和维护复杂度增加的风险。如果需要多次临时访问OSS，需要手动刷新STS Token。

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

# 填写获取的临时访问密钥AccessKey ID和AccessKey Secret，非阿里云账号AccessKey ID和AccessKey Secret。
# 请注意区分STS服务获取的Access Key ID是以STS开头，如下所示。
sts_access_key_id = 'STS.****************'
sts_access_key_secret = 'yourAccessKeySecret'
# 填写获取的STS安全令牌（SecurityToken）。
security_token = 'yourSecurityToken'

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

# yourBucketName填写存储空间名称。
bucket_name = 'yourBucketName'

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

# 初始化StsAuth实例。注意，auth_version设置为"v4"，表示使用OSS V4版本签名。
auth = oss2.StsAuth(sts_access_key_id,
                    sts_access_key_secret,
                    security_token,
                    auth_version="v4")

# 使用StsAuth实例初始化bucket。注意，使用V4签名时，region参数必须指定，否则会报错。
bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)

# 使用bucket对象进行后续操作...

使用RAMRoleARN

适用于应用程序需要授权访问OSS，例如跨阿里云账号访问OSS的场景。通过指定RAM角色的ARN（Alibabacloud Resource Name）初始化凭证提供者，底层实现基于STS Token。Credentials工具会前往STS服务获取STS Token，并在会话到期前调用AssumeRole接口申请新的STS Token。还可以通过为policy赋值来限制RAM角色到一个更小的权限集合。

1. 添加credentials依赖。

   pip install alibabacloud_credentials

2. 配置AK和RAMRoleARN作为访问凭证。

   # -*- coding: utf-8 -*-
   import oss2
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   import os
   
   
   class CredentialProviderWrapper(CredentialsProvider):
       def __init__(self, client):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           access_key_id = credential.access_key_id
           access_key_secret = credential.access_key_secret
           security_token = credential.security_token
           return Credentials(access_key_id, access_key_secret, security_token)
   
   config = Config(
       # 从环境变量中获取RAM用户的访问密钥（AccessKey ID和AccessKey Secret）
       access_key_id=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
       access_key_secret=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
       type='ram_role_arn',
       # 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置RoleArn
       role_arn='<RoleArn>',
       # 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
       role_session_name='<RoleSessionName>',
       # 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
       policy='<Policy>',
       # 设置角色会话有效期，非必填
       role_session_expiration=3600
   )
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   # 请注意，此处使用ProviderAuthV4表示使用V4签名。
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
   endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
   
   # yourBucketName填写存储空间名称。
   bucket_name = 'yourBucketName'
   
   # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou。
   region = 'cn-hangzhou'
   
   # 使用Auth实例初始化bucket。注意，使用V4签名时，region参数必须指定，否则会报错。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket对象进行后续操作...

使用ECSRAMRole

适用于应用程序运行在ECS实例、ECI实例、容器服务Kubernetes版的Worker节点中的场景。建议使用ECSRAMRole初始化凭证提供者，底层实现基于STS Token。ECSRAMRole允许将一个角色关联到ECS实例、ECI实例或容器服务 Kubernetes 版的Worker节点，实现在实例内部自动刷新STS Token。该方式无需提供AK或STS Token，消除了手动维护AK或STS Token的风险。如何获取ECSRAMRole，请参见创建角色。如何将一个角色关联到ECS实例，请参见实例RAM角色。

1. 添加credentials依赖。

   pip install alibabacloud_credentials

2. 配置ECSRAMRole作为访问凭证。

   # -*- coding: utf-8 -*-
   import oss2
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   
   
   class CredentialProviderWrapper(CredentialsProvider):
       def __init__(self, client):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           access_key_id = credential.access_key_id
           access_key_secret = credential.access_key_secret
           security_token = credential.security_token
           return Credentials(access_key_id, access_key_secret, security_token)
   
   
   config = Config(
       type='ecs_ram_role',      # 访问凭证类型。固定为ecs_ram_role。
       role_name='<RoleName>'    # 为ECS授予的RAM角色的名称。可选参数。如果不设置，将自动检索。强烈建议设置，以减少请求。
   )
   
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   # 请注意，此处使用ProviderAuthV4表示使用V4签名。
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
   endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
   
   # yourBucketName填写存储空间名称。
   bucket_name = 'yourBucketName'
   
   # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou。
   region = 'cn-hangzhou'
   
   # 使用Auth实例初始化bucket。注意，使用V4签名时，region参数必须指定，否则会报错。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket对象进行后续操作...

使用OIDCRoleARN

在容器服务Kubernetes版中设置了Worker节点RAM角色后，对应节点内的Pod中的应用也可以像ECS上部署的应用一样，通过元数据服务（Meta Data Server）获取关联角色的STS Token。但如果容器集群上部署的是不可信的应用（比如部署客户提交的应用，代码也没有开放），可能并不希望它们能通过元数据服务获取Worker节点关联实例RAM角色的STS Token。为了避免影响云上资源的安全，同时又能让这些不可信的应用安全地获取所需的STS Token，实现应用级别的权限最小化，可以使用RRSA（RAM Roles for Service Account）功能。该方式底层实现基于STS Token。阿里云容器集群会为不同的应用Pod创建和挂载相应的服务账户OIDC Token文件，并将相关配置信息注入到环境变量中，Credentials工具通过获取环境变量的配置信息，调用STS服务的AssumeRoleWithOIDC接口换取绑定角色的STS Token。该方式无需提供AK或STS Token，消除了手动维护AK或STS Token的风险。详情请参见通过RRSA配置ServiceAccount的RAM权限实现Pod权限隔离。

1. 添加credentials依赖。

   pip install alibabacloud_credentials

2. 配置OIDC的RAM角色作为访问凭证。

   # -*- coding: utf-8 -*-
   import oss2
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   import os
   
   
   class CredentialProviderWrapper(CredentialsProvider):
       def __init__(self, client):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           access_key_id = credential.access_key_id
           access_key_secret = credential.access_key_secret
           security_token = credential.security_token
           return Credentials(access_key_id, access_key_secret, security_token)
   
   
   config = Config(
       # 指定Credential类型，固定值为oidc_role_arn。
       type='oidc_role_arn',
       # RAM角色名称ARN，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置RoleArn
       role_arn=os.environ.get('<RoleArn>'),
       # OIDC提供商ARN，可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置OidcProviderArn
       oidc_provider_arn=os.environ.get('<OidcProviderArn>'),
       # OIDC Token文件路径，可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置OidcTokenFilePath
       oidc_token_file_path=os.environ.get('<OidcTokenFilePath>'),
       # 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
       role_session_name='<RoleSessionName>',
       # 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
       policy='<Policy>',
       # 设置session过期时间
       role_session_expiration=3600
   )
   
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   # 请注意，此处使用ProviderAuthV4表示使用V4签名。
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
   endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
   
   # yourBucketName填写存储空间名称。
   bucket_name = 'yourBucketName'
   
   # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou。
   region = 'cn-hangzhou'
   
   # 使用Auth实例初始化bucket。注意，使用V4签名时，region参数必须指定，否则会报错。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket对象进行后续操作...

使用函数计算上下文中的Credentials

适用于应用程序的函数部署运行在函数计算中的场景。可以使用函数计算上下文中的Credentials初始化凭证提供者，底层实现基于STS Token。函数计算根据函数配置的角色，通过扮演服务角色获取一个STS Token，然后通过上下文中的参数Credentials将STS Token传递给应用程序。该STS Token的有效期为36小时，且不支持修改。函数的最大执行时间为24小时，因此，执行函数过程中，STS Token不会过期，无需考虑刷新问题。该方式无需提供AK或STS Token，消除了手动维护AK或STS Token的风险。如何授予函数计算访问OSS的权限，请参见使用函数角色授予函数计算访问其他云服务的权限。

使用函数计算上下文中的Credentials初始化凭证提供者示例代码如下：

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


def handler(event, context):

    class CredentialProviderWrapper(CredentialsProvider):
        def get_credentials(self):
            creds = context.credentials
            return Credentials(creds.access_key_id, creds.access_key_secret, creds.security_token)

    credentials_provider = CredentialProviderWrapper()
    # 请注意，此处使用ProviderAuthV4表示使用V4签名。
    auth = oss2.ProviderAuthV4(credentials_provider)

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

    # yourBucketName填写存储空间名称。
    bucket_name = 'yourBucketName'

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

    # 使用Auth实例初始化bucket。注意，使用V4签名时，region参数必须指定，否则会报错。
    bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)

    # 使用bucket对象进行后续操作...

    return 'success'

使用CredentialsURI

适用于应用程序需要通过外部系统获取阿里云凭证，从而实现灵活的凭证管理和无密钥访问的场景。可以使用CredentialsURI初始化凭证提供者，底层实现基于STS Token。Credentials工具通过提供的URI获取STS Token，完成凭证客户端初始化。该方式无需提供AK或STS Token，消除了手动维护AK或STS Token的风险。

1. 为了使Credentials工具正确解析和使用STS Token，URI必须遵循以下响应协议：

   • 响应状态码：200

   • 响应体结构：

     {
         "Code": "Success",
         "AccessKeySecret": "AccessKeySecret",
         "AccessKeyId": "AccessKeyId",
         "Expiration": "2021-09-26T03:46:38Z",
         "SecurityToken": "SecurityToken"
     }

2. 添加credentials依赖。

   pip install alibabacloud_credentials

3. 配置CredentialsURI作为访问凭证。

   # -*- coding: utf-8 -*-
   import oss2
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   
   
   class CredentialProviderWrapper(CredentialsProvider):
       def __init__(self, client):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           access_key_id = credential.access_key_id
           access_key_secret = credential.access_key_secret
           security_token = credential.security_token
           return Credentials(access_key_id, access_key_secret, security_token)
   
   
   config = Config(
       type='credentials_uri',
       # 凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置CredentialsUri
       credentials_uri='<CredentialsUri>',
   )
   
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   # 请注意，此处使用ProviderAuthV4表示使用V4签名。
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
   endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
   
   # yourBucketName填写存储空间名称。
   bucket_name = 'yourBucketName'
   
   # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou。
   region = 'cn-hangzhou'
   
   # 使用Auth实例初始化bucket。注意，使用V4签名时，region参数必须指定，否则会报错。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket对象进行后续操作...

使用自动轮转的AK

适用于应用程序需要长期访问OSS，但部署运行的环境面临AK泄露风险，需要频繁手动轮转（轮换）AK的场景。可以使用ClientKey初始化凭证提供者，底层实现基于AK。使用ClientKey后，密钥管理服务（KMS）可以对托管的RAM用户AK进行全自动的定期轮转，将静态的RAM用户AK动态化，从而降低AK泄漏的风险。除定期轮转外，KMS还支持立即轮转，在AK泄漏情况下快速更换AK。该方式无需手动维护AK，从而降低安全性风险和维护复杂度。如何获取ClientKey，请参见创建应用接入点。

1. 添加凭据客户端依赖。

   pip install aliyun-secret-manager-client

2. 创建配置文件secretsmanager.properties。

   # 访问凭据类型，固定为client_key
   credentials_type=client_key
   
   # 读取Client Key的解密密码：支持从环境变量或者文件读取，只需设置一种
   client_key_password_from_env_variable=<your client key private key password environment variable name>
   client_key_password_from_file_path=<your client key private key password file path>
   
   # Client Key的私钥文件路径
   client_key_private_key_path=<your client key private key file path>
   
   # 关联的KMS服务地域
   cache_client_region_id=[{"regionId":"<regionId>"}]

3. 使用配置文件传递凭证信息。

   # -*- coding: utf-8 -*-
   import json
   import oss2
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   from alibaba_cloud_secretsmanager_client.secret_manager_cache_client_builder import SecretManagerCacheClientBuilder
   
   
   class CredentialProviderWrapper(CredentialsProvider):
       def get_credentials(self):
           secret_cache_client = SecretManagerCacheClientBuilder.new_client()
           secret_info = secret_cache_client.get_secret_info("<secretName>")
           secret_value_json = json.loads(secret_info.secret_value)
           return Credentials(secret_value_json["AccessKeyId"], secret_value_json["AccessKeySecret"])
   
   
   credentials_provider = CredentialProviderWrapper()
   
   # 请注意，此处使用ProviderAuthV4表示使用V4签名。
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
   endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
   
   # yourBucketName填写存储空间名称。
   bucket_name = 'yourBucketName'
   
   # 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou。
   region = 'cn-hangzhou'
   
   # 使用Auth实例初始化bucket。注意，使用V4签名时，region参数必须指定，否则会报错。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket对象进行后续操作...

使用自定义访问凭证

当以上凭证配置方式都不满足要求时，可以通过实现Credential Providers接口的方式自定义凭证提供方式。需要注意，如果底层实现基于STS Token，需要提供凭证的更新支持。

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


class CredentialProviderWrapper(CredentialsProvider):
    def get_credentials(self):
        # TODO
        # 自定义访问凭证的获取方法

        # 返回长期凭证access_key_id, access_key_secrect
        return Credentials('<access_key_id>', '<access_key_secrect>')

        # 返回 临时凭证access_key_id, access_key_secrect, token
        # 对于临时凭证，需要根据过期时间，刷新凭证。
        # return Credentials('<access_key_id>', '<access_key_secrect>', '<token>');


credentials_provider = CredentialProviderWrapper()

# 请注意，此处使用ProviderAuthV4表示使用V4签名。
auth = oss2.ProviderAuthV4(credentials_provider)

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

# yourBucketName填写存储空间名称。
bucket_name = 'yourBucketName'

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

# 使用Auth实例初始化bucket。注意，使用V4签名时，region参数必须指定，否则会报错。
bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)

# 使用bucket对象进行后续操作...

报错No module named _crcfunext？

使用OSS Python SDK V1调用上传、下载接口较其他工具如ossutil或其他SDK慢。

• 问题原因：

  编译crcmod时，由于_crcfunext.so依赖Python.h文件，而系统中缺少该头文件，导致_crcfunext.so库生成失败。关于crcmod的更多信息，请参见crcmod introduction。

• 解决方法：

  验证crcmod的C扩展模式是否安装成功。

  1. 执行以下命令进入Python环境。

     python

  2. 执行以下命令导入crcmod模块下的_crcfunext的C扩展模块。

     import crcmod._crcfunext

     出现以下错误提示，表明crcmod库的C扩展模式安装失败。

     Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     ImportError: No module named _crcfunext                                 

  3. 根据系统环境选择解决方案。

     Windows

     1. 下载crcmod-1.7.win32-py2.7.msi或者其他版本的.msi文件。

        说明

        win32位的crcmod同时兼容win32和win64系统。

     2. 安装.msi文件并在安装过程中指定crcmod的安装路径到本地python安装路径下的Lib\site-packages文件夹。例如D:\python\Lib\site-packages\。

     3. 安装完成后，重新执行验证crcmod的步骤。

     Linux

     Linux系统出现该问题时，执行以下步骤：

     1. 执行以下命令卸载crcmod。

        pip uninstall crcmod

     2. 安装python-devel。具体操作，请参见准备环境。

     3. 执行以下命令重新安装crcmod。

        pip install crcmod

        如果执行上述步骤仍然安装失败，卸载crcmod，然后执行以下命令查看安装失败的详细原因。

        pip install crcmod -v

报错No module named 'Crypto'？

• 问题原因：

  系统中不存在Crypto模块或存在crypto模块（首字母小写）。

• 解决方法：

  检查本地Python安装路径下的Crypto模块，例如D:\python3.9\Lib\site-packages。

  • 如果不存在Crypto模块，执行以下命令。

    python -m pip install --upgrade setuptools

  • 如果存在crypto模块（首字母小写），将首字母改为大写，然后重新启动程序。

提示“不是内部或外部命令”？

Windows环境中，如果提示"不是内部或外部命令"，需要在环境变量中编辑Path，增加Python和pip的安装路径。pip的安装路径通常为Python所在目录的Scripts文件夹。编辑环境变量后，可能需要重启计算机使环境变量生效。

安装OSS Python SDK V1失败？

如果安装OSS Python SDK V1失败，执行以下命令卸载后重新安装。

pip uninstall oss2            

如何升级OSS Python SDK V1？

执行以下命令升级OSS Python SDK V1。

 pip install --upgrade oss2

当使用SDK时遇到报错AccessDenied该如何进行排查？

遇到AccessDenied错误通常是因为缺少相应的访问权限。排查步骤如下：

1. 确认AccessKey ID和AccessKey Secret：确保使用了正确的AccessKey ID和AccessKey Secret。

2. 检查RAM用户权限：确认RAM用户是否拥有Bucket或Object相关操作权限。

3. 检查Bucket Policy：如果错误信息中提到"Access denied by bucket policy"，表明访问被Bucket Policy策略拒绝。

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

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

如何查看RAM用户的AK，是否可以查看旧的AccessKey Secret？

1. 查看RAM用户的AK：直接登录RAM控制台选择具体用户查看AK信息。

2. RAM用户的AccessKey Secret仅在创建时显示，之后无法查看，遗忘后无法找回。可以直接访问RAM控制台选择具体用户，创建新的AccessKey进行轮换。具体操作请参见创建AccessKey。