Object Storage Service：Python初始化

注意事項

• 初始化Python SDK前，您需要配置訪問憑證，本文以從環境變數讀取存取憑證為例，詳情請參見配置訪問憑證。

• 如果您希望擷取關於OSS支援的Region與Endpoint的對應關係，請參見OSS地區和訪問網域名稱。

• 如果您希望建立RAM使用者的AccessKey，請參見建立AccessKey。

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

  • oss2.Service類用於列舉儲存空間。

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

  初始化oss2.Service和oss2.Bucket兩個類時，需要指定Endpoint。其中oss2.Service類不支援自訂網域名訪問。

前置條件

1. 使用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

      1. 執行以下命令使變更生效。

         source ~/.bashrc

      2. 執行以下命令檢查環境變數是否生效。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. 在終端中執行以下命令，查看預設Shell類型。

      echo $SHELL

      1. 根據預設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"

      1. 運行以下命令，檢查環境變數是否生效。

         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)

      1. 運行以下命令，檢查環境變數是否生效。

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

2. 參考上述方式修改系統內容變數後，請重啟或重新整理您的編譯運行環境，包括IDE、命令列介面、其他傳統型應用程式及後台服務，以確保最新的系統內容變數成功載入。

預設樣本

以下程式碼範例示範了如何使用V4簽名和V1簽名初始化Python SDK。

請注意，以下程式碼範例使用Bucket外網網域名稱以及RAM使用者的AK資訊。

# -*- 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) 

# -*- 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')                    

常見情境配置樣本

以下提供了常見情境的配置樣本，其中程式碼範例預設使用V4簽名以及RAM使用者的AK資訊進行初始化。

內網網域名稱配置樣本

當您的應用部署在阿里雲的ECS執行個體上，並且需要頻繁訪問同地區的OSS資源時，使用內網網域名稱可以降低流量成本並提高訪問速度。

以下是使用OSS內網網域名稱配置OSSClient的範例程式碼。

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

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

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

自訂網域名配置樣本

當您有多個不同的OSS Bucket用於不同的目的時，可以通過為每個Bucket設定不同的子網域名稱來更好地管理和組織資源。

以下是使用自訂網域名配置OSSClient的範例程式碼。

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

# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請先配置環境變數。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# yourEndpoint請填寫您的自訂網域名。例如https://static.example.com。
endpoint = 'yourEndpoint'
# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。
region = 'cn-hangzhou'

# 填寫Bucket名稱。請注意，設定is_cname=True表示開啟CNAME選項
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', is_cname=True, 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"

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

關閉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協議。

以下代碼用於指定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")

oss2.Bucket類支援配置的參數匯總

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

常見問題