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

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

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

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

相似處：

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

  Cloud 用戶端程式庫也支援其他功能，例如建立和標記儲存桶，以及擷取舊版物件。

差異：

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

• App Engine 用戶端程式庫要求您使用存取控制清單 (ACL) 來控管值區和物件的存取權。不過，Cloud Storage 和 Cloud 用戶端程式庫支援兩個系統，可授予使用者存取值區和物件的權限：ACL 和統一值區層級存取權。統一值區層級存取權可讓您在所有 Cloud 資源中提供更簡單、一致的存取權控管體驗。

  遷移至 Cloud 用戶端程式庫後，您在 App Engine 用戶端程式庫中使用的所有 ACL 仍會對現有儲存桶生效，您也可以視需要繼續使用 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 程式庫，應用程式收到要求時，您會在「Logs Explorer」中看到 SSL 錯誤。

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

   google-cloud-storage==1.24.1
   

   建議您使用 1.24.1 版的 Cloud Storage 用戶端程式庫，因為它支援 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 物件。用戶端包含連線至 Cloud Storage 所需的憑證和其他資料。例如：

from google.cloud import storage

client = storage.Client()

在先前所述的預設授權情境中，Cloud Storage 用戶端包含 App Engine 預設服務帳戶的憑證，該帳戶已獲授權與專案的值區和物件互動。如果您並未使用這個預設情境，請參閱「應用程式預設憑證 (ADC)」一文，瞭解如何提供憑證。

使用 Cloud 用戶端程式庫方法

下表概略說明在實作特定 Cloud Storage 功能時，應使用 Cloud 用戶端程式庫的哪些方法。

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

Cloud Storage 功能	雲端用戶端方法
列出值區中的物件	Client.list_blobs 請參閱簡單的程式碼範例和 模擬目錄模式的範例。 如要逐頁瀏覽物件清單，請使用 Client.list_blobs 傳回的迭代器物件 pages 屬性。
寫入儲存空間	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 值區。App Engine 和 Cloud Storage 皆未提供 Cloud Storage 模擬器。

如要進一步瞭解測試 Python 2 應用程式，請參閱「使用本機開發伺服器」一文。

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

部署您的應用程式

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

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

2. 如果應用程式運作時沒有發生錯誤，請使用流量分配功能，逐步增加更新版應用程式的流量。在將更多流量導向更新版應用程式之前，請密切監控應用程式是否有任何問題。