遷移至 Storage 適用的 Cloud 用戶端程式庫

Cloud Storage 可讓應用程式提供影片或圖片檔等大型資料物件，並讓使用者上傳大型資料檔案。在 Python 2 執行階段中，App Engine 提供專屬的用戶端程式庫，用於在 Cloud Storage 中寫入及讀取物件。較新的 App Engine 執行階段 (包括 Python 3 執行階段) 不支援這個 App Engine 程式庫。

如果 Python 2 應用程式使用 GoogleAppEngineCloudStorageClient 程式庫，您必須先遷移至 Cloud Storage 適用的 Cloud 用戶端程式庫，才能在 Python 3 執行階段中執行應用程式。請注意，您只需要遷移應用程式，即可使用新的用戶端程式庫。現有 Cloud Storage bucket 中的所有資料物件和權限都會維持不變，您可以使用新的用戶端程式庫存取現有 bucket。

比較 App Engine 與 Cloud 用戶端程式庫

相似處：

• Cloud 用戶端程式庫支援 App Engine 用戶端程式庫啟用的所有 Cloud Storage 功能，例如讀取、寫入、移除及列出物件。遷移作業只需要稍微修改程式碼。

  Cloud Client Library 也支援其他功能，例如建立及標記 buckets，以及擷取舊版物件。

差異：

• 在 App Engine 程式庫中，擷取物件清單的函式會以非同步方式運作。Cloud 用戶端程式庫不會提供列出物件的非同步函式，但您可以分頁並逐一查看一小組物件。

• App Engine 用戶端程式庫要求您使用存取控制清單 (ACL) 來控管值區和物件的存取權。不過，Cloud Storage 和 Cloud Client Library 支援兩種系統，可授予使用者存取值區和物件的權限：ACL 和統一 bucket 層級存取權。統一 bucket 層級存取權可簡化所有 Cloud 資源的存取權控管程序，並確保一致性。

  遷移至 Cloud 用戶端程式庫後，您透過 App Engine 用戶端程式庫使用的所有 ACL 仍會對現有 bucket 生效，而且您也可以視需要繼續使用 ACL。

  如果統一值區層級存取權符合您的需求，建議您為建立的任何新值區使用這個較簡單的系統。您可以轉換現有值區，改用統一值區層級存取權，但這可能需要大幅變更應用程式保護儲存空間物件存取權的方式。

程式碼範例：

• 使用 App Engine API 執行基本儲存作業

• 使用 Cloud Storage 適用的 Cloud 用戶端程式庫執行基本儲存作業

開始遷移前

如果您尚未設定 Python 開發環境，請設定該環境以使用與 Google Cloud相容的 Python 版本，並安裝測試工具來建立隔離的 Python 環境。

瞭解 Cloud Storage 權限

根據預設，應用程式自動建立的預設服務帳戶具有專案中值區的讀取和寫入權限，且無論是在遷移前或後，都擁有其建立物件的完整權限。

如果您使用其他服務帳戶或使用者帳戶，確保 Cloud Storage 值區和物件的存取安全，請務必在遷移前後繼續使用相同的帳戶和驗證技術。

轉換程序總覽

如要遷移 Python 應用程式，改用 Cloud Storage 適用的 Cloud 用戶端程式庫，而非 App Engine 用戶端程式庫，請按照下列步驟操作：

1. 安裝 Cloud Storage 適用的 Cloud 用戶端程式庫。

2. 更新程式碼，使用 Cloud 用戶端程式庫。

3. 測試更新。

4. 將應用程式部署至 App Engine。

安裝 Cloud Storage 適用的 Cloud 用戶端程式庫

如要在應用程式於 App Engine 中執行時，使用 Cloud Storage 適用的 Cloud 用戶端程式庫，請按照下列步驟操作：

1. 更新 app.yaml 檔案：

   1. 如果您使用 Cloud 用戶端程式庫，請新增最新版本的 grpcio 和 setuptools 程式庫。
   2. 新增 ssl 程式庫，因為 Cloud Storage 需要這個程式庫。

   以下是 app.yaml 檔案範例：

   runtime: python27
   threadsafe: yes
   api_version: 1
   
   libraries:
   - name: grpcio
     version: 1.0.0
   - name: setuptools
     version: 36.6.0
   - name: ssl
     version: latest
   

   部分用戶端程式庫不需要 SSL 程式庫。如果用戶端程式庫需要 SSL 程式庫，但您未加入，應用程式收到要求時，記錄檔探索器就會顯示 SSL 錯誤。

2. 更新 requirements.txt 檔案，將 Cloud Storage 的 Cloud 用戶端程式庫新增至依附元件清單：

   google-cloud-storage==1.24.1
   

   建議您使用 Cloud Storage 用戶端程式庫 1.24.1 版，因為該版本支援 Python 2.7 應用程式。

   然後執行 pip install -t lib -r requirements.txt，更新應用程式的可用程式庫清單。

3. 如果是 Python 2 應用程式，且應用程式使用內建或複製的程式庫，您必須在 appengine_config.py 檔案中指定這些路徑：

   import pkg_resources
   from google.appengine.ext import vendor
   
   # Set PATH to your libraries folder.
   PATH = 'lib'
   # Add libraries installed in the PATH folder.
   vendor.add(PATH)
   # Add libraries to pkg_resources working set to find the distribution.
   pkg_resources.working_set.add_entry(PATH)
   

   上述範例中的 appengine_config.py 檔案假設 lib 資料夾位於目前的工作目錄。如果無法確保 lib 一律位於目前工作目錄中，請指定 lib 資料夾的完整路徑。例如：

   import os
   path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')

更新程式碼以使用 Cloud 用戶端程式庫

建立 Cloud Storage 用戶端

如要使用 Cloud Storage 的 Cloud Client Library，請建立 Client 物件。用戶端包含連線至 Cloud Storage 所需的憑證和其他資料。例如：

from google.cloud import storage

client = storage.Client()

在先前說明的預設授權情境中，Cloud Storage 用戶端包含來自 App Engine 預設服務帳戶的憑證，該帳戶已獲授權可與專案的值區和物件互動。如果您不是在預設情境中工作，請參閱「應用程式預設憑證 (ADC)」，瞭解如何提供憑證。

使用 Cloud 用戶端程式庫方法

下表大致列出了實作特定 Cloud Storage 功能時，應使用 Cloud 用戶端程式庫中的哪些方法。

注意： 請參閱 Cloud 用戶端程式庫的程式碼範例清單和參考文件。

Cloud Storage 功能	Cloud 用戶端方法
列出值區中的物件	Client.list_blobs 請參閱簡單的程式碼範例，以及 模擬目錄模式的範例。 如要逐頁瀏覽物件清單，請使用 pages 屬性，該屬性是 Client.list_blobs 傳回的疊代器物件。
寫入儲存空間	blob.upload_from_file blob.upload_from_filename blob.upload_from_string 請參閱程式碼範例。
指定 ACL	如要套用預先定義的 ACL，請在建立值區或建立物件時使用 predefined_acl 參數。 如要進行更精細的控制，請使用 bucket.acl.reload() 或 blob.acl.reload() 擷取目前定義的任何 ACL。然後使用 ACL 方法新增或移除 ACL。請參閱程式碼範例。
從儲存空間讀取	blob.download_to_file blob.download_to_filename blob.download_as_string 請參閱程式碼範例。
刪除物件	blob.delete 請參閱程式碼範例。
複製物件	bucket.copy_blob 請參閱程式碼範例。
讀取物件的中繼資料	blob.propertyname 和 blob.metadata 請參閱程式碼範例。

測試更新

您可以在本機環境中測試應用程式更新，但所有 Cloud Storage 要求都必須透過網際網路傳送至實際的 Cloud Storage bucket。App Engine 和 Cloud Storage 都不提供 Cloud Storage 模擬器。

如要進一步瞭解如何測試 Python 3 應用程式，請參閱「測試及部署應用程式」。

部署您的應用程式

準備好部署應用程式後，請按照下列步驟操作：

1. 在 App Engine 上測試應用程式。

2. 如果應用程式順利執行，請使用流量分配，逐步增加更新版應用程式的流量。在將更多流量導向更新版應用程式前，請密切監控應用程式，確保沒有任何問題。