部署基本 "；Google 翻譯"Python 2 Cloud Run 上的應用程式 (Docker)

1. 總覽

這一系列的程式碼研究室 (自學式實作教學課程) 旨在協助開發人員瞭解部署應用程式時的各種選項。在本程式碼研究室中，您將瞭解如何透過 Python 使用 Google Cloud Translation API，並在本機執行或部署至 Cloud 無伺服器運算平台 (App Engine、Cloud Functions 或 Cloud Run)。您可以在本教學課程的存放區中找到範例應用程式，只要稍做設定變更，就能以 (至少) 八種不同方式部署：

本機 Flask 伺服器 (Python 2)
本機 Flask 伺服器 (Python 3)
App Engine (Python 2)
App Engine (Python 3)
Cloud Functions (Python 3)
Cloud Run (透過 Docker 的 Python 2)
Cloud Run (透過 Docker 使用 Python 3)
Cloud Run (透過 Cloud Buildpacks 進行 Python 3)

本程式碼研究室著重於將這個應用程式部署至上述粗體平台。

課程內容

使用 Google Cloud API，特別是 Cloud Translation API (進階/v3)
在本機執行基本網頁應用程式，或部署至 Cloud 無伺服器運算平台

軟硬體需求

Google Cloud 專案，並啟用 Cloud Billing 帳戶
已安裝 Flask (用於在本機執行)，或已啟用雲端無伺服器運算平台 (用於雲端部署)
Python 基礎技能
熟悉基本作業系統指令

問卷調查

您會如何使用本教學課程？

閱讀並完成練習

僅閱讀

你對 Python 的使用體驗如何？

新手

中級

熟練

您對使用 Google Cloud 服務的體驗滿意嗎？

新手

中級

熟練

2. 設定和需求條件

自修實驗室環境設定

登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果沒有 Gmail 或 Google Workspace 帳戶，請先建立帳戶。

專案名稱是這個專案參與者的顯示名稱。這是 Google API 未使用的字元字串，您隨時可以更新。
專案 ID 在所有 Google Cloud 專案中不得重複，且設定後即無法變更。Cloud 控制台會自動產生專屬字串，通常您不需要在意該字串為何。在大多數程式碼研究室中，您需要參照專案 ID (通常會標示為 PROJECT_ID)，因此如果您不喜歡該字串，可以產生另一個隨機字串，或是嘗試使用自己的字串，看看是否可用。專案建立後，系統就會「凍結」該值。
還有第三個值，也就是部分 API 使用的「專案編號」。如要進一步瞭解這三種值，請參閱說明文件。

接著，您需要在 Cloud 控制台中啟用帳單，才能使用 Cloud 資源/API。完成本程式碼研究室的費用應該不高，甚至完全免費。如要停用資源，避免在本教學課程結束後繼續產生帳單費用，請按照程式碼研究室結尾的「清除」操作說明操作。Google Cloud 新使用者可參加價值$300 美元的免費試用計畫。

3. 啟用 Translation API

啟用 Cloud API

本節將說明如何啟用 Google API。針對範例應用程式，您將啟用 Cloud Translation API、Cloud Run 和 Cloud Artifact Registry。

簡介

無論您要在應用程式中使用哪個 Google API，都必須啟用。以下範例說明如何啟用 Cloud Vision API。瞭解如何啟用一個 Cloud API 後，您就能啟用其他 API，因為程序類似。

方法 1：透過 Cloud Shell 或指令列介面

雖然透過 Cloud 控制台啟用 API 是較常見的做法，但有些開發人員偏好透過指令列完成所有作業。如要這麼做，您需要查詢 API 的「服務名稱」。這看起來像是網址：SERVICE_NAME.googleapis.com。您可以在「支援的產品圖表」中找到這些項目，也可以使用 Google Discovery API 以程式輔助方式查詢。

取得這項資訊後，您可以使用 Cloud Shell (或已安裝 gcloud 指令列工具的本機開發環境) 啟用 API，方法如下：

gcloud services enable SERVICE_NAME.googleapis.com

舉例來說，下列指令會啟用 Cloud Vision API：

gcloud services enable vision.googleapis.com

這個指令會啟用 App Engine：

gcloud services enable appengine.googleapis.com

您也可以透過單一要求啟用多個 API。舉例來說，這個指令列會啟用 Cloud Run、Cloud Artifact Registry 和 Cloud Translation API：

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

方法 2：透過 Cloud 控制台

您也可以在 API 管理工具中啟用 Vision API。在 Cloud 控制台中，前往 API 管理工具，然後選取「程式庫」。

如要啟用 Cloud Vision API，請在搜尋列中輸入「vision」，系統會顯示所有符合您輸入內容的項目：

選取要啟用的 API，然後按一下「啟用」：

費用

雖然許多 Google API 都能免費使用，但 Google Cloud 產品和 API 並非免費。啟用 Cloud API 時，系統可能會要求您提供有效的帳單帳戶。但請注意，部分 Google Cloud 產品提供「永久免費」層級 (每日/每月)，您必須超出該層級才會產生帳單費用；否則，系統不會向您的信用卡 (或指定的帳單付款方式) 收費。

啟用任何 API 前，使用者應先參考定價資訊，特別注意是否有免費層級，以及免費層級的內容。如果您要啟用 Cloud Vision API，請查看定價資訊頁面。Cloud Vision 確實提供免費配額，只要每月總用量不超過上限，就不會產生任何費用。

Google API 的定價和免費層級各不相同。範例：

Google Cloud/GCP：每項產品的計費方式不同，一般是依據 vCPU 週期、儲存空間用量、記憶體用量或用量計費；詳情請參閱上文的免費層級資訊。
Google 地圖：提供一系列 API，使用者每月可獲得 $200 美元的免費額度。
Google Workspace (舊稱 G Suite) API：只要支付 Workspace 月費，即可免費使用 (設有上限)，因此使用 Gmail、Google 雲端硬碟、日曆、文件、試算表和簡報 API 時，不會直接產生費用。

不同 Google 產品的計費方式不同，因此請務必參閱 API 的說明文件，瞭解相關資訊。

摘要

現在您已瞭解如何啟用 Google API，請前往 API 管理工具，並啟用 Cloud Translation API、Cloud Run 和 Cloud Artifact Registry (如果尚未啟用)。您啟用前者是因為我們的應用程式會使用該項目。您啟用後者，是因為容器映像檔會先儲存在這裡，然後再部署來啟動 Cloud Run 服務，因此您必須啟用該服務。如要使用 gcloud 工具一次啟用所有 API，請改為在終端機中發出下列指令：

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

雖然整體「永久免費」方案摘要頁面未列出每月配額，但Translation API 的價格頁面指出，所有使用者每月都可翻譯固定數量的字元。只要不超過該門檻，就不會產生任何 API 費用。如有其他 Google Cloud 相關費用，我們會在最後的「清除」一節中討論。

4. 取得範例應用程式程式碼

在本機或 Cloud Shell 中複製存放區的程式碼 (使用 git clone 指令)，或從綠色的「Code」按鈕下載 ZIP 檔案，如下列螢幕截圖所示：

現在您已備妥所有項目，請建立資料夾的完整副本，以便進行這個教學課程，因為這可能涉及刪除或變更檔案。如要進行其他部署作業，可以複製原始部署作業，不必再次複製或下載。

5. 範例應用程式導覽

這個範例應用程式是簡單的 Google 翻譯衍生版本，會提示使用者輸入英文文字，並提供該文字的西班牙文翻譯。現在開啟 main.py 檔案，看看實際運作情形。省略有關授權的註解行後，頂端和底部看起來會像這樣：

from flask import Flask, render_template, request
import google.auth
from google.cloud import translate

app = Flask(__name__)
_, PROJECT_ID = google.auth.default()
TRANSLATE = translate.TranslationServiceClient()
PARENT = 'projects/{}'.format(PROJECT_ID)
SOURCE, TARGET = ('en', 'English'), ('es', 'Spanish')

# . . . [translate() function definition] . . .

