Object Storage Service：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 = "<region-id>"
    # 設定Endpoint
    endpoint = "<endpoint>"
    # 設定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 = "<region-id>"
    # 設定Endpoint
    endpoint = "<endpoint>"

    # 初始化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指定為內網訪問網域名稱即可實現內網訪問。

請將代碼中的 <region-id>預留位置替換為實際的地區和Endpoint，如 ap-southeast-1。

endpoint = "oss-<region-id>-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簽名用戶端初始化範例程式碼參見初始化用戶端。

運行範例程式碼前，請將代碼中的 <endpoint>等預留位置替換為實際的地區和Endpoint，如 https://oss-ap-southeast-1.aliyuncs.com。

#!/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
    endpoint = "<endpoint>"
    # 設定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 = "<region-id>"
    # 設定Endpoint
    endpoint = "<endpoint>"
    # 設定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
endpoint = '<endpoint>'

# yourBucketName填寫儲存空間名稱。
bucket_name = 'yourBucketName'

# 填寫Bucket所在地區
region = '<region-id>'

# 初始化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作為訪問憑證。

   運行範例程式碼前，請將代碼中的 <region-id>等預留位置替換為實際的地區和Endpoint，如 ap-southeast-1。

   # -*- 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
   endpoint = '<endpoint>'
   
   # yourBucketName填寫儲存空間名稱。
   bucket_name = 'yourBucketName'
   
   # 填寫Bucket所在地區
   region = '<region-id>'
   
   # 使用Auth執行個體初始化bucket。注意，使用V4簽名時，region參數必須指定，否則會報錯。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket對象進行後續操作...

使用ECSRAMRole

適用於應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中的情境。建議使用ECSRAMRole初始化憑證提供者，底層實現基於STS Token。ECSRAMRole允許將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點，實現在執行個體內部自動重新整理STS Token。該方式無需提供AK或STS Token，消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole，請參見建立角色。如何將一個角色關聯到ECS執行個體，請參見執行個體RAM角色。

1. 添加credentials依賴。

   pip install alibabacloud_credentials

2. 配置ECSRAMRole作為訪問憑證。

   運行範例程式碼前，請將代碼中的 <region-id>等預留位置替換為實際的地區和Endpoint，如 ap-southeast-1。

   # -*- 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
   endpoint = '<endpoint>'
   
   # yourBucketName填寫儲存空間名稱。
   bucket_name = 'yourBucketName'
   
   # 填寫Bucket所在地區
   region = '<region-id>'
   
   # 使用Auth執行個體初始化bucket。注意，使用V4簽名時，region參數必須指定，否則會報錯。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket對象進行後續操作...

使用OIDCRoleARN

在Container ServiceKubernetes版中設定了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角色作為訪問憑證。

   運行範例程式碼前，請將代碼中的 <region-id>等預留位置替換為實際的地區和Endpoint，如 ap-southeast-1。

   # -*- 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。
   endpoint = '<endpoint>'
   
   # yourBucketName填寫儲存空間名稱。
   bucket_name = 'yourBucketName'
   
   # 填寫Bucket所在地區。
   region = '<region-id>'
   
   # 使用Auth執行個體初始化bucket。注意，使用V4簽名時，region參數必須指定，否則會報錯。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket對象進行後續操作...

使用Function Compute上下文中的Credentials

適用於應用程式的函數部署運行在Function Compute中的情境。可以使用Function Compute上下文中的Credentials初始化憑證提供者，底層實現基於STS Token。Function Compute根據函數配置的角色，通過扮演服務角色擷取一個STS Token，然後通過上下文中的參數Credentials將STS Token傳遞給應用程式。該STS Token的有效期間為36小時，且不支援修改。函數的最大執行時間為24小時，因此，執行函數過程中，STS Token不會到期，無需考慮重新整理問題。該方式無需提供AK或STS Token，消除了手動維護AK或STS Token的風險。如何授予Function Compute訪問OSS的許可權，請參見使用函數角色授予Function Compute訪問其他雲端服務的許可權。

使用Function Compute上下文中的Credentials初始化憑證提供者

運行範例程式碼前，請將代碼中的 <region-id>等預留位置替換為實際的地區和Endpoint，如 ap-southeast-1。

# -*- 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。
    endpoint = '<endpoint>'

    # yourBucketName填寫儲存空間名稱。
    bucket_name = 'yourBucketName'

    # 填寫Bucket所在地區。
    region = '<region-id>'

    # 使用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作為訪問憑證。

   運行範例程式碼前，請將代碼中的 <region-id>等預留位置替換為實際的地區和Endpoint，如 ap-southeast-1。

   # -*- 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。
   endpoint = '<endpoint>'
   
   # yourBucketName填寫儲存空間名稱。
   bucket_name = 'yourBucketName'
   
   # 填寫Bucket所在地區。
   region = '<region-id>'
   
   # 使用Auth執行個體初始化bucket。注意，使用V4簽名時，region參數必須指定，否則會報錯。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket對象進行後續操作...

使用自動輪轉的AK

適用於應用程式需要長期訪問OSS，但部署啟動並執行環境面臨AK泄露風險，需要頻繁手動輪轉（輪換）AK的情境。可以使用ClientKey初始化憑證提供者，底層實現基於AK。使用ClientKey後，Key Management Service（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. 使用設定檔傳遞憑證資訊。

   運行範例程式碼前，請將代碼中的 <region-id>等預留位置替換為實際的地區和Endpoint，如 ap-southeast-1。

   # -*- 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。
   endpoint = '<endpoint>'
   
   # yourBucketName填寫儲存空間名稱。
   bucket_name = 'yourBucketName'
   
   # 填寫Bucket所在地區。
   region = '<region-id>'
   
   # 使用Auth執行個體初始化bucket。注意，使用V4簽名時，region參數必須指定，否則會報錯。
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # 使用bucket對象進行後續操作...

使用自訂訪問憑證

當以上憑證配置方式都不滿足要求時，可以通過實現Credential Providers介面的方式自訂憑證提供方式。需要注意，如果底層實現基於STS Token，需要提供憑證的更新支援。

運行範例程式碼前，請將代碼中的 <region-id>等預留位置替換為實際的地區和Endpoint，如 ap-southeast-1。

# -*- 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。
endpoint = '<endpoint>'

# yourBucketName填寫儲存空間名稱。
bucket_name = 'yourBucketName'

# 填寫Bucket所在地區。
region = '<region-id>'

# 使用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。