新增 API 管理設定

Cloud Endpoints Frameworks 提供 API 管理功能,這些功能相當於可擴充服務 Proxy (ESP) 為 Cloud Endpoints 提供的功能。Endpoints Frameworks 包含內建 API 閘道,可攔截所有要求並執行所有必要的檢查 (例如驗證),然後再將要求轉送至 API 後端。當後端回應時,Endpoints Frameworks 會收集並回報遙測資料。您可以在 Google Cloud Platform 主控台中,依序前往「Endpoints」>「Services」(服務) 頁面查看 API 的指標

Endpoints Frameworks 提供的 API 管理功能包含:

如要讓 Endpoints 管理您的 API,您必須部署 OpenAPI 文件,且此文件應使用 OpenAPI 規範 2.0 版說明 API。本頁說明如何產生及部署可讓 Endpoints 管理您 API 的 OpenAPI 文件。

如果您不新增 API 管理設定,API 仍然會處理要求,但不會出現在 GCP 主控台的「Endpoints」>「Services」(服務) 頁面上,且您無法使用 Endpoints 提供的功能,例如記錄、監控和設定配額。

安裝並設定所需的軟體

若您尚未安裝 Python 專用的 Cloud SDK,請先安裝並設定這個軟體,並新增 Endpoints Frameworks Python 程式庫至您的 API 專案目錄中,以便在部署時與 API 程式碼一起上傳。

安裝並設定 Python 專用的 Cloud SDK

  1. 安裝並初始化 Cloud SDK:

    下載並安裝 Cloud SDK

  2. 安裝 gcloud 元件,其中包含 Python 專用的 App Engine 擴充功能:

    gcloud components install app-engine-python
    
  3. 更新 Cloud SDK:

    gcloud components update
    
  4. 確認 Cloud SDK 已獲授權,可存取您在 GCP 上的資料與服務:

    gcloud auth login
    

    系統將開啟新的瀏覽器分頁,並提示您選擇一個帳戶。

  5. 將預設專案設定為您的專案 ID,並將 YOUR_PROJECT_ID 替換為您的 GCP 專案 ID。

    gcloud config set project YOUR_PROJECT_ID
    
  6. 如果您使用 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 程式庫

  1. 確認您可以編譯 Python 的 C 擴充功能。

    • Windows:需要 Microsoft Visual C++ 9.0 以上版本。您可以從 Microsoft 下載中心下載 Python 2.7 版本適用的 Microsoft Visual C++ 編譯器。

    • 其他作業系統:視您的作業系統而定,您可能需要安裝編譯器工具 (有時在套件中稱為 build-essential),以及/或是 Python 開發標頭 (有時在套件中稱為 python-dev)。

  2. 將目錄更改為 API 的主目錄。

  3. 在 API 的主目錄中建立一個 /lib 子目錄。

    mkdir lib
    
  4. 安裝程式庫:

    pip install -t lib google-endpoints --ignore-installed
    

產生 OpenAPI 文件

使用架構工具,從 API 的主目錄產生 OpenAPI 文件。例如:

單一類別

請將以下指令中的 YOUR_PROJECT_ID 替換為您的 GCP 專案 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 替換為您的 GCP 專案 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 要替換成您的 GCP 專案 ID:

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

您可以建立及部署自己的 OpenAPI 文件,而不使用系統產生的文件,只需將上面的 echov1openapi.json 替換為 OpenAPI 文件的路徑即可。如要進一步瞭解如何編寫 OpenAPI 文件,請參閱 OpenAPI 總覽

重新部署 API 並進行測試

  1. 編輯專案的 app.yaml 檔案並新增 env_variables 部分,如下所示:

    env_variables:
      ENDPOINTS_SERVICE_NAME: YOUR_PROJECT_ID.appspot.com
      ENDPOINTS_SERVICE_VERSION: YOUR_SERVICE_VERSION
    

    YOUR_PROJECT_ID 替換為您的 GCP 專案 ID,並將 YOUR_SERVICE_VERSION 替換為您在前述部分使用的服務設定 ID。將這個部分新增至 app.yaml 檔案並重新部署應用程式後,Endpoints 就會管理您的 API。

  2. 重新部署應用程式:

    gcloud app deploy
    
  3. 稍等片刻,等待部署成功,並請忽略警告訊息。部署完成後,您將看到如下的訊息:

    File upload done.
    Updating service [default]...done.
    
  4. 測試重新部署作業是否成功,例如使用 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"
    }
    
  5. 向您的 API 發出一些其他要求。

  6. 如要查看 API 指標,請在 GCP 主控台中依序前往您專案的「Endpoints」>「Services」(服務) 頁面:

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

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

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

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