if __name__ == '__main__':
    import os
    app.run(debug=True, threaded=True, host='0.0.0.0',
            port=int(os.environ.get('PORT', 8080)))

匯入作業會帶入 Flask 功能、google.auth 模組和 Cloud Translation API 用戶端程式庫。
全域變數代表 Flask 應用程式、Cloud 專案 ID、Translation API 用戶端、Translation API 呼叫的父項「位置路徑」，以及來源和目標語言。在本例中，這些值是英文 (en) 和西班牙文 (es)，但您可以隨意將這些值變更為 Cloud Translation API 支援的其他語言代碼。
底部的 if 大型區塊用於教學課程，在本機執行這個應用程式，也就是利用 Flask 開發伺服器提供應用程式。如果網頁伺服器未併入容器，這個區段也會用於 Cloud Run 部署作業教學課程。系統會要求您在容器中啟用伺服器套裝組合，但如果您忽略這項要求，應用程式程式碼就會改用 Flask 開發伺服器。(這不是 App Engine 或 Cloud Functions 的問題，因為這些平台是以來源為基礎，也就是說，Google Cloud 會提供並執行預設的網頁伺服器)。

最後，main.py 中間是應用程式的核心，也就是 translate() 函式：

@app.route('/', methods=['GET', 'POST'])
def translate(gcf_request=None):
    """
    main handler - show form and possibly previous translation
    """

    # Flask Request object passed in for Cloud Functions
    # (use gcf_request for GCF but flask.request otherwise)
    local_request = gcf_request if gcf_request else request

    # reset all variables (GET)
    text = translated = None

    # if there is data to process (POST)
    if local_request.method == 'POST':
        text = local_request.form['text']
        data = {
            'contents': [text],
            'parent': PARENT,
            'target_language_code': TARGET[0],
        }
        # handle older call for backwards-compatibility
        try:
            rsp = TRANSLATE.translate_text(request=data)
        except TypeError:
            rsp = TRANSLATE.translate_text(**data)
        translated = rsp.translations[0].translated_text

    # create context & render template
    context = {
        'orig':  {'text': text, 'lc': SOURCE},
        'trans': {'text': translated, 'lc': TARGET},
    }
    return render_template('index.html', **context)

主要函式會負責接收使用者輸入內容，並呼叫 Translation API 執行繁重的工作。以下將詳細說明：

使用 local_request 變數檢查要求是否來自 Cloud Functions。Cloud Functions 會傳送自己的 Flask Request 物件，而所有其他物件 (在本機執行或部署至 App Engine 或 Cloud Run) 則會直接從 Flask 取得要求物件。
重設表單的基本變數。這主要是針對 GET 要求，因為 POST 要求會有資料取代這些要求。
如果是 POST，請擷取要翻譯的文字，並建立代表 API 中繼資料需求的 JSON 結構。然後呼叫 API，如果使用者採用舊版程式庫，則會回復為舊版 API。
無論如何，請將實際結果 (POST) 或沒有資料 (GET) 格式化為範本內容並算繪。

應用程式的視覺部分位於範本 index.html 檔案中。畫面會顯示先前翻譯的結果 (如果沒有則為空白)，然後顯示要求翻譯內容的表單：

<!doctype html>
<html><head><title>My Google Translate 1990s</title><body>
<h2>My Google Translate (1990s edition)</h2>

{% if trans['text'] %}
    <h4>Previous translation</h4>
    <li><b>Original</b>:   {{ orig['text'] }}  (<i>{{ orig['lc'][0] }}</i>)</li>
    <li><b>Translated</b>: {{ trans['text'] }} (<i>{{ trans['lc'][0] }}</i>)</li>
{% endif %}

<h4>Enter <i>{{ orig['lc'][1] }}</i> text to translate to <i>{{ trans['lc'][1] }}</i>:</h4>
<form method="POST"><input name="text"><input type="submit"></form>
</body></html>

6. 部署服務

現在，您可以執行下列指令，將翻譯服務部署至 Cloud Run：

gcloud run deploy translate --source . --allow-unauthenticated --platform managed

輸出內容應如下所示，並提供後續步驟的一些提示：

