App Engine 和 Google Cloud Storage 範例

瞭解如何啟用 Cloud Storage 對 App Engine Python 應用程式的存取權,以及建立、寫入、讀取及列出 Cloud Storage 值區中的檔案。

本教學課程的使用前提是您熟悉 Python,並已完成 Python App Engine 標準環境的快速入門導覽課程

執行本文範例時,系統會執行指令碼並將輸出內容寫入到瀏覽器。該指令碼會示範 Cloud Storage 用戶端程式庫的下列功能:

  • 建立檔案並將檔案寫入至值區。
  • 讀取檔案並取得檔案的中繼資料。
  • 建立多個檔案並列出值區中的這些檔案。
  • 列出剛新增至值區的檔案。
  • 讀取同一批檔案。
  • 刪除該批檔案。

目標

  • 逐步操作 Python 專案以檢視所要的版面配置與檔案。
  • 瞭解用於連線至 Cloud Storage 的程式碼。
  • 瞭解用於建立、寫入、讀取、列出及刪除檔案的程式碼。
  • 瞭解用於重試的程式碼。
  • 在本機開發伺服器上建構並測試應用程式。
  • 在 Google App Engine 上部署應用程式至實際工作環境。

費用

App Engine 提供有限度的免費使用。如果您的 App Engine 總使用量並未超過 App Engine 免費配額指定的限制,則執行本教學課程無需收費。

事前準備

在執行此範例前,您需要有專案 ID、gcloud 指令列工具,以及 Cloud Storage 值區:

  1. 建立新的 GCP 主控台專案,或從 Google Cloud Platform 主控台擷取現有專案的專案 ID:

    前往「Project」(專案) 頁面

    提示:您可以透過 gcloud 指令列工具擷取現有專案 ID 的清單。

  2. 安裝並初始化 Google Cloud SDK:

    下載 SDK

  3. 啟動預設的 Cloud Storage 值區

複製教學課程專案

若要複製專案:

  1. 將用戶端程式庫和範例 (示範) 應用程式複製到本機電腦。

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    

    或者,您也可以下載 zip 格式的範例,然後解壓縮該檔案。

  2. 在複製或下載的專案中,前往適當的目錄:

    cd python-docs-samples/appengine/standard/storage/appengine-client
    

安裝依附元件

您可以使用 virtualenv 工具在系統中建立乾淨的 Python 環境。就 App Engine 開發作業而言,這有助於確保您在本機測試的程式碼類似於其要部署的目的地環境。如要進一步瞭解,請參閱使用第三方程式庫

若要安裝 virtualenv 以及範例的依附元件:

Mac OS / Linux

  1. 如果沒有 virtualenv,請使用 pip 安裝至整個系統。
    sudo pip install virtualenv
  2. 在專案外部的目錄中建立獨立的 Python 環境並加以啟動。
    virtualenv env
    source env/bin/activate
  3. 前往專案目錄,並安裝依附元件:
    cd YOUR_PROJECT
    pip install -t lib -r requirements.txt

Windows

如果您已安裝 Cloud SDK,那麼電腦上應該會有 Python 2.7,該程式語言通常位於 C:\python27_x64\ (如果電腦是 64 位元系統)。請使用 PowerShell 執行 Python 套件。

  1. 尋找已安裝的 PowerShell
  2. 以滑鼠右鍵按一下 PowerShell 的捷徑,然後以系統管理員的身分啟動 PowerShell。
  3. 嘗試執行 python 指令。如果找不到該指令,請將 Python 資料夾新增至環境的 PATH
    $env:Path += ";C:\python27_x64\"
  4. 如果沒有 virtualenv,請使用 pip 安裝至整個系統:
    python -m pip install virtualenv
  5. 在專案外部的目錄中建立獨立的 Python 環境,並啟動該環境。
    python -m virtualenv env
    env\Scripts\activate
  6. 前往專案目錄,並且安裝依附元件:
    cd YOUR_PROJECT
    python -m pip install -t lib -r requirements.txt

