如何初始化Python SDK - Object Storage Service

本文介紹如何初始化Python SDK。

前提條件

初始化Python SDK前，您需要配置訪問憑證。詳情請參見配置訪問憑證。

背景資訊

使用Python SDK時，大部分操作都是通過oss2.Service和oss2.Bucket兩個類進行。

oss2.Service類用於列舉儲存空間。
oss2.Bucket類用於上傳、下載、刪除檔案以及對儲存空間進行各種配置。

初始化oss2.Service和oss2.Bucket兩個類時，需要指定Endpoint。其中oss2.Service類不支援自訂網域名訪問。關於Endpoint的更多資訊，請參見OSS地區和訪問網域名稱和自訂訪問網域名稱。

初始化oss2.Service類

具體操作，請參見列舉儲存空間。

初始化oss2.Bucket類

V4簽名（推薦）

推薦使用更安全的V4簽名演算法。使用V4簽名初始化時，除指定Endpoint以外，您還需要指定阿里雲通用Region ID作為發起請求地區的標識，樣本值為cn-hangzhou。同時聲明oss2.ProviderAuthV4。OSS Python SDK 2.18.4及以上版本支援V4簽名。

以使用OSS網域名稱初始化時使用V4簽名為例，其他通過自訂網域名、匿名初始化的情境可參考以下樣本執行相應修改。

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

# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請先配置環境變數。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'yourEndpoint'
# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。
region = 'cn-hangzhou'

# 填寫Bucket名稱。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

V1簽名（不推薦）

重要

阿里雲Object Storage Service自2024年12月1日起不再對新使用者（即新UID ）開放使用V1簽名，並將於2025年06月01日起停止更新與維護且不再對新增Bucket開放使用V1簽名。請儘快切換到V4簽名，避免影響服務。更多資訊，請參見公告說明。

使用OSS網域名稱初始化

以下代碼用於使用OSS網域名稱初始化。關於不同地區的OSS網域名稱，請參見OSS地區和訪問網域名稱。

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

# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請先配置環境變數。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'yourEndpoint'

# 填寫Bucket名稱。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket')

使用自訂網域名初始化

以下代碼用於使用自訂網域名初始化。關於使用自訂網域名訪問OSS的更多資訊，請參見綁定自訂網域名至Bucket預設網域名稱。

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

# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請先配置環境變數。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# 填寫自訂網域名，例如example.com。
cname = 'http://example.com'

# 填寫Bucket名稱，並設定is_cname=True來開啟CNAME。CNAME是指將自訂網域名綁定到儲存空間。
bucket = oss2.Bucket(auth, cname, 'examplebucket', is_cname=True)

使用匿名訪問初始化

重要

匿名使用者只能讀取public-read（公用讀取）的Bucket以及讀取和寫入public-read-write（公用讀寫）的Bucket，不能進行Service相關的操作、Bucket相關的操作、列舉檔案等。

假設examplebucket儲存空間的ACL為public-read-write，以下代碼用於使用匿名訪問初始化。

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

# yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'yourEndpoint'

# 填寫Bucket名稱，例如examplebucket。    
bucket_name = 'examplebucket'

# 使用匿名訪問初始化。
bucket = oss2.Bucket(oss2.AnonymousAuth(), endpoint, bucket_name)

oss2.Bucket類支援配置的參數

初始化oss2.Bucket類時支援配置的參數請參見下表。

參數	樣本值	描述	方法
is_cname	True	Endpoint是否為自訂網域名。取值範圍如下： True：Endpoint為自訂網域名。 False（預設）：Endpoint為OSS網域名稱。	oss2.Bucket(auth, cname, 'examplebucket', is_cname=True)
session	mytestsession	會話名，預設值為None，表示新開會話。如果設定此參數為已有會話名，則複用傳入的會話。	oss2.Bucket(auth, endpoint, 'examplebucket', session=oss2.Session())
connect_timeout	30	連線逾時時間，預設值為60，單位為秒。	oss2.Bucket(auth, endpoint, 'examplebucket', connect_timeout=30)
app_name	mytool	應用程式名稱，預設值為空白。如果此參數不為空白，則在User Agent中加入對應值。重要由於該字串會作為HTTP Header的值進行傳輸，因此該字串必須遵循HTTP標準。	oss2.Bucket(auth, endpoint, 'examplebucket', app_name='mytool')
enable_crc	False	是否開啟CRC資料校正。 True（預設）：開啟 False：關閉	oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False)

oss2.Bucket類配置樣本

oss2.Bucket類常見配置樣本如下。

設定連線逾時時間

以下代碼用於設定連線逾時時間。

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

# 強烈建議不要把訪問憑證儲存到工程代碼裡，否則可能導致訪問憑證泄露，威脅您帳號下所有資源的安全。本程式碼範例以從環境變數中擷取訪問憑證為例。運行本程式碼範例之前，請先配置環境變數。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# 填寫Bucket名稱，並設定連線逾時時間為30秒。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', connect_timeout=30,region=region)

關閉CRC資料校正

上傳和下載檔案時預設開啟CRC資料校正，確保上傳和下載過程的資料完整性。

警告

強烈建議不要關閉CRC資料校正功能。如果關閉此功能，則阿里雲不保證上傳和下載過程資料的完整性。

以下代碼用於關閉CRC資料校正。

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

# 強烈建議不要把訪問憑證儲存到工程代碼裡，否則可能導致訪問憑證泄露，威脅您帳號下所有資源的安全。本程式碼範例以從環境變數中擷取訪問憑證為例。運行本程式碼範例之前，請先配置環境變數。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# 填寫Bucket名稱，並設定enable_crc=False來關閉CRC資料校正。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False,region=region)

設定串連池大小

以下代碼用於設定串連池大小。

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

# 強烈建議不要把訪問憑證儲存到工程代碼裡，否則可能導致訪問憑證泄露，威脅您帳號下所有資源的安全。本程式碼範例以從環境變數中擷取訪問憑證為例。運行本程式碼範例之前，請先配置環境變數。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# 設定串連池的大小，預設值為10。
session = oss2.Session(pool_size=20)

# 填寫Bucket名稱。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', session=session,region=region)

指定TLS版本

不同版本的TLS協議有不同的安全性和效能特點，請根據具體的應用情境選擇合適版本的TLS協議。

說明

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

以下代碼用於指定TLS版本為1.2。

# -*- coding: utf-8 -*-
import ssl
import oss2
from requests.adapters import HTTPAdapter
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請先配置環境變數。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 自訂ssl adapter。
class SSLAdapter(HTTPAdapter):
    def init_poolmanager(self, *args, **kwargs):
        # 設定TLS版本為1.2。
        kwargs["ssl_version"] = ssl.PROTOCOL_TLSv1_2
        return super().init_poolmanager(*args, **kwargs)

# 建立session對象，並通過session自訂adapter。
session = oss2.Session(adapter=SSLAdapter())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# 填寫Bucket名稱，例如examplebucket。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', session=session, region=region)

# 上傳檔案。
bucket.put_object("example.txt", "hello")

後續步驟

初始化Python SDK後，您可以使用oss2發起請求。詳情請參見快速入門。