開始使用 Python 適用的 Cloud Endpoints Frameworks

{% include "_shared/_delete_tutorial_resources.html" with name="Getting started with Cloud Endpoints Frameworks for Python" %}

本頁面說明如何使用 Python 適用的 Cloud Endpoints Frameworks 進行設定和部署，以及傳送要求至範例 API。Python 適用的 Endpoints Frameworks 已經與 App Engine 標準 Python 2.7 執行階段環境整合。Endpoints Frameworks 的工具、程式庫以及功能，可讓您從 App Engine 應用程式產生 API 和用戶端程式庫。

目標

在逐步進行本教學課程時，請使用以下概略工作清單。您必須完成所有工作才能成功傳送要求至 API。

設定 Google Cloud Platform (GCP) 專案。請參閱事前準備一節。
安裝所需的軟體，並建立一個 App Engine 應用程式。請參閱安裝並設定所需的軟體一節。
下載範例程式碼。請參閱取得範例程式碼一節。
產生 OpenAPI 文件。請參閱設定 Endpoints 一節。
部署 Endpoints 設定以建立 Endpoints 服務。請參閱部署 Endpoints 設定一節。
在您的電腦上執行範例。請參閱在本機執行範例一節。
建立後端以提供及部署 API。請參閱部署 API 後端一節。
傳送要求至 API。請參閱傳送要求至 API 一節。
追蹤 API 活動。請參閱追蹤 API 活動一節。
避免系統向您的 GCP 帳戶收取相關費用。請參閱清除所用資源一節。

費用

本教學課程使用下列 Google Cloud Platform 計費元件：

您可以使用 Pricing Calculator，根據您的預測使用量來產生預估費用。初次使用 GCP 的使用者可能符合申請免費試用的資格。

完成此教學課程後，您可刪除已建立的資源以免繼續計費。詳情請參閱清除所用資源一節。

事前準備

登入您的 Google 帳戶。
如果您沒有帳戶，請申請新帳戶。
選取或建立 Google Cloud Platform 專案。

附註：如果您不打算保留您在這項程序中建立的資源，請建立新專案，而不要選取現有專案，這樣在完成這些步驟之後，您就可以刪除專案，並移除與該專案相關聯的所有資源。

前往「Manage resources」(管理資源) 頁面
請確認您已啟用 Google Cloud Platform 專案的計費功能。

瞭解如何啟用計費功能
記下 GCP 專案 ID，以便在稍後使用。

安裝並設定所需的軟體

依照安裝 Python 專用 Cloud SDK 的操作說明，設定 App Engine 標準開發環境。請確認您已經安裝 app-engine-python 和 app-engine-python-extras gcloud 元件。
執行下列指令：
1. 更新 Cloud SDK。
```
gcloud components update
```
2. 確認 Cloud SDK (gcloud) 已取得授權，可存取您在 GCP 上的資料與服務：
```
gcloud auth login
```
3. 在隨即開啟的新瀏覽器分頁中，選取一個帳戶。
4. 將預設專案設為您的專案 ID。
```
gcloud config set project [YOUR_PROJECT_ID]
```
  請將 [YOUR_PROJECT_ID] 替換成您的 GCP 專案 ID。如果您有其他 GCP 專案，而且想要使用 gcloud 管理這些專案，請參閱「管理 Cloud SDK 設定」一文。
您需要一個可以將要求傳送至範例 API 的應用程式。
- Linux 和 macOS 使用者：本教學課程提供了一個使用 curl 的範例，該工具通常已預先安裝在您的作業系統中。如果您沒有 curl，請前往 curl 的版本與下載頁面下載需要的檔案。
- Windows 使用者：本教學課程提供使用 Invoke-WebRequest 的範例，而 PowerShell 3.0 以上版本均支援該工具。
確認您的 Python 開發環境包含 pip。
確認您可以編譯 Python 的 C 擴充功能。
- Windows系統：需要 Microsoft Visual C++ 9.0 以上版本。您可以從 Microsoft 下載中心下載 Python 2.7 適用的 Microsoft Visual C++ 編譯器。
- 其他作業系統：視您的作業系統而定，您可能需要安裝編譯器工具 (有時在套件中會稱為 build-essential) 或 Python 開發標頭 (有時在套件中會稱為 python-dev)。
針對 Linux 系統，請將 ENDPOINTS_GAE_SDK 環境變數設定為 App Engine SDK 資料夾的路徑：[Path-to-Google-Cloud-SDK]/platform/google_appengine。

