Object Storage Service：OSS Python SDK V2

快速接入

環境準備

要求 Python 3.8 及以上版本。

可以通過 Python -version 命令查看 Python 版本。如果當前環境沒有 Python 或版本低於 Python 3.8，請下載並安裝Python。

安裝SDK

• 執行以下命令安裝OSS Python SDK V2程式碼封裝。請根據需求選擇合適的OSS Python SDK V2版本，推薦使用最新的版本，確保本文中的程式碼範例可以正常運行。

  pip install alibabacloud-oss-v2

• 使用以下代碼引入OSS Python SDK V2包。

  import alibabacloud_oss_v2 as oss

初始化用戶端

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

import alibabacloud_oss_v2 as oss

def main():
    """
    Python SDK V2 用戶端初始化配置說明：

    1. 簽名版本：Python SDK V2 預設使用 V4 簽名，提供更高的安全性
    2. Region配置：初始化 Client 時，必須指定阿里雲 Region ID 作為請求地區標識
    3. Endpoint配置：
       - 可通過Endpoint參數自訂服務要求的訪問網域名稱
       - 當不指定 Endpoint 時，將根據 Region 自動構造公網訪問網域名稱
    4. 協議配置：
       - SDK 預設使用 HTTPS 協議構造訪問網域名稱
       - 如需使用 HTTP 協議，在指定網域名稱時明確指定
    """

    # 從環境變數中載入憑證資訊，用於身分識別驗證
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 載入SDK的預設配置，並設定憑證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 方式一：只填寫Region（推薦）
    # 必須指定Region ID，SDK會根據Region自動構造HTTPS訪問網域名稱
    cfg.region = '<region-id>' 

    # # 方式二：同時填寫Region和Endpoint
    # # 必須指定Region ID
    # cfg.region = '<region-id>'
    # # 填寫Bucket所在地區對應的外網Endpoint
    # cfg.endpoint = '<endpoint>'

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 定義要上傳的字串內容
    text_string = "Hello, OSS!"
    data = text_string.encode('utf-8')  # 將字串編碼為UTF-8位元組串

    # 執行上傳對象的請求，指定儲存空間名稱、對象名稱和資料內容
    result = client.put_object(oss.PutObjectRequest(
        bucket="Your Bucket Name",
        key="Your Object Key",
        body=data,
    ))

    # 輸出請求的結果狀態代碼、請求ID、ETag，用於檢查請求是否成功
    print(f'status code: {result.status_code}\n'
          f'request id: {result.request_id}\n'
          f'etag: {result.etag}'
    )

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

import asyncio
import alibabacloud_oss_v2 as oss
import alibabacloud_oss_v2.aio as oss_aio

async def main():
    """
    Python SDK V2 非同步用戶端初始化配置說明：

    1. 簽名版本：Python SDK V2 預設使用 V4 簽名，提供更高的安全性

    2. Region配置：初始化 AsyncClient 時，必須指定阿里雲 Region ID 作為請求地區標識

    3. Endpoint配置：
       - 可通過Endpoint參數自訂服務要求的訪問網域名稱
       - 當不指定 Endpoint 時，將根據 Region 自動構造公網訪問網域名稱

    4. 協議配置：
       - SDK 預設使用 HTTPS 協議構造訪問網域名稱
       - 如需使用 HTTP 協議，在指定網域名稱時明確指定
    
    5. 非同步特性：
       - 匯入非同步模組：import alibabacloud_oss_v2.aio as oss_aio
       - 建立非同步用戶端：oss_aio.AsyncClient(cfg)
       - 所有操作需要使用 await 關鍵字
       - 需要在 finally 塊中調用 await client.close() 關閉串連
       - 需要安裝 aiohttp 依賴：pip install aiohttp
    """

    # 從環境變數中載入憑證資訊，用於身分識別驗證
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 載入SDK的預設配置，並設定憑證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 方式一：只填寫Region（推薦）
    # 必須指定Region ID，SDK會根據Region自動構造HTTPS訪問網域名稱
    cfg.region = '<region-id>'

    # # 方式二：同時填寫Region和Endpoint
    # # 必須指定Region ID
    # cfg.region = '<region-id>'
    # # 填寫Bucket所在地區對應的外網Endpoint
    # cfg.endpoint = '<endpoint>'

    # 使用配置好的資訊建立OSS非同步用戶端
    client = oss_aio.AsyncClient(cfg)

    try:
        # 定義要上傳的字串內容
        text_string = "Hello, OSS!"
        data = text_string.encode('utf-8')  # 將字串編碼為UTF-8位元組串

        # 執行非同步上傳對象的請求，指定儲存空間名稱、對象名稱和資料內容
        # 注意：使用 await 關鍵字等待非同步作業完成
        result = await client.put_object(
            oss.PutObjectRequest(
                bucket="Your Bucket Name",
                key="Your Object Key",
                body=data,
            )
        )

        # 輸出請求的結果狀態代碼、請求ID、ETag，用於檢查請求是否成功
        print(f'status code: {result.status_code}\n'
              f'request id: {result.request_id}\n'
              f'etag: {result.etag}'
        )

    except Exception as e:
        print(f'上傳失敗: {e}')

    finally:
        # 關閉非同步用戶端串連（重要：避免資源泄漏）
        await client.close()

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    # 使用 asyncio.run() 運行非同步主函數
    asyncio.run(main())

