Python SDK V1到V2遷移指南

主要變更概覽

遷移到V2版 SDK時，您需要瞭解以下主要變更：

1. 用戶端建立方式：V2版本把Client的建立函數從Bucket修改為Client

2. API調用模式：從函數參數傳遞方式改為請求/響應模型

3. 包名稱變更：從oss2變更為alibabacloud_oss_v2

4. 類和方法名稱變化：部分API名稱發生變化

5. 類型註解：V2版本引入完整類型註解，提升代碼可維護性

完整遷移步驟

第一步：環境準備

1. 評估現有代碼：

   • 梳理現有代碼中使用OSS SDK的位置

   • 記錄您使用了哪些OSS功能和介面

   • 確定依賴關係，避免遷移過程中出現意外問題

2. 更新Python運行環境：

   • V2版本要求Python的運行環境版本最低為3.8。請參考Python官網下載和安裝Python 3.8及以上版本的運行環境，通過以下命令檢查Python是否安裝成功：

     python --version

3. 保留V1版SDK以便逐步遷移，安裝V2版SDK：

   pip install alibabacloud-oss-v2

4. 建立測試環境：

   • 建議建立獨立的測試環境，而不是直接在生產環境修改

   • 配置測試資料和測試案例，用於驗證遷移後的代碼

第二步：修改匯入語句

功能變更

Python SDK V2版本啟用了新的代碼倉庫（alibabacloud-oss-python-sdk-v2），並對代碼結構進行了最佳化調整。此次調整按照功能模組對代碼進行了重新組織，旨在提升代碼的可讀性和維護性。以下是各個模組的路徑及其相應說明：

程式碼範例

1. 替換包匯入： 將所有oss2的匯入替換為對應的alibabacloud_oss_v2匯入：

   # V1版
   import oss2
   
   # V2版
   import alibabacloud_oss_v2 as oss
   

2. 匯入模型類：

   # V2版SDK需要匯入請求和結果模型
   from oss.models import (
       PutObjectRequest, GetObjectRequest, DeleteObjectRequest, 
       ListObjectsRequest, PutBucketRequest, GetBucketAclRequest
       # 其他您需要的請求類...
   )

3. 匯入其他工具類：

   # 根據需要匯入V2版SDK的工具類
   from oss import (
       Uploader, Downloader, Copier, 
       ListObjectsPaginator, ListObjectsV2Paginator
   )

第三步：修改建立用戶端代碼

功能變更

1. V2 版本把用戶端Client的建立函數從Bucket包遷移至Client包中。

2. V2版本對配置用戶端進行了最佳化，所有配置項現已統一歸類到config下，支援通過編程方式覆蓋預設配置，從而提供更高的靈活性和便捷性。

3. V2版本預設採用V4簽名演算法，因此在配置用戶端時必須指定阿里雲通用Region ID作為發起請求地區的標識。

4. V2版本支援根據所選地區（Region）自動產生訪問網域名稱（Endpoint）。當您訪問公網網域名稱時，無需手動設定Endpoint，系統將自動依據您的地區資訊進行構造。

程式碼範例

# -*- 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。
region = 'cn-hangzhou'

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

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

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即可
    # 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou
    cfg.region = 'cn-hangzhou'

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

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

關於V2版配置用戶端的更多詳細樣本，請參見配置用戶端。

關於V2版配置訪問憑證的更多詳細樣本，請參見配置訪問憑證。

第四步：修改基礎API調用方式

功能變更

1. SDK V2版本提供了與REST API對應的介面，把這類介面叫做基礎介面或者低層級API。您可以通過這些介面訪問OSS的服務，例如建立儲存空間，上傳檔案和下載檔案等。

2. 在V2版本中，各個基礎API介面遵循一套標準化的命名規則。每個操作方法均命名為<OperationName>形式，其中，操作的請求參數類被定義為<OperationName>Request，而操作的結果傳回值則定義為<OperationName>Result，如下所示。

   def <OperationName>(self, request: models.<OperationRequestName>, **kwargs
                    ) -> models.<OperationResulttName>:            
       return operations.<OperationName>(self._client, request, **kwargs)

關於基礎API的更多詳細說明，請參考開發人員指南-基礎介面。

程式碼範例

1. 建立儲存空間：

   # V1版
   bucket.create_bucket()
   # 或者帶許可權
   bucket.create_bucket(oss2.BUCKET_ACL_PRIVATE)
   
   # V2版
   request = PutBucketRequest(bucket='your-bucket-name')
   client.put_bucket(request)
   # 或者帶許可權
   request = PutBucketRequest(
       bucket='your-bucket-name',
       acl=BucketAcl.PRIVATE
   )
   client.put_bucket(request)