將 [Path-to-Google-Cloud-SDK] 替換為以下指令的輸出值：
```
gcloud info --format="value(installation.sdk_root)"
```
建立 App Engine 應用程式：
1. 選取您要在其中建立 App Engine 應用程式的地區。請執行以下指令取得地區清單：
```
gcloud app regions list
```
2. 使用下列指令建立 App Engine 應用程式。請將 [YOUR_PROJECT_ID] 改成您的 GCP 專案 ID，並將 [YOUR_REGION] 改成您要在其中建立 App Engine 應用程式的地區。
```
gcloud app create \
--project=[YOUR_PROJECT_ID] \
--region=[YOUR_REGION]
```
  例如：
```
gcloud app create --project=example-project-12345 --region=us-central
```

取得範例程式碼

從 Github 複製範例 API：

#NOTYPO

將範例存放區複製到本機電腦中。

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

變更為包含範例程式碼的目錄：

cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo

設定 Endpoints

如要設定 Endpoints，您必須先安裝 Endpoints Frameworks Python 程式庫。然後，請使用 Endpoints Frameworks 程式庫中的工具來產生範例 API 的 OpenAPI 文件。您需要 Endpoints Frameworks 程式庫和 OpenAPI 文件，才能讓 Endpoints 管理 API。詳情請參閱「新增 API 管理」一文。

安裝 Endpoints Frameworks 程式庫

本節將逐步引導您使用 Python 的 pip，將 Endpoinds Frameworks 程式庫新增至範例 API 的專案目錄。

如何將 Endpoints Frameworks 程式庫新增到範例：

確認您位於範例 API 的主目錄：python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo。
在專案中建立 /lib 子目錄：
```
mkdir lib
```
從範例主目錄 python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo 執行安裝指令：
```
pip install --target lib --requirement requirements.txt --ignore-installed
```
注意事項：
- 這個 pip 指令可能會使用 GNU 編譯器套件 (GCC) 來編譯擴充功能模組。如果您使用 macOS，且這是您第一次在系統上執行 GCC，則可能必須接受 Apple 的 XCode 授權，方法是執行 sudo xcodebuild -license。
- 如果您在電腦上安裝了多個版本的 Python，請確認您使用的 pip 版本能夠對應到您在本教學課程中使用的 Python 版本。如果版本不符 (例如，同時使用 Python 2.7 的 python 和 Python 3.4 的 pip)，可能會造成難以理解的錯誤。如有需要，您可將 pip 視為 Python 模組執行：將上述指定中的 pip 替換為 python -m pip。
- 如果 pip 在執行指令時，無法找到合適的套件，請嘗試執行 pip install --upgrade pip 來進行升級。升級完畢後，請再次嘗試安裝指令。
- 在某些 Debian 和 Ubuntu 版本上，pip 可能會發生錯誤，並顯示 DistutilsOptionError。如果您看到這個錯誤，請新增 --system 標記。

成功完成後，系統會將建構 Endpoints Frameworks 應用程式所需的檔案填入 lib 目錄。

產生 OpenAPI 文件

您可以使用 Endpoints Frameworks 程式庫中的工具，產生會描述範例程式碼的 REST API 文件。

如何產生 OpenAPI 文件：

確認您位於範例的主目錄：

python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo

產生 OpenAPI 文件：
```
python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [YOUR_PROJECT_ID].appspot.com
```
將 [YOUR_PROJECT_ID] 替換為 GCP 專案 ID，並請忽略顯示的警告。Endpoints 工具會在目前的目錄中，產生名為 echov1openapi.json 的 OpenAPI 文件。Endpoints 工具是根據在 @endpoints.api 修飾符中所指定服務的名稱和版本，對檔案進行命名。詳情請參閱建立 API。

Endpoints 會使用在 hostname 引數中指定的文字做為服務名稱。YOUR_PROJECT_ID.appspot.com 名稱格式與您在部署 API 至 App Engine 後端時自動建立的 DNS 項目相符。因此在這個案例中，Endpoints 服務名稱和完整網域名稱 (FQDN) 相同。