運行後將會輸出上傳檔案成功的結果：

status code: 200
request id: 6875F95738B0ED3030F086A0
etag: "56AAD346F0899BFE8BDD02C06BBE511E"

用戶端配置

使用自訂網域名

使用OSS預設網域名稱訪問時，可能會出現檔案禁止訪問、檔案無法預覽等問題；通過通過自訂網域名訪問OSS，不僅支援瀏覽器直接預覽檔案，還可結合CDN加速分發。

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

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所在地區
    cfg.region = '<region-id>'

    # 請填寫您的自訂網域名。例如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函數

逾時控制

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

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所在地區
    cfg.region = '<region-id>'

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

重試策略

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

import alibabacloud_oss_v2 as oss

def main():
    """
    SDK 重試策略配置說明：

    預設重試策略：
    當沒有配置重試策略時，SDK 使用 StandardRetryer() 作為用戶端的預設實現，其預設配置如下：
    - max_attempts：設定最大嘗試次數。預設為3次
    - max_backoff：設定最大退避時間（單位：秒）。預設為20秒
    - base_delay：設定基礎延遲時間（單位：秒）。預設為0.2秒
    - backoff_delayer：設定退避演算法。預設使用FullJitter退避演算法
      計算公式為：[0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
    - error_retryables：可重試的錯誤類型，請參閱https://gosspublic.alicdn.com/sdk-doc/alibabacloud-oss-python-sdk-v2/latest/_modules/alibabacloud_oss_v2/retry/error_retryable.html

    當發生可重試錯誤時，將使用其提供的配置來延遲並隨後重試該請求。
    請求的總體延遲會隨著重試次數而增加，如果預設配置不滿足您的情境需求時，
    可配置重試參數或者修改重試實現。
    """

    # 從環境變數中載入憑證資訊，用於身分識別驗證
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 載入預設的配置資訊
    cfg = oss.config.load_default()

    # 配置重試策略樣本：

    # 1. 自訂最大重試次數（預設為3次，這裡設定為5次）
    cfg.retryer = oss.retry.StandardRetryer(max_attempts=5)

    # 2. 自訂退避延遲時間
    # 調整基礎延遲時間 base_delay 為0.5秒（預設0.2秒），最大退避時間 max_backoff 為25秒（預設20秒）
    # cfg.retryer = oss.retry.StandardRetryer(max_backoff=25, base_delay=0.5)

    # 3. 自訂退避演算法
    # 使用固定時間退避演算法替代預設的FullJitter演算法，每次延遲2秒
    # cfg.retryer = oss.retry.StandardRetryer(backoff_delayer=oss.retry.FixedDelayBackoff(2))

    # 4. 禁用重試策略
    # 如需禁用所有重試嘗試時，可以使用retry.NopRetryer實現
    # cfg.retryer = oss.retry.NopRetryer()

    # 設定憑證提供者
    cfg.credentials_provider = credentials_provider

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

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

設定串連池大小

在http_client中指定max_connections參數即可配置串連池大小。

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

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