2. 擷取儲存空間ACL：

   # V1版
   result = bucket.get_bucket_acl()
   acl = result.acl
   
   # V2版
   request = GetBucketAclRequest(bucket='your-bucket-name')
   result = client.get_bucket_acl(request)
   acl = result.acl
   

3. 刪除儲存空間：

   # V1版
   bucket.delete_bucket()
   
   # V2版
   request = DeleteBucketRequest(bucket='your-bucket-name')
   client.delete_bucket(request)

4. 列舉儲存空間：

   # V1版
   service = oss2.Service(auth, endpoint)
   result = service.list_buckets()for bucket_info in result.buckets:print(bucket_info.name)
   
   # V2版 - 基本用法
   request = ListBucketsRequest()
   result = client.list_buckets(request)
   for bucket_info in result.buckets:
       print(bucket_info.name)   

5. 上傳對象：

   # V1版 - 上傳內容
   result = bucket.put_object('object-key', 'content')
   
   # V2版 - 上傳內容
   request = PutObjectRequest(
       bucket='your-bucket-name',
       key='object-key',
       content='content')
   result = client.put_object(request)
   
   # V1版 - 上傳檔案
   result = bucket.put_object_from_file('object-key', 'local-file.txt')
   
   # V2版 - 上傳檔案
   request = PutObjectRequest(
       bucket='your-bucket-name',
       key='object-key')
   result = client.put_object_from_file(request, 'local-file.txt')

6. 下載對象：

   # V1版 - 擷取對象內容
   result = bucket.get_object('object-key')
   content = result.read()
   
   # V2版 - 擷取對象內容
   request = GetObjectRequest(
       bucket='your-bucket-name',
       key='object-key')
   result = client.get_object(request)
   content = result.read()
   
   # V1版 - 下載到檔案
   bucket.get_object_to_file('object-key', 'local-file.txt')
   
   # V2版 - 下載到檔案
   request = GetObjectRequest(
       bucket='your-bucket-name',
       key='object-key')
   client.get_object_to_file(request, 'local-file.txt')

7. 刪除對象：

   # v1版
   bucket.delete_object('object-key')
   
   # V2版
   request = DeleteObjectRequest(
       bucket='your-bucket-name',
       key='object-key')
   client.delete_object(request)