成功完成後，您會看到下列訊息：OpenAPI spec written to ./echov1openapi.json

部署 Endpoints 設定

您可以使用服務基礎架構部署 Endpoints 設定；服務基礎架構是 Google 的基礎服務平台，Endpoints 和其他服務使用此架構建立及管理 API 和服務。

如何部署設定檔：

確認您位於範例的主目錄：

python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo

執行下列指令，部署您在上一節產生的 OpenAPI 文件：
```
gcloud endpoints services deploy echov1openapi.json
```
這將建立新的 Endpoints 服務，而服務名稱就是您之前執行 Endpoints 工具來產生 OpenAPI 文件時，在 hostname 引數中指定的名稱。無論 Endpoints 服務名稱為何，當您在 App Engine 上部署 API 時，系統會以 YOUR_PROJECT_ID.appspot.com 名稱格式建立 DNS 記錄，而該名稱就是您在傳送要求至 API 時所使用的 FQDN。

Service Management 在建立和設定服務時，會輸出大量資訊至終端機，您可以放心地忽略有關 echov1openapi.json 中的路徑沒有要求 API 金鑰的警告。部署完成後，您將看到類似以下的訊息：
```
Service Configuration [2017-02-13r2] uploaded for service [example-project-12345.appspot.com]
```
在上方的範例中，2017-02-13-r2 是服務設定 ID，example-project-12345.appspot.com 則是服務名稱。

詳情請參閱 gcloud 參考說明文件中的 gcloud endpoints services deploy。

檢查必要服務

如要提供 API 管理，Endpoints Frameworks 需要使用以下服務：

名稱	標題
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API
`endpoints.googleapis.com`	Google Cloud Endpoints

在大多數情況下，gcloud endpoints services deploy 指令會啟用這些必要服務。雖然 gcloud 指令可以成功完成，但在下列狀況中無法啟用必要的服務：

您使用 Terraform 之類的第三方應用程式，而其中未包含這些服務。
您已將 Endpoints 設定部署至現有 GCP 專案，但在專案中已明確停用這些服務。

如要確認必要服務已啟用，請執行：

gcloud services list

如果必要的服務並未列出，請執行下列指令加以啟用：

gcloud services enable SERVICE_NAME

將 SERVICE_NAME 替換為要啟用的服務名稱。

如要進一步瞭解 gcloud 指令，請參閱 gcloud 服務。

在本機執行範例

當您部署 Endpoints 設定之後，就可以利用本機開發伺服器在本機執行範例。

確認您位於範例的主目錄：

python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo

啟動本機開發伺服器：
```
dev_appserver.py ./app.yaml
```
根據預設，開發伺服器會監聽 http://localhost:8080，正如利用 dev_appserver.py 輸出的 Google Cloud Platform 主控台記錄檔所示：
```
INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
```
將要求傳送到本機開發伺服器：

Linux 或 Mac OS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

在上述的 curl 中：

--data 選項指定要張貼至 API 的資料。
--header 選項指定資料採用 JSON 格式。

PowerShell

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

在上述範例中，前兩行的結尾為倒引號。當您將範例貼到 PowerShell 中時，請確保倒引號後面沒有空格。如需瞭解範例要求中使用的選項，請參閱 Microsoft 說明文件中的 Invoke-WebRequest。

API 會回應您傳送給它的訊息，並回覆以下內容：

{
 "message": "hello world"
}

部署 API 後端

到目前為止，您已經將 OpenAPI 文件部署到 Service Management，但還沒有部署會提供 API 後端的程式碼。本節將逐步引導您把範例 API 部署至 App Engine。

如何部署 API 後端：

執行以下指令顯示服務設定 ID：

gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com

將 [YOUR_PROJECT_ID] 替換為您的專案 ID，例如：

gcloud endpoints configs list --service=example-project-12345.appspot.com

在 python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo 目錄中開啟 app.yaml。

appengine/standard/endpoints-frameworks-v2/echo/app.yaml

前往 GitHub 查看

env_variables:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy swagger.json' command.
  ENDPOINTS_SERVICE_NAME: YOUR-PROJECT-ID.appspot.com
  ENDPOINTS_SERVICE_VERSION: 2016-08-01r0