# OSS Python SDK V2 串連池配置樣本

import alibabacloud_oss_v2 as oss

def main():

    # 從環境變數中載入訪問憑證（需要設定OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 載入SDK的預設配置，並設定憑證提供者
    config = oss.config.load_default()
    config.credentials_provider = credentials_provider

    # 設定OSS服務地區
    config.region = "<region-id>"

    # ============ 自訂HTTPClient配置 ============
    # 建立HTTP用戶端配置參數字典
    http_client_config = {}
    
    # 設定串連池大小為100，預設為20
    http_client_config["max_connections"] = 100
    
    # 使用自訂配置建立HTTP用戶端
    http_client = oss.transport.RequestsHttpClient(**http_client_config)
    
    # 將自訂的HTTP用戶端設定到設定物件中
    config.http_client = http_client
    # ============================================
    
    # 初始化OSS用戶端執行個體
    client = oss.Client(config)

    # 配置Bucket和檔案資訊
    bucket = "example-bucket"             # Bucket名稱
    key = "dest.jpg"                      # OSS中的檔案路徑
    file_path = "dest.jpg"                # 本地儲存路徑

    # 將OSS中的檔案下載到本地指定路徑
    client.get_object_to_file(oss.GetObjectRequest(bucket, key), file_path)
    print(f"檔案下載完成: {key} -> {file_path}")
    print(f"串連池大小已設定為: {http_client_config['max_connections']}")

if __name__ == "__main__":
    # 程式進入點
    try:
        main()
    except Exception as e:
        print(f"運行過程中發生錯誤: {e}")
        raise

HTTP/HTTPS 協議

使用 cfg.disable_ssl = True 設定不使用HTTPS協議。

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

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所在地區
    cfg.region = '<region-id>'

    # 設定不使用https請求
    cfg.disable_ssl = True

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

Proxy 伺服器

企業安全性原則通常限制直接存取公網，配置Proxy 伺服器訪問 OSS。

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

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所在地區
    cfg.region = '<region-id>'

    # 設定user_agent
    cfg.user_agent = 'aliyun-sdk-python'

    # 設定Proxy 伺服器
    cfg.proxy_host = 'http://user:passswd@proxy.example-***.com'

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

使用內網網域名稱

使用內網網域名稱訪問同地區的OSS資源，可以降低流量成本並提高訪問速度。

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

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所在地區
    cfg.region = '<region-id>'
    cfg.use_internal_endpoint = True

    # # 方式二： 直接填寫Region和Endpoint
    # # 填寫Bucket所在地區
    # cfg.region = '<region-id>'
    # # 填寫Bucket所在地區對應的內網Endpoint
    # cfg.endpoint = '<endpoint>'

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

使用傳輸加速網域名稱

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

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所在地區
    cfg.region = '<region-id>'
    cfg.use_accelerate_endpoint = True

    # # 方式二： 直接填寫Region和傳輸加速Endpoint
    # # 填寫Bucket所在地區
    # cfg.region = '<region-id>'
    # # 填寫Bucket所在地區對應的傳輸加速Endpoint
    # cfg.endpoint = 'https://oss-accelerate.aliyuncs.com'

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

使用專有域

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

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所在地區
    cfg.region = '<region-id>'

    # 請填寫您的專有域。例如：https://service.corp.example.com
    cfg.endpoint = 'https://service.corp.example.com'

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

自訂HTTPClient

當常用配置參數無法滿足情境需求時，您可以使用cfg.http_client替換預設的 HTTP 用戶端。

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

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] = {}

    # 設定session
    # kwargs["session"] = requests.Session()

    # 設定adapter
    # kwargs["adapter"] = HTTPAdapter()

    # 是否跳過認證檢查，預設不跳過
    # kwargs["insecure_skip_verify"] = False

    # 是否開啟啟HTTP重新導向，預設不啟用
    # kwargs["enabled_redirect"] = False

    # 設定Proxy 伺服器
    # kwargs["proxy_host"] = config.proxy_host

    # 設定塊大小
    # kwargs["block_size"] = 16 * 1024

    # 連線逾時, 預設值 10秒
    kwargs["connect_timeout"] = 30

    # 應用讀寫資料的逾時時間, 預設值 20秒
    kwargs["readwrite_timeout"] = 30

    # 最大串連數，預設值 20
    kwargs["max_connections"] = 1024

    # 建立HTTP用戶端，並傳入HTTP用戶端參數
    cfg.http_client = oss.transport.RequestsHttpClient(**kwargs)

    # 設定憑證提供者
    cfg.credentials_provider = credentials_provider

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

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