$ gcloud run deploy translate --source . --allow-unauthenticated --platform managed
Please specify a region:
 [1] asia-east1
 [2] asia-east2
. . . (other regions) . . .
 [28] us-west4
 [29] cancel
Please enter your numeric choice:  REGION_CHOICE

To make this the default region, run `gcloud config set run/region REGION`.

Deploying from source requires an Artifact Registry repository to
store build artifacts. A repository named [cloud-run-source-deploy] in
 region [REGION] will be created.

Do you want to continue (Y/n)?

This command is equivalent to running "gcloud builds submit --pack image=[IMAGE] ." and "gcloud run deploy translate --image [IMAGE]"

Building . . . and deploying container to Cloud Run service [translate] in project [PROJECT_ID] region [REGION]
✓ Building and deploying... Done.
  ✓ Creating Container Repository...
  ✓ Uploading sources...
  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/60e1b
  9bb-b991-4b4e-8d8a-HASH?project=PROJECT_NUMBER].
  ✓ Creating Revision...
  ✓ Routing traffic...
  ✓ Setting IAM Policy...
Done.
Service [translate] revision [translate-00001-xyz] has been deployed and is serving 100 percent of traffic.
Service URL: https://SVC_NAME-HASH-REG_ABBR.a.run.app

現在您的應用程式已在全球推出，您應該可以透過含有專案 ID 的網址存取應用程式，如部署輸出內容所示：

翻譯內容，看看這項功能如何運作！

7. 結語

恭喜！您已瞭解如何啟用 Cloud Translation API、取得必要憑證，以及將簡單的網頁應用程式部署至 Python 2 Cloud Run！如要進一步瞭解這項部署作業，請參閱存放區中的這個表格。

清除所用資源

Cloud Translation API 每月提供固定額度的免費翻譯字元。App Engine 也提供免費配額，Cloud Functions 和 Cloud Run 也是如此。如果超過任一限制，就會產生費用。如果您打算繼續下一個程式碼研究室，則不必關閉應用程式。

不過，如果您還沒準備好進行下一個教學課程，或是擔心網際網路會發現您剛部署的應用程式，請停用 App Engine 應用程式、刪除 Cloud Function 或停用 Cloud Run 服務，以免產生費用。準備好進行下一個程式碼研究室時，可以重新啟用這項功能。另一方面，如果您不打算繼續使用這個應用程式或其他程式碼研究室，並想徹底刪除所有內容，可以關閉專案。

此外，部署至 Google Cloud 無伺服器運算平台會產生少許建構和儲存空間費用。Cloud Build 和 Cloud Storage 都有各自的免費配額。為提高透明度，Cloud Build 會建構應用程式映像檔，然後儲存在 Cloud Container Registry 或後繼服務 Artifact Registry 中。儲存該圖片會耗用部分配額，將圖片傳輸至服務時也會耗用網路輸出量。不過，你所在的區域可能沒有這類免付費層級，因此請留意儲存空間用量，盡量減少潛在費用。

8. 其他資源

在接下來的章節中，您可以找到額外的閱讀資料和建議練習，進一步擴充完成本教學課程所學到的知識。

其他研究

現在您已具備 Translation API 的使用經驗，接下來請完成一些額外練習，進一步提升技能。如要繼續學習，請修改範例應用程式，完成下列操作：

完成本程式碼研究室的所有其他版本，即可在本機執行或部署至 Google Cloud 無伺服器運算平台 (請參閱 repo README)。
使用其他程式設計語言完成本教學課程。
變更這個應用程式，支援不同的來源或目標語言。
升級這個應用程式，即可將文字翻譯成多種語言；變更範本檔案，加入支援的目標語言下拉式選單。

瞭解詳情

Google App Engine

Google Cloud Functions

Google Cloud Run

Google Cloud Buildpacks、Container Registry、Artifact Registry

Google Cloud Translation 和 Google ML Kit

其他 Google Cloud 產品/頁面

Python 和 Flask

Flask

授權

本教學課程採用創用 CC 姓名標示 2.0 通用授權，而存放區中的原始碼則採用 Apache 2 授權。