在 env_variables 部分進行以下變更：
- 在 ENDPOINTS_SERVICE_NAME 欄位中，將 YOUR-PROJECT-ID 替換為您的 GCP 專案 ID。
- 在 ENDPOINTS_SERVICE_VERSION 欄位中，將文字替換為服務設定 ID，例如：
```
  ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com
  ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
```
執行下列指令：
```
gcloud app deploy
```
按照畫面上顯示的提示操作。請稍等片刻，等待部署成功，並請忽略警告訊息。部署完成後，您將看到類似以下的訊息：
```
File upload done.
Updating service [default]...done.
```
如果您收到錯誤訊息，請參閱 App Engine 說明文件的疑難排解一節。

建議您稍等幾分鐘，然後在 App Engine 完成初始化後向 API 傳送要求。

向範例 API 發送要求

Linux 或 Mac OS

請利用 curl 傳送 HTTP 要求，並將 [YOUR_PROJECT_ID] 替換成您的 GCP 專案 ID：

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

在上述的 curl 中：

--data 選項指定要張貼至 API 的資料。
--header 選項指定資料採用 JSON 格式。

PowerShell

利用 Invoke-WebRequest 來傳送 HTTP 要求。請將 [YOUR_PROJECT_ID] 替換成您的 GCP 專案 ID：

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} -URI `
     "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content

在上述範例中，前兩行的結尾為倒引號。當您將範例貼到 PowerShell 中時，請確保倒引號後面沒有空格。如欲瞭解範例要求中使用的選項，請參閱 Microsoft 說明文件中的 Invoke-WebRequest。

第三方應用程式

您可以使用諸如 Chrome 瀏覽器擴充功能 Postman 等第三方應用程式來傳送要求：

選取 POST 做為 HTTP 動詞。
針對標頭，選取鍵 content-type 和值 application/json。
針對主體，請輸入以下內容：
{"message":"hello world"}
請輸入範例應用程式的網址，例如：
https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

API 會回應您傳送給它的訊息，並回覆以下內容：

{
 "message": "hello world"
}

如果您未取得成功的回應，請參閱排解回應錯誤一文。

追蹤 API 活動

在 GCP 主控台的「Endpoints」>「Service」(服務) 頁面上，檢視您 API 的活動圖表。

前往 Endpoints 的「Services」(服務) 頁面

要求可能需要一些時間才能反映在圖表中。
在「Logs Viewer」(記錄檢視器) 頁面中，查看您的 API 要求記錄。

前往「Logs Viewer」(記錄檢視器) 頁面

建立 API 開發人員入口網站

您可以透過 Cloud Endpoints 入口網站建立開發人員入口網站，並將該網站用於與範例 API 進行互動。詳情請參閱 Cloud Endpoints 入口網站總覽。

清除所用資源

如要避免系統向您的 Google Cloud Platform 帳戶收取您在本教學課程中使用資源的相關費用：

前往 GCP 主控台的「Projects」(專案) 頁面。
前往專案頁面
在專案清單中選取要刪除的專案，然後按一下 [Delete] (刪除)。
在對話方塊中輸入專案 ID，按一下 [Shut down] (關閉) 即可刪除專案。

後續步驟

瞭解如何利用 JavaScript 用戶端進行驗證呼叫。
瞭解 Endpoints Frameworks 架構。
瞭解如何建立 API。
瞭解如何建立網路伺服器來提供 API。
瞭解如何透過不同的路徑提供 API。
瞭解如何監控您的 API。
瞭解如何使用 API 金鑰限制存取權限。
瞭解如何設定自訂網域名稱。
瞭解如何處理 API 版本管理。
瞭解支援選項。

目標

費用

事前準備

安裝並設定所需的軟體

取得範例程式碼

設定 Endpoints

安裝 Endpoints Frameworks 程式庫

產生 OpenAPI 文件

部署 Endpoints 設定

檢查必要服務

在本機執行範例

Linux 或 Mac OS

PowerShell

部署 API 後端

向範例 API 發送要求

Linux 或 Mac OS

PowerShell

第三方應用程式

追蹤 API 活動

建立 API 開發人員入口網站

清除所用資源

後續步驟

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