訪問憑證配置

OSS 提供多種憑證初始化方式。請根據您的認證和授權需求選擇合適的初始化方式。

使用RAM使用者的AK

如果您的應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問您的OSS，且不能頻繁輪轉憑證時，您可以使用阿里雲主帳號或RAM使用者的AK（Access Key ID、Access Key Secret）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個AK，存在安全性風險和維護複雜度增加的風險。

import alibabacloud_oss_v2 as oss

def main():
    # 建立靜態憑證提供者，顯式設定存取金鑰和密鑰密碼，請替換為您的RAM使用者的AccessKey ID和AccessKey Secret
    credentials_provider = oss.credentials.StaticCredentialsProvider(
        access_key_id="RAM AccessKey ID",
        access_key_secret="RAM AccessKey Secret"
    )

    # 載入SDK的預設配置，並設定憑證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

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

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

使用STS臨時訪問憑證

如果您的應用程式需要臨時訪問OSS，您可以使用通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個STS Token，存在安全性風險和維護複雜度增加的風險。此外，如果您需要多次臨時訪問OSS，您需要手動重新整理STS Token。

import alibabacloud_oss_v2 as oss

def main():
    # 填寫擷取的臨時存取金鑰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）。
    sts_security_token = 'yourSecurityToken'

    # 建立靜態憑證提供者，顯式設定臨時存取金鑰AccessKey ID和AccessKey Secret，以及STS安全性權杖
    credentials_provider = oss.credentials.StaticCredentialsProvider(
        access_key_id=sts_access_key_id,
        access_key_secret=sts_access_key_secret,
        security_token=sts_security_token,
    )

    # 載入SDK的預設配置，並設定憑證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

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

    # 使用配置好的資訊建立OSS用戶端
    client = oss.Client(cfg)

    # 使用建立好的client執行後續操作...

# 當此指令碼被直接運行時，調用main函數
if __name__ == "__main__":
    main()  # 指令碼入口，當檔案被直接運行時調用main函數

使用RAMRoleARN

如果您的應用程式需要授權訪問OSS，例如跨阿里雲帳號訪問OSS，您可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具會前往STS服務擷取STS Token，並在會話到期前調用AssumeRole介面申請新的STS Token。此外，您還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。

1. 添加alibabacloud_credentials依賴。

   pip install alibabacloud_credentials

2. 配置AK和RAMRoleARN作為訪問憑證。

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

   # -*- coding: utf-8 -*-
   import os
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   import alibabacloud_oss_v2 as oss
   
   def main():
       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>',
           # 設定角色會話有效期間，單位為秒，預設值為3600秒（1小時），非必填
           role_session_expiration=3600
       )
   
       cred_client = Client(config)
   
       def get_credentials_wrapper():
           cred = cred_client.get_credential()
           return oss.credentials.Credentials(access_key_id=cred.access_key_id, access_key_secret=cred.access_key_secret, security_token=cred.security_token)
   
       # 建立憑證提供者，用於動態載入憑證
       credentials_provider = oss.credentials.CredentialsProviderFunc(func=get_credentials_wrapper)
   
       # 載入OSS SDK的預設配置
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # 填寫Bucket所在地區
       cfg.region = '<region-id>'
   
       # 建立OSS用戶端執行個體
       client = oss.Client(cfg)
   
       # 使用client進行後續操作...
   
   # 當此指令碼被直接運行時，調用main函數
   if __name__ == "__main__":
       main()  # 指令碼入口，當檔案被直接運行時調用main函數

使用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，請參見建立角色。