您所複製或下載的程式碼範例已經包含 appengine_config.py 檔案,在指示 App Engine 使用 lib 資料夾在本機以及在部署時載入依附元件時,您必須使用此檔案。

本機執行

若要在本機執行範例:

  1. 在專案子目錄 python-docs-samples/appengine/standard/storage/appengine-client 中,執行 [本機開發伺服器] 中的應用程式:

    dev_appserver.py .
    
  2. 等待畫面出現類似以下的成功訊息:

    INFO     2016-04-12 21:33:35,446 api_server.py:205] Starting API server at: http://localhost:36884
    INFO     2016-04-12 21:33:35,449 dispatcher.py:197] Starting module "default" running at: http://localhost:8080
    INFO     2016-04-12 21:33:35,449 admin_server.py:116] Starting admin server at: http://localhost:8000
    
  3. 使用瀏覽器造訪下列網址:

    http://localhost:8080/

    載入網頁時將執行應用程式,並在瀏覽器上顯示輸出內容以表示執行的內容。輸出畫面類似:

    Hello_Storage

  4. 按下 Control-C 鍵以終止開發伺服器。

app.yaml 逐步操作說明

app.yaml 檔案提供應用程式設定的詳細資料:

runtime: python27
api_version: 1
threadsafe: yes

env_variables:

handlers:
- url: /blobstore.*
  script: blobstore.app

- url: /.*
  script: main.app

如要進一步瞭解這個檔案的可用設定選項,請參閱 app.yaml 參考資料

匯入逐步操作說明

main.py 檔案包含透過用戶端程式庫存取 Cloud Storage 時使用的一般匯入項目:

import os

import cloudstorage
from google.appengine.api import app_identity

import webapp2

您需要 os 模組和 app_identity API,在執行階段取得預設值區名稱。您需要這個值區名稱才能進行所有的 Cloud Storage 存取作業。

此範例還使用 webapp2 網路架構。

指定 Cloud Storage 值區

在 Cloud Storage 中執行任何作業前,您需要先提供值區名稱。最簡單的方法是使用專案的預設值區,取得方式如下:

def get(self):
    bucket_name = os.environ.get(
        'BUCKET_NAME', app_identity.get_default_gcs_bucket_name())

    self.response.headers['Content-Type'] = 'text/plain'
    self.response.write(
        'Demo GCS Application running from Version: {}\n'.format(
            os.environ['CURRENT_VERSION_ID']))
    self.response.write('Using bucket name: {}\n\n'.format(bucket_name))

將檔案寫入至 Cloud Storage

以下範例說明如何寫入至值區:

def create_file(self, filename):
    """Create a file."""

    self.response.write('Creating file {}\n'.format(filename))

    # The retry_params specified in the open call will override the default
    # retry params for this particular file handle.
    write_retry_params = cloudstorage.RetryParams(backoff_factor=1.1)
    with cloudstorage.open(
        filename, 'w', content_type='text/plain', options={
            'x-goog-meta-foo': 'foo', 'x-goog-meta-bar': 'bar'},
            retry_params=write_retry_params) as cloudstorage_file:
                cloudstorage_file.write('abcde\n')
                cloudstorage_file.write('f'*1024*4 + '\n')
    self.tmp_filenames_to_clean_up.append(filename)

請注意,呼叫 open 以開啟檔案進行寫入時,程式碼範例會指定特定 Cloud Storage 標頭,針對檔案寫入自訂中繼資料;使用 cloudstorage.stat 可擷取這些中繼資料。您可以在 cloudstorage.open 參考資料中找到受支援標頭的清單。

此外,這個範例並未設定 x-goog-acl 標頭。這表示公開讀取權限的預設 Cloud Storage ACL 將在寫入至值區時套用至物件。

