本頁面由 Cloud Translation API 翻譯而成。

開始使用 Python 適用的 Cloud Endpoints Frameworks

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

目標

請根據以下的主要工作清單，逐步進行本教學課程的各個步驟。您必須完成所有工作才能成功傳送要求至 API。

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

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

您可以使用 Pricing Calculator 根據預測用量產生預估費用。新 Google Cloud 使用者可能符合申請免費試用的資格。

完成本文件所述工作後，您可以刪除已建立的資源，避免繼續計費。詳情請參閱「清除所用資源」。

事前準備

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

記下 Google Cloud 專案 ID，以便在稍後使用。

安裝並設定所需的軟體

依照「安裝 Python 專用 Google Cloud CLI」中的操作說明，設定 App Engine 標準開發環境。請務必安裝 app-engine-python 和 app-engine-python-extras gcloud 元件。
執行下列指令：
1. 更新 gcloud CLI。
```
gcloud components update
```
2. 確認 Google Cloud CLI (gcloud) 已取得授權，可存取您在 Google Cloud中的資料與服務：
```
gcloud auth login
```
3. 在開啟的新瀏覽器分頁中選擇一個帳戶。
4. 將預設專案設為您的專案 ID。
```
gcloud config set project [YOUR_PROJECT_ID]
```
  將 [YOUR_PROJECT_ID] 替換為您的 Google Cloud專案 ID。如果您有其他 Google Cloud 專案，而且想要使用 gcloud 加以管理，請參閱管理 gcloud CLI 設定。
您需要一個可以將要求傳送至範例 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] 改成您的 Google Cloud專案 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：

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

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，將 Endpoints 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] 替換為您的 Google Cloud 專案 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

在大多數情況下，gcloud endpoints services deploy 指令會啟用這些必要服務。不過在以下情況中，即便您成功執行 gcloud 指令，還是無法啟用必要服務：

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

使用下列指令確認已啟用必要服務：

gcloud services list

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

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

並啟用 Endpoints 服務：

gcloud services enable ENDPOINTS_SERVICE_NAME

如要判斷 ENDPOINTS_SERVICE_NAME，您可以採取下列任一做法：

部署 Endpoints 設定後，請前往 Cloud 控制台的「Endpoints」頁面。Service name 欄下方會列出可能的 ENDPOINTS_SERVICE_NAME 清單。
針對 OpenAPI，ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 規格 host 欄位中指定的值。針對 gRPC，ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 設定的 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 主控台記錄檔所示：
```
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

Open the app.yaml file in the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.

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 替換為您的 Google Cloud 專案 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] 替換為您的Google Cloud 專案 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] 替換為您的 Google Cloud 專案 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

第三方應用程式

您可以使用諸如 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 活動

在 Google Cloud 主控台的「Endpoints」 >「Service」頁面上，查看 API 的活動圖表。

前往 Endpoints 服務頁面

要求可能需要一些時間才能反映在圖表中。
在「Logs Explorer」(記錄檔探索工具) 頁面中查看您的 API 要求記錄。

前往「Logs Explorer」頁面

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，請刪除含有該項資源的專案，或者保留專案但刪除個別資源。

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.

後續步驟

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

開始使用 Python 適用的 Cloud Endpoints Frameworks 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

安裝並設定所需的軟體

取得範例程式碼

設定 Endpoints

安裝 Endpoints Frameworks 程式庫

產生 OpenAPI 文件

部署 Endpoints 設定

檢查必要服務

在本機執行範例

Linux 或 Mac OS

PowerShell

部署 API 後端

向範例 API 發送要求

Linux 或 Mac OS

PowerShell

第三方應用程式

追蹤 API 活動

清除所用資源

後續步驟

開始使用 Python 適用的 Cloud Endpoints Frameworks