1. 添加alibabacloud_credentials依賴。

   pip install alibabacloud_credentials

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

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

   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   import alibabacloud_oss_v2 as oss
   
   def main():
       config = Config(
           type='ecs_ram_role',      # 訪問憑證類型。固定為ecs_ram_role。
           role_name='EcsRoleExample'    # 為ECS授予的RAM角色的名稱。選擇性參數。如果不設定，將自動檢索。強烈建議設定，以減少請求。
       )
   
       cred_client = Client(config)
   
       def get_credentials_wrapper():
           cred = cred_client.get_credential()
           return oss.credentials.Credentials(access_key_id=cred.access_key_id, access_key_secret=cred.access_key_secret, security_token=cred.security_token)
   
       # 建立憑證提供者，用於動態載入憑證
       credentials_provider = oss.credentials.CredentialsProviderFunc(func=get_credentials_wrapper)
   
       # 載入OSS SDK的預設配置
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # 填寫Bucket所在地區
       cfg.region = '<region-id>'
   
       # 建立OSS用戶端執行個體
       client = oss.Client(cfg)
   
       # 使用client進行後續操作...
   
   # 當此指令碼被直接運行時，調用main函數
   if __name__ == "__main__":
       main()  # 指令碼入口，當檔案被直接運行時調用main函數

使用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許可權隔離。

使用自訂訪問憑證

當以上憑證配置方式不滿足要求時，您可以自訂擷取憑證的方式。SDK 支援多種實現方式。

1. 通過credentials.CredentialsProviderFunc介面

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

   import argparse
   import alibabacloud_oss_v2 as oss
   import os
   
   def main():
   
       def get_credentials_wrapper():
           # 返回長期憑證
           return oss.credentials.Credentials(access_key_id='access_key_id', access_key_secret='access_key_security')
           # 返回STS臨時憑證
           # return oss.credentials.Credentials(access_key_id='access_key_id', access_key_secret='access_key_security', security_token='security_token')
   
       credentials_provider = oss.credentials.CredentialsProviderFunc(func=get_credentials_wrapper)
   
      # 載入SDK的預設配置，並設定憑證提供者
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
       
       # 填寫Bucket所在地區
       cfg.region = "<region-id>"
   
       # 使用配置好的資訊建立OSS用戶端
       client = oss.Client(cfg)
   
       # 使用client進行後續操作...
   
   if __name__ == "__main__":
       main()  # 指令碼入口，當檔案被直接運行時調用main函數

2. 實現credentials.CredentialsProvider介面

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

   # -*- coding: utf-8 -*-
   import alibabacloud_oss_v2 as oss
   
   class CredentialProviderWrapper(oss.credentials.CredentialsProvider):
       def get_credentials(self):
           # TODO
           # 自訂訪問憑證的擷取方法
   
           # 返回長期憑證access_key_id, access_key_secrect
           return oss.credentials.Credentials('<access_key_id>', '<access_key_secrect>')
   
           # 返回 STS臨時憑證access_key_id, access_key_secrect, token
           # 對於臨時憑證，需要根據到期時間，重新整理憑證。
           # return oss.credentials.Credentials('<access_key_id>', '<access_key_secrect>', '<token>');
   
   def main():
       # 建立憑證提供者，用於動態載入憑證
       credentials_provider = CredentialProviderWrapper()
   
       # 載入OSS SDK的預設配置
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # 填寫Bucket所在地區
       cfg.region = '<region-id>'
   
       client = oss.Client(cfg)
   
       # 使用client進行後續操作...
   
   if __name__ == "__main__":
       main()  # 指令碼入口，當檔案被直接運行時調用main函數

匿名訪問

如果您只需要訪問公用讀取許可權的OSS資源，可以使用匿名訪問方式，無需提供任何憑證。

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

import alibabacloud_oss_v2 as oss

# 建立匿名憑證提供者
credentials_provider = oss.credentials.AnonymousCredentialsProvider()

# 配置用戶端
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
# 填寫Bucket所在地區
cfg.region = '<region-id>'

# 建立OSS用戶端
client = oss.Client(cfg)

錯誤自助排查

使用OSS Python SDK V2訪問OSS出現錯誤時，OSS會返回HTTP Code、Message、RequestId、EC錯誤碼等資訊，其中EC碼對應一個具體的錯誤原因，您可以使用EC碼自助進行錯誤排查。

範例程式碼

OSS Python SDK V2提供豐富的範例程式碼供參考或直接使用。