最後,在完成寫入時需要呼叫 close 關閉檔案。如果沒有執行此操作,檔案就不會寫入至 Cloud Storage。請注意,在呼叫 close 後,就無法在檔案中附加任何內容。如需修改檔案,您必須在寫入模式中再次開啟檔案。請注意,這樣做會覆寫原先內容,並非額外附加新內容。

讀取 Cloud Storage 中的檔案

以下範例說明如何讀取值區中的檔案:

def read_file(self, filename):
    self.response.write(
        'Abbreviated file content (first line and last 1K):\n')

    with cloudstorage.open(filename) as cloudstorage_file:
        self.response.write(cloudstorage_file.readline())
        cloudstorage_file.seek(-1024, os.SEEK_END)
        self.response.write(cloudstorage_file.read())

這個範例說明了如何使用 seek 來顯示讀取中檔案裡的所選行 (在此範例中為第一行和最後一千行)。

請注意,上述程式碼並未指定要使用哪種模式開啟檔案以進行讀取。open 預設為唯讀模式。

列出值區內容

以下範例程式碼說明如何使用 marker 逐頁瀏覽含有大量檔案的值區,並使用 max_keys 參數逐頁瀏覽值區內容的清單:

def list_bucket(self, bucket):
    """Create several files and paginate through them."""

    self.response.write('Listbucket result:\n')

    # Production apps should set page_size to a practical value.
    page_size = 1
    stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size)
    while True:
        count = 0
        for stat in stats:
            count += 1
            self.response.write(repr(stat))
            self.response.write('\n')

        if count != page_size or count == 0:
            break
        stats = cloudstorage.listbucket(
            bucket + '/foo', max_keys=page_size, marker=stat.filename)

請注意,完整的檔案名稱會顯示為單一字串,不會有目錄分隔字元。如要在顯示檔案時一併顯示其更易於辨識的目錄階層,請將 delimiter 參數設為您要使用的目錄分隔字元。

刪除檔案

這個程式碼範例說明如何刪除檔案 (在此範例中為刪除應用程式執行期間新增的所有檔案)。由於這只是本範例的清除功能,並不會在程式碼執行刪除:

def delete_files(self):
    self.response.write('Deleting files...\n')
    for filename in self.tmp_filenames_to_clean_up:
        self.response.write('Deleting file {}\n'.format(filename))
        try:
            cloudstorage.delete(filename)
        except cloudstorage.NotFoundError:
            pass

部署範例

若要在 App Engine 上部署並執行範例:

  1. app.yaml 檔案所在的 python-docs-samples/appengine/standard/storage/appengine-client 目錄中執行下列指令,以便上傳應用程式範例:

    gcloud app deploy
    

    選用標記:

    • 加上 --project 標記可指定替代 GCP 主控台專案 ID,而不使用您在 gcloud 工具中初始化為預設值的 ID。範例:--project [YOUR_PROJECT_ID]
    • 加上 -v 標記可指定版本 ID;如未加入,將由系統自動產生。範例:-v [YOUR_VERSION_ID]

    提示:如果您指定的是先前上傳的應用程式版本 ID,部署將覆寫 App Engine 上的現有版本。這未必是最理想的情況,尤其是 App Engine 上的版本可能正在提供流量。若要避免中斷連線至應用程式的流量,您可以使用其他版本 ID 來部署應用程式,然後將流量移至該版本。如要進一步瞭解如何移動流量,請參閱流量拆分

  2. 在部署程序完成後,您可以執行下列指令,在 https://[YOUR_PROJECT_ID].appspot.com 檢視應用程式:

    gcloud app browse
    

    demo 應用程式會在載入網頁時執行,這點與在本機執行時相同。不過,此時的應用程式會實際寫入 Cloud Storage 值區以及從中讀取。

如要進一步瞭解如何從指令列部署應用程式,請參閱部署 Python 2 應用程式

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Python 2 適用的 App Engine 標準環境