透過 ESPv2 為標準環境設定 Endpoints OpenAPI
本頁面說明如何設定 App Engine 專用的 Cloud Endpoints。Endpoints 使用可擴充服務 Proxy V2 (ESPv2) 做為 API 閘道。如要為 App Engine 提供 API 管理，您需要先在 Cloud Run 部署預先建構的 ESPv2 容器。接下來要使用 Identity-Aware Proxy (IAP) 保護應用程式的安全，確保只有 ESPv2 可以叫用。
這項設定完成後，ESPv2 會先攔截所有向您應用程式發出的要求並執行必要的檢查 (例如驗證)，然後才叫用應用程式。當應用程式回應時，ESPv2 會收集並回報遙測資料，如下圖所示。您可以在 Google Cloud 主控台的「Endpoints」 >「Services」(服務) 頁面上查看應用程式的指標。
如需 Cloud Endpoints 的總覽資訊，請參閱關於 Endpoints 和 Endpoints 架構。
遷移至 ESPv2
先前版本的 Endpoints 支援搭配 Cloud Run 使用可擴充服務 Proxy (ESP)。如果您有想遷移至 ESPv2 的現有 API，請參閱「遷移至可擴充服務 Proxy 第 2 版」一文瞭解詳情。
工作清單
在逐步進行本教學課程時，請使用以下工作清單。您必須完成所有工作，Endpoints 才能管理您的應用程式。
- 建立 Google Cloud 專案，如果尚未部署您自己的 App Engine，請部署範例後端應用程式。詳情請參閱「事前準備」一節。
- 設定 IAP 以保護應用程式。詳情請參閱設定 IAP一節。
- 為 ESPv2 服務保留 Cloud Run 主機名稱。 請參閱「保留 Cloud Run 主機名稱」。
- 建立說明 API 的 OpenAPI 文件，並設定連至 App Engine 的路徑。請參閱設定 Endpoints 一節。
- 部署 OpenAPI 文件以建立代管服務。 請參閱部署 Endpoints 設定一節。
- 使用 Endpoints 服務設定建構新的 ESPv2 Docker 映像檔。請參閱「建構新的 ESPv2 映像檔」。
- 將 ESPv2 容器部署至 Cloud Run。 並將 Identity and Access Management (IAM) 權限授予 ESPv2，以叫用您的服務。請參閱部署 ESPv2 容器。
- 叫用應用程式。詳情請參閱「傳送要求至 API」一節。
- 追蹤應用程式的活動。請參閱追蹤 API 活動一節。
- 避免系統向您的 Google Cloud 帳戶收取相關費用。 請參閱「清除所用資源」一節。
費用
在本文件中，您會使用下列 Google Cloud的計費元件：
如要根據預測用量估算費用，請使用 Pricing Calculator。
完成本文所述工作後，您可以刪除建立的資源，避免繼續計費，詳情請參閱「清除所用資源」。
事前準備
如何設定：
前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面，並建立專案。
請確認您已為專案啟用計費功能。
記下專案 ID，後續步驟將會用到。在本頁其餘部分，這個專案 ID 又稱為 ESPv2_PROJECT_ID。
記下專案編號，後續步驟將會用到。在本頁其餘部分，這個專案編號又稱為 ESPv2_PROJECT_NUMBER。
下載並安裝 Google Cloud CLI。
如果尚未部署自己的後端 App Engine，請按照 App Engine 快速入門導覽課程中的步驟操作。記下部署應用程式的地區和專案 ID。在本頁其餘部分，這個專案 ID 又稱為 APP_PROJECT_ID。
設定 IAP 以保護應用程式
您必須使用 Identity Aware Proxy (IAP) 確保已驗證要求，以保護 App Engine 應用程式的安全。
按照啟用 IAP 的步驟操作，並確認您可以登入應用程式。
此外，設定 OAuth 用戶端時，請記下本教學課程中稱為 IAP_CLIENT_ID 的 OAuth client_id。
保留 Cloud Run 主機名稱
您必須為 ESPv2 服務保留 Cloud Run 主機名稱，才能設定 OpenAPI 文件或 gRPC 服務設定。如要保留主機名稱，請將範例容器部署至 Cloud Run。稍後，您會將 ESPv2 容器部署到相同的 Cloud Run 服務。
-
確認 gcloud CLI 已取得授權，能夠存取您的資料和服務。
- 登入。
gcloud auth login
- 在開啟的新瀏覽器分頁中，選擇在用於將 ESPv2 部署至 Cloud Run 而建立的 Google Cloud 專案中，具有編輯者或擁有者角色的帳戶。
- 登入。
-
設定地區。
gcloud config set run/region us-central1
-
將範例映像檔
gcr.io/cloudrun/hello部署至 Cloud Run。將 ESPv2_CLOUD_RUN_SERVICE_NAME 替換為您想要用於該服務的名稱。gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/cloudrun/hello" \ --allow-unauthenticated \ --platform managed \ --project=ESPv2_PROJECT_ID成功完成後，這個指令會顯示類似如下的訊息：
Service [ESPv2_CLOUD_RUN_SERVICE_NAME] revision [ESPv2_CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL
舉例來說，如果將 ESPv2_CLOUD_RUN_SERVICE_NAME 設為
gateway：Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app
在本範例中，
https://gateway-12345-uc.a.run.app是 CLOUD_RUN_SERVICE_URL，而gateway-12345-uc.a.run.app是 ESPv2_CLOUD_RUN_HOSTNAME。 - 記下 ESPv2_CLOUD_RUN_SERVICE_NAME 和 ESPv2_CLOUD_RUN_HOSTNAME。您稍後會將 ESPv2 部署至 ESPv2_CLOUD_RUN_SERVICE_NAME Cloud Run 服務。您可以在 OpenAPI 文件的
host欄位中指定 ESPv2_CLOUD_RUN_HOSTNAME。
設定 Endpoints
您必須提供符合 OpenAPI 2.0 或 OpenAPI 3.x 的 OpenAPI 文件，此文件須說明您應用程式的介面以及所有驗證需求。詳情請參閱「支援的 OpenAPI 版本」。
此外，您也必須加入內含各應用程式網址的 Google 專用欄位，這樣 ESPv2 才能獲得叫用應用程式所需的資訊。如果您還不熟悉 OpenAPI，請參閱 OpenAPI 總覽瞭解詳情。
-
建立名為
openapi-appengine.yaml的文字檔案。為方便起見，本頁會以該檔案名稱來稱呼 OpenAPI 文件，但是您可以依據需求替該檔案命名。 -
您的 App Engine 後端應用程式會定義於
openapi-appengine.yaml檔案中，可以是x-google-backend定義 (適用於 OpenAPI 2.0)，也可以是x-google-api-management定義 (適用於 OpenAPI 3.x)。例如：縮排對 yaml 格式來說很重要。例如，OpenAPI 2.0
swagger: '2.0' info: title: Cloud Endpoints + App Engine description: Sample API on Cloud Endpoints with an App Engine backend version: 1.0.0 host: CLOUD_RUN_HOSTNAME schemes: - https produces: - application/json x-google-backend: address: https://APP_PROJECT_ID.REGION.r.appspot.com jwt_audience: IAP_CLIENT_ID protocol: h2 paths: /: get: summary: Greet a user operationId: hello responses: '200': description: A successful response schema: type: string
OpenAPI 3.x
openapi: 3.0.4 info: title: Cloud Endpoints + App Engine description: Sample API on Cloud Endpoints with an App Engine backend version: 1.0.0 servers: - url: https://CLOUD_RUN_HOSTNAME x-google-endpoint: {} # Define reusable components in x-google-api-management x-google-api-management: backends: appengine_backend: address: https://APP_PROJECT_ID.REGION.r.appspot.com jwtAudience: IAP_CLIENT_ID protocol: h2 # Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden. x-google-backend: appengine_backend paths: /: get: summary: Greet a user operationId: hello responses: '200': description: A successful response content: application/json: schema: type: string
host或servers欄位必須與info位於相同層級。 - 在
address欄位中，將 APP_PROJECT_ID 替換為您的Google Cloud 專案 ID，REGION 則替換為您部署 App Engine 的 Google Cloud 地區，並將 IAP_CLIENT_ID 替換為您在設定 IAP 時建立的 OAuth 用戶端 ID。 指定服務的主機名稱。視您使用的 OpenAPI 規格版本而定，所需的值也會有所不同。
OpenAPI 2.0
在
host欄位中，指定 CLOUD_RUN_HOSTNAME，也就是在「保留 Cloud Run 主機名稱」中保留的網址主機名稱部分。請勿加上通訊協定 IDhttps://，例如：swagger: '2.0' info: title: Cloud Endpoints + App Engine description: Sample API on Cloud Endpoints with an App Engine backend version: 1.0.0 host: gateway-12345-uc.a.run.app
OpenAPI 3.x
在
servers物件的url欄位中，指定完整網址，包括通訊協定 IDhttps://和 CLOUD_RUN_HOSTNAME，以及在「保留 Cloud Run 主機名稱」中保留的網址主機名稱部分。例如：openapi: 3.0.4 info: title: Cloud Endpoints + App Engine description: Sample API on Cloud Endpoints with an App Engine backend version: 1.0.0 servers: - url: https://gateway-12345-uc.a.run.app x-google-endpoint: {}
請注意
openapi-appengine.yaml檔案中title屬性的值：title: Cloud Endpoints + App Engine
部署設定後，
title屬性的值會成為 Endpoints 服務的名稱。- 儲存 OpenAPI 文件
如要瞭解 Endpoints 所需的 OpenAPI 文件欄位，請參閱設定 Endpoints 一文。
部署 Endpoints 設定
如要部署 Endpoints 設定，請使用 gcloud endpoints services deploy 指令。這個指令使用 Service Management 建立代管服務。
如何部署 Endpoints 設定：
- 確定您位於內含 OpenAPI 文件的目錄。
上傳設定並建立代管服務。
gcloud endpoints services deploy openapi-appengine.yaml \ --project ESPv2_PROJECT_ID
這會建立新的 Endpoints 服務，並以您在 OpenAPI 文件中指定的名稱做為主機名稱。另外，也會根據您的 OpenAPI 文件來設定服務。
Service Management 在建立並設定服務時，會把資訊輸出到終端機。部署完成後，您將看到類似以下的訊息：
Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]
CONFIG_ID 是部署作業建立的專屬 Endpoints 服務設定 ID。例如：
Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]
服務設定 ID 是由一個日期戳記和一個修訂版本編號所組成。如果您在同一天再次部署
openapi-appengine.yaml，服務設定 ID 中的修訂版本編號就會增加。您可以在 Google Cloud 控制台的「Endpoints > Services」(端點 > 服務) 頁面中查看服務設定和部署記錄。如果收到錯誤訊息，請參閱「排解 Endpoints 設定部署問題」。
檢查必要服務
Endpoints 和 ESP 至少需要啟用下列 Google 服務：| 名稱 | 標題 |
|---|---|
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」頁面。「服務名稱」欄下方會顯示可能的 ENDPOINTS_SERVICE_NAME 清單。
如果是 OpenAPI，ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 規格的
host欄位中指定的內容。如果是 gRPC，ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 設定的name欄位中指定的內容。
如要進一步瞭解 gcloud 指令，請參閱 gcloud 服務。
建構新的 ESPv2 映像檔
將 Endpoints 服務設定建構為新的 ESPv2 Docker 映像檔。稍後，您會將這個映像檔部署至預留的 Cloud Run 服務。
如要將服務設定建構為新的 ESPv2 Docker 映像檔，請執行下列指令：
將這份指令碼下載到已安裝 gcloud CLI 的本機電腦。
使用下列指令執行指令碼：
chmod +x gcloud_build_image./gcloud_build_image -s ESPv2_CLOUD_RUN_HOSTNAME \ -c CONFIG_ID -p ESPv2_PROJECT_ID針對 ESPv2_CLOUD_RUN_HOSTNAME，請指定您在「保留 Cloud Run 主機名稱」一節中保留的網址主機名稱。請勿加上通訊協定 ID
https://。例如：
chmod +x gcloud_build_image./gcloud_build_image -s gateway-12345-uc.a.run.app \ -c 2019-02-01r0 -p your-project-id-
這個指令碼會使用
gcloud指令下載服務設定，將服務設定建構為新的 ESPv2 映像檔，然後將新映像檔上傳至專案容器登錄檔。指令碼會自動使用最新版本的 ESPv2，輸出映像檔名稱會以 ESPv2_VERSION 表示。輸出圖片會上傳至：gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID
例如：
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
部署 ESPv2 容器
使用先前建構的新映像檔，部署 ESPv2 Cloud Run 服務。 將 CLOUD_RUN_SERVICE_NAME 替換為您在保留 Cloud Run 主機名稱中，最初保留主機名稱時使用的 Cloud Run 服務名稱：
gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --allow-unauthenticated \ --platform managed \ --project=ESPv2_PROJECT_ID
如要設定 端點 使用其他 ESPv2 啟動選項，例如啟用 CORS，可以 傳遞
ESPv2_ARGS環境變數中的 引數：gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ --allow-unauthenticated \ --platform managed \ --project ESPv2_PROJECT_ID
如要進一步瞭解如何設定
ESPv2_ARGS環境變數，包括可用選項清單和如何指定多個選項，請參閱「可擴充服務 Proxy V2 標記」。- 授予 ESPv2 權限以叫用受 IAP 保護的應用程式。請對每個服務執行下列指令。在下列指令中：
- 將 APP_PROJECT_ID 替換為 App Engine 專案 ID 的名稱。
- 將 ESPv2_PROJECT_NUMBER 替換為您為 ESPv2 建立的專案的專案「編號」。找到此編號的方法之一，就是前往 IAM 主控台並找到 Compute Engine 預設服務帳戶，即 `member` 旗標中使用的服務帳戶。
gcloud projects add-iam-policy-binding APP_PROJECT_ID \ --member "serviceAccount:ESPv2_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --role "roles/iap.httpsResourceAccessor"
詳情請參閱「使用 IAM 管理存取權」。
傳送要求至 API
本節會說明如何將要求傳送至您的 API。
建立 Endpoints 服務名稱的環境變數，這是您在 OpenAPI 文件的
host欄位中指定的名稱，例如：Linux 或 macOS：
export ENDPOINTS_HOST=gateway-12345-uc.a.run.appWindows Powershell：
$Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"
Linux 或 Mac OS
使用 curl，透過您在上一步中設定的 ENDPOINTS_HOST 環境變數傳送 HTTP 要求。
curl --request GET \
--header "content-type:application/json" \
"https://${ENDPOINTS_HOST}/"PowerShell
使用 Invoke-WebRequest，透過您在上一步中設定的 ENDPOINTS_HOST 環境變數傳送 HTTP 要求。
(Invoke-WebRequest -Method GET `
-Headers @{"content-type"="application/json"} `
-URI "https://$Env:ENDPOINTS_HOST/").Content
在上述範例中，前兩行的結尾為倒引號。當您將範例貼到 PowerShell 中時，請確保倒引號後面沒有空格。 如要瞭解範例要求中使用的選項，請參閱 Microsoft 說明文件中的 Invoke-WebRequest。
第三方應用程式
您可以使用第三方應用程式，例如 Chrome 瀏覽器擴充功能 Postman 要求。
- 選取
GET做為 HTTP 動詞。 - 選取
content-type鍵和application/json值做為標頭。 請使用實際網址，而非環境變數，例如：
https://gateway-12345-uc.a.run.app/
如果您未取得成功的回應，請參閱排解回應錯誤一文。
您已在 Endpoints 中部署並測試了 API！
追蹤 API 活動
如要查看 API 活動圖表，請前往 Google Cloud 主控台的「Endpoints」 >「Service」(服務) 頁面。
要求可能需要一些時間才能反映在圖表中。
在「Logs Explorer」頁面中查看您的 API 要求記錄。
清除所用資源
為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請按照下列步驟操作。
如要瞭解如何停用本教學課程使用的服務，請參閱刪除 API 和 API 執行個體一文。