8. 列舉對象：

   # V1版
   for obj in oss2.ObjectIterator(bucket, prefix='photos/'):
       print(obj.key)
       
   # V2版 - 基本用法
    client = oss.Client(cfg)
   
   paginator = client.list_objects_v2_paginator()
   for page in paginator.iter_page(oss.ListObjectsV2Request(
       bucket='your-bucket-name',
   ):
   for o in page.contents:
       print(f'Object: {o.key}, Size: {o.size}, Last_modified: {o.last_modified}')

關於V2版基礎API的更多範例程式碼，請參見對象/檔案。

第五步：修改進階API調用方式（可選）

預簽名介面

變更點

V2版本把預簽名介面名稱從sign_url修改為presign，同時把介面代碼實現遷移到Client類中。介面形式如下：

def presign(self, request: PresignRequest, **kwargs) -> PresignResult:

對於request參數，其類型與基礎API介面中的<OperationName>Request一致。

對於返回結果，除了返回預簽名URL外，還返回 HTTP 方法，到期時間和被簽名的要求標頭，如下：

class PresignResult:
    def __init__(
        self,
        method: Optional[str] = None,
        url: Optional[str] = None,
        expiration: Optional[datetime.datetime] = None,
        signed_headers: Optional[MutableMapping] = None,
    ) -> None:
        self.method = method
        self.url = url
        self.expiration = expiration
        self.signed_headers = signed_headers

關於V2版預簽名介面的詳細使用說明，請參考開發人員指南-預簽名介面。

程式碼範例

1. 使用預簽名URL上傳：

   # V1版 
   url = bucket.sign_url('PUT', 'object-key', 3600) # 3600秒有效期間
   
   # V2版
   client = oss.Client(cfg)
   pre_result = client.presign(oss.PutObjectRequest(
       bucket=args.bucket,
       key=args.key,
   ),expires=timedelta(seconds=3600)) # 3600秒有效期間

   關於V2版使用預簽名URL上傳檔案的完整範例程式碼，請參見使用預簽名URL上傳。

2. 使用預簽名URL下載

   # V1版
   url = bucket.sign_url('GET', 'object-key', 3600)  # 3600秒有效期間
   
   # V2版
   client = oss.Client(cfg)
   pre_result = client.presign(
       oss.GetObjectRequest(
           bucket=args.bucket, 
           key=args.key,    
   ),expires=timedelta(seconds=3600)) # 3600秒有效期間

   關於V2版使用預簽名URL下載檔案的完整範例程式碼，請參見使用預簽名URL下載。

檔案傳輸管理器

變更點

V2版本使用傳輸管理器'Uploader'，'Downloader' 和'Copier'分別管理對象的上傳，下載和拷貝。 同時移除了原有的斷點續傳介面Bucket.UploadFile，Bucket.DownloadFile和Bucket.CopyFile。

介面對比如下：

關於V2版檔案傳輸管理器的詳細使用說明，請參考開發人員指南-傳輸管理器。

程式碼範例

1. 檔案上傳管理器：

   # V1版
   oss2.resumable_upload(bucket, 'object-key', 'local-file.zip', 
                        multipart_threshold=100*1024,
                        part_size=100*1024,
                        num_threads=4)
                        
   # V2版 - 使用檔案上傳管理器
   uploader = client.uploader()
   
   # 調用方法執行檔案上傳操作
   result = uploader.upload_file(
       oss.PutObjectRequest(
           bucket='your-bucket-name',  
           key='object-key',   
       ),
       filepath='local-file.zip',
       part_size=10  * 1024 * 1024,
       part_num=3
   )

   關於V2版檔案上傳管理器的更多詳細說明，請參見開發人員指南-檔案上傳管理器。

   關於V2版檔案上傳管理器的完整範例程式碼，請參見檔案上傳管理器。

2. 檔案下載管理員：

   # V1版
   oss2.resumable_download(bucket, 'object-key', 'local-file.zip',
                          multiget_threshold=100*1024,
                          part_size=100*1024,
                          num_threads=4)
                          
   # V2版 - 使用檔案下載管理員
   down_loader = client.downloader()
   
   result = down_loader.download_file(oss.GetObjectRequest(
       bucket='your-bucket-name',  
       key='object-key',
   ), filepath='local-file.zip')

   關於V2版檔案下載管理員的更多詳細說明，請參見開發人員指南-檔案下載管理員。

   關於V2版檔案下載管理員的完整範例程式碼，請參見檔案下載管理員。

3. 檔案拷貝管理器：

   # V1版
   bucket.copy_object('src-bucket', 'src-object', 'dst-object')
   
   # V2版
   request = CopyObjectRequest(
       bucket='your-bucket-name',
       key='dst-object',
       source_bucket='src-bucket',
       source_key='src-object')
   client.copy_object(request)
   
   # V2版 - 使用檔案拷貝管理器
   client = oss.Client(cfg)
   copier = client.copier()
   result = copier.copy(
       oss.CopyObjectRequest(
           bucket=args.bucket,
           key=args.key,
           source_bucket=args.source_bucket,
           source_key=args.source_key,
       )
   )

   關於V2版檔案拷貝管理器的更多詳細說明，請參見開發人員指南-檔案拷貝管理器。

   關於V2版檔案拷貝管理器的完整範例程式碼，請參見檔案拷貝管理器。

第六步：測試和驗證

1. 編寫單元測試：

   為確保遷移後功能的正確性，您需要為每個遷移的功能編寫詳細的單元測試案例。這些測試應涵蓋所有關鍵操作，並驗證其行為與舊版SDK保持一致。重點包括：

   • 基礎功能測試：如建立資源、查詢狀態、更新資料和刪除資源等。

   • 邊界條件測試：測試極端情況下的應用行為，例如處理極大或極小的資料集、異常輸入等。

   • 錯誤處理測試：確保在出現錯誤時（如網路逾時、無效輸入），應用能夠正確處理並給出合適的反饋。

2. 增量測試：

   採用增量式的方法進行遷移和測試，可以有效降低風險：

   • 選擇一個小模組開始：先從一個相對獨立且不複雜的小模組開始遷移，並為其編寫完整的測試案例。

   • 進行全面測試：在確認該模組遷移成功且所有測試通過後，再逐步遷移到其他部分。這種方法有助於及時發現並解決問題，避免大規模復原。

3. 相容性測試：

   確保新版本SDK與您的整個技術棧及其他依賴項相容至關重要：

   • 內部系統相容性：驗證新版本是否與現有的內部系統和架構相容。

   • 第三方服務相容性：如果您的應用依賴於第三方服務或API，請確保這些介面與V2 SDK相容，並按照預期工作。

   • 環境相容性：在不同的作業系統和運行環境中測試您的應用，確保V2 SDK在各種環境下都能正常運行。

4. 效能測試：

   在完成代碼遷移後，必須對應用的效能進行全面評估：

   • 基準測試：建立效能基準，記錄當前應用的回應時間、輸送量等關鍵計量。

   • 對比分析：遷移完成後，使用相同的負載進行測試，比較新舊版本之間的效能差異，確保效能沒有顯著下降。

   • 調優：如果發現效能有所退步，可以通過調整配置參數、最佳化代碼邏輯等方式進行改進。

V1與V2版本差異匯總

import oss2

import alibabacloud_oss_v2

常見遷移問題與解決方案

相關文檔

關於Python SDK V1遷移到V2的更多詳細內容，請參見開發人員指南-遷移指南。