Cloud Endpoints Frameworks 提供 API 管理功能,這些功能相當於可擴充服務 Proxy (ESP) 為 Cloud Endpoints 提供的功能。Endpoints Frameworks 包含內建 API 閘道,可攔截所有要求並執行所有必要的檢查 (例如驗證),然後再將要求轉送至 API 後端。當後端回應時,Endpoints Frameworks 會收集並回報遙測資料。您可以在Google Cloud 主控台的「Endpoints」 >「Services」頁面查看 API 指標。
Endpoints Frameworks 提供的 API 管理功能包含:
如要讓 Endpoints 管理您的 API,您必須部署 OpenAPI 文件,且此文件應使用 OpenAPI 規範 2.0 版說明 API。本頁說明如何產生及部署可讓 Endpoints 管理您 API 的 OpenAPI 文件。
如果您不新增 API 管理設定,API 仍然會處理要求,但不會出現在Google Cloud 主控台的「Endpoints」>「Services」(服務) 頁面上,且您無法使用 Endpoints 提供的功能,例如記錄、監控和設定配額。
安裝並設定所需的軟體
如果您尚未安裝 Python 專用的 Google Cloud CLI,請先安裝並設定這個軟體,並新增 Endpoints Frameworks Python 程式庫至您的 API 專案目錄中,以便在部署時與 API 程式碼一起上傳
安裝並設定 Python 專用的 gcloud CLI
安裝並初始化 gcloud CLI:
安裝包含 Python 專用 App Engine 擴充功能的
gcloud
元件:gcloud components install app-engine-python
更新 gcloud CLI:
gcloud components update
確認 gcloud CLI 已獲授權,可存取您在 Google Cloud上的資料和服務:
gcloud auth login
系統將開啟新的瀏覽器分頁,並提示您選擇一個帳戶。
將預設專案設為您的專案 ID。將
YOUR_PROJECT_ID
替換為您的 Google Cloud 專案 ID。gcloud config set project YOUR_PROJECT_ID
如果您使用 Linux,請將
ENDPOINTS_GAE_SDK
環境變數設定為 App Engine SDK 資料夾的路徑:PATH_TO_CLOUD_SDK/platform/google_appengine
將
PATH_TO_CLOUD_SDK
替換為以下指令的輸出內容:gcloud info --format="value(installation.sdk_root)"
新增 Endpoints Frameworks Python 程式庫
確認您可以編譯 Python 的 C 擴充功能。
Windows系統:需要 Microsoft Visual C++ 9.0 以上版本。您可以從 Microsoft 下載中心下載 Python 2.7 版本適用的 Microsoft Visual C++ 編譯器。
其他作業系統:視您的作業系統而定,您可能需要安裝編譯器工具 (有時在套件中稱為
build-essential
),以及/或是 Python 開發標頭 (有時在套件中稱為python-dev
)。
將目錄更改為 API 的主目錄。
在 API 主目錄中建立
/lib
子目錄:mkdir lib
安裝程式庫:
pip install -t lib google-endpoints --ignore-installed
產生 OpenAPI 文件
使用架構工具,從 API 的主目錄產生 OpenAPI 文件。例如:
單一類別
請將以下指令中的 YOUR_PROJECT_ID
替換為您的 Google Cloud 專案 ID。
python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi \ --hostname YOUR_PROJECT_ID.appspot.com
請忽略顯示的警告。
多個類別
您可以在指令列上列出多個類別。Endpoints 會為每個 API 名稱/版本組合產生 OpenAPI 文件。
如果您想要將多個 API 名稱不同的 API 類別部署為單一服務的一部分,您必須新增 --x-google-api-name
標記。啟用此標記會使您的 API 名稱受到其他限制。具體而言,名稱必須與規則運算式 [a-z][a-z0-9]{0,39}
相符,也就是說,名稱必須包含 1 到 40 個字元,除了第一個字元不得為數字之外,所有其他字元都可為小寫字母或數字。例如:
請將以下指令中的 YOUR_PROJECT_ID
替換為您的 Google Cloud 專案 ID。
python lib/endpoints/endpointscfg.py get_openapi_spec main.FooApi main.BarApi \ --hostname YOUR_PROJECT_ID.appspot.com \ --x-google-api-name
請忽略顯示的警告。
Endpoints 會使用您在 hostname
引數中指定的文字做為服務名稱。在您將 API 部署至 App Engine 時,系統會自動建立名稱格式為 YOUR_PROJECT_ID.appspot.com
的 DNS 項目。
部署 OpenAPI 文件
單一類別
gcloud endpoints services deploy echov1openapi.json
多個類別
如果您有多個 OpenAPI 文件,請在指令列上列出所有文件。例如:
gcloud endpoints services deploy foov1openapi.json barv1openapi.json
初次部署一或多份 OpenAPI 文件時,系統會建立名稱為 YOUR_PROJECT_ID.appspot.com
的新 Endpoints 服務。
成功部署之後,您會看到一行如下的訊息,當中顯示服務設定 ID 和服務名稱:
Service Configuration 2017-02-13r0 uploaded for service example-project-12345.appspot.com
在上方範例中,2017-02-13r0
是服務設定 ID。服務設定 ID 是由一個日期戳記和一個修訂版本編號所組成。若您再次部署 OpenAPI 文件,服務設定 ID 中的修訂版本編號將會增加。
如果您需要再次顯示服務設定 ID,請執行下列指令,但將 YOUR_PROJECT_ID
替換成您的 Google Cloud 專案 ID:
gcloud endpoints configs list --service=YOUR_PROJECT_ID.appspot.com
您可以建立及部署自己的 OpenAPI 文件,而不使用系統產生的文件,只需將上面的 echov1openapi.json
替換為 OpenAPI 文件的路徑即可。如要進一步瞭解如何編寫 OpenAPI 文件,請參閱 OpenAPI 總覽。
重新部署 API 並進行測試
編輯專案的
app.yaml
檔案,並新增env_variables
部分,如下所示:env_variables: ENDPOINTS_SERVICE_NAME: YOUR_PROJECT_ID.appspot.com ENDPOINTS_SERVICE_VERSION: YOUR_SERVICE_VERSION
將
YOUR_PROJECT_ID
替換為您的Google Cloud 專案 ID,並將YOUR_SERVICE_VERSION
替換為您在前述部分使用的服務設定 ID。將這個部分新增至app.yaml
檔案並重新部署應用程式後,Endpoints 就會管理您的 API。重新部署應用程式:
gcloud app deploy
稍等片刻,等待部署成功,並請忽略警告訊息。部署完成後,您將看到如下的訊息:
File upload done. Updating service [default]...done.
測試重新部署作業是否成功,例如使用 curl:
curl --request POST \ --header "Content-Type: application/json" \ --data '{"content":"echo"}' \ https://YOUR_PROJECT_ID.appspot.com/_ah/api/echo/v1/echo?n=2
將
echo
替換為您的 API 名稱。結果應如下所示:
{ "content": "echo echo" }
向您的 API 發出一些其他要求。
如要查看 API 指標,請在 Google Cloud 專案主控台中依序前往「Endpoints」 >「Services」 頁面: