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

透過 ESPv2 為 Cloud Run 函式設定 Cloud Endpoints OpenAPI

本頁說明如何在 Cloud Run 函式上設定 Cloud Endpoints。Endpoints 使用可擴充服務 Proxy V2 (ESPv2) 做為 API 閘道。如要為 Cloud Run functions 提供 API 管理，您需要先在 Cloud Run 部署預先建構的 ESPv2 容器。接下來使用 Cloud Run 函式 IAM 保護函式的安全，以便 ESPv2 叫用。

此設定完成後，ESPv2 會先攔截所有向函式發出的要求並執行必要的檢查 (例如驗證)，然後才叫用函式。當函式回應時，ESPv2 會收集並回報遙測資料，如下圖所示。您可以在 Google Cloud 控制台的「Endpoints」 >「Services」(服務) 頁面查看函式指標。

Endpoints 架構

如需 Cloud Endpoints 的總覽資訊，請參閱關於 Endpoints 和 Endpoints 架構。

遷移至 ESPv2

先前版本的 Cloud Endpoints 支援搭配 Cloud Functions 使用可擴充服務 Proxy (ESP)。如要將現有 API 遷移至 ESPv2，請參閱「遷移至可擴充服務 Proxy 第 2 版」一文。

工作清單

在逐步進行本教學課程時，請使用以下工作清單。您必須完成所有工作，才能完成本教學課程。

建立 Google Cloud 專案，如果尚未部署自己的 Cloud Run 函式，請部署範例後端函式。請參閱「事前準備」。
為 ESPv2 服務保留 Cloud Run 主機名稱。請參閱「保留 Cloud Run 主機名稱」。
建立說明 API 的 OpenAPI 文件，並設定連至 Cloud Run 函式的路徑。請參閱設定 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 的使用者可能符合免費試用資格。

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

事前準備

使用 Cloud Run functions 專用的 Endpoints 前，建議您採取下列做法：

當您將 ESPv2 容器部署至 Cloud Run 時，請建立要使用的新 Google Cloud 專案。
針對 Cloud Run 函式建立新專案或選擇現有專案。

如何設定：

前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面，並建立專案。
前往「Manage resources」(管理資源) 頁面
請確認您已為專案啟用計費功能。
瞭解如何啟用計費功能
記下專案 ID，後續步驟將會用到。在本頁其餘部分，這個專案 ID 又稱為 ESP_PROJECT_ID。
記下專案編號，後續步驟將會用到。在本頁的其餘部分，這個專案編號又稱為 ESP_PROJECT_NUMBER。
下載並安裝 Google Cloud CLI。
下載 gcloud CLI
如果尚未部署自己的後端 Cloud Run 函式，請按照快速入門導覽課程：使用 Google Cloud CLI一文中的步驟，選擇或建立 Google Cloud 專案並部署範例函式。記下部署函式的地區和專案 ID。在本頁其餘部分，這個專案 ID 又稱為 FUNCTIONS_PROJECT_ID。

保留 Cloud Run 主機名稱

您必須為 ESPv2 服務保留 Cloud Run 主機名稱，才能設定 OpenAPI 文件或 gRPC 服務設定。如要保留主機名稱，請將範例容器部署至 Cloud Run。稍後，您會將 ESPv2 容器部署到同一個 Cloud Run 服務上。

確認 gcloud CLI 已取得授權，能夠存取您的資料和服務。
1. 登入。
```
gcloud auth login
```
2. 在開啟的新瀏覽器分頁中，選擇在用於將 ESPv2 部署至 Cloud Run 而建立的 Google Cloud 專案中，具有編輯者或擁有者角色的帳戶。

設定地區。

gcloud config set run/region us-central1

將範例映像檔 gcr.io/cloudrun/hello 部署至 Cloud Run。將 CLOUD_RUN_SERVICE_NAME 替換為您想要用於該服務的名稱。

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESP_PROJECT_ID

成功完成後，這個指令會顯示類似如下的訊息：

Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

舉例來說，如果將 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 是 CLOUD_RUN_HOSTNAME。

請記下 CLOUD_RUN_SERVICE_NAME 和 CLOUD_RUN_HOSTNAME。稍後，您會將 ESPv2 部署至 CLOUD_RUN_SERVICE_NAME Cloud Run 服務。您可以在 OpenAPI 文件的 host 欄位中指定 CLOUD_RUN_HOSTNAME。

設定 Endpoints

您必須具有以 OpenAPI 規範 v2.0 為基礎的 OpenAPI 文件，該文件會說明函式的介面以及任何的驗證需求。此外，你也必須加入內含各函式網址的 Google 專用欄位，這樣 ESPv2 才能獲得叫用函式所需的資訊。如果您還不熟悉 OpenAPI，請參閱 OpenAPI 總覽瞭解詳情。

建立名為 openapi-functions.yaml 的文字檔案。(為方便起見，本頁會以該檔案名稱來稱呼 OpenAPI 文件，但是您可以依據需求替該檔案命名)。

每個函式都必須列於 openapi-functions.yaml 檔案的 paths 區段中。例如：

swagger: '2.0'
info:
  title: Cloud Endpoints + GCF
  description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
  version: 1.0.0
host: HOST
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
        protocol: h2
      responses:
        '200':
          description: A successful response
          schema:
            type: string

縮排對 yaml 格式來說很重要。例如，host 欄位必須與 info 位於相同層級。

在 x-google-backend 區段的 address 欄位中，將 REGION 替換為函式所在的 Google Cloud 地區，FUNCTIONS_PROJECT_ID 替換為您的 Google Cloud 專案 ID，並將 FUNCTIONS_NAME 替換為函式名稱。例如：
```
x-google-backend:
  address: https://us-central1-myproject.cloudfunctions.net/helloGET
```
如要保護 Cloud Run 函式，只允許 ESPv2 叫用，請確認 address 欄位包含函式名稱 (如果未指定 jwt_audience)。例如：
```
x-google-backend:
  address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
  path_translation: CONSTANT_ADDRESS
```
如果指定 jwt_audience，其值也應包含函式名稱。例如：
```
x-google-backend:
  address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net
  jwt_audience: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
  path_translation: APPEND_PATH_TO_ADDRESS
```
ESPv2 會在呼叫 Cloud Run 函式進行驗證時產生 ID 權杖。ID 權杖應具有適當的 audience，可指定函式主機和函式名稱。如果指定了 jwt_audience 欄位中的值，ESPv2 會使用該值設定 ID 權杖的 audience；否則，會使用 address 欄位。

在 host 欄位中，指定 CLOUD_RUN_HOSTNAME，也就是您在「保留 Cloud Run 主機名稱」一節中保留的網址主機名稱部分。請勿加上通訊協定 ID https://，例如：

swagger: '2.0'
  info:
    title: Cloud Endpoints + GCF
    description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
    version: 1.0.0
  host: gateway-12345-uc.a.run.app

請注意 openapi-functions.yaml 檔案中 title 屬性的值：
```
title: Cloud Endpoints + GCF
```
部署設定後，title 屬性的值會成為 Endpoints 服務的名稱。
儲存 OpenAPI 文件。

如要瞭解 Endpoints 所需的 OpenAPI 文件欄位，請參閱設定 Endpoints 一文。

部署 Endpoints 設定

如要部署 Endpoints 設定，請使用 gcloud endpoints services deploy 指令。這個指令使用 Service Management 建立代管服務。

如何部署 Endpoints 設定：

確定您位於內含 OpenAPI 文件的目錄。
上傳設定並建立代管服務。
```
gcloud endpoints services deploy openapi-functions.yaml \
    --project ESP_PROJECT_ID
```
完成後，系統會建立新的 Endpoints 服務，並命名為您在 openapi-functions.yaml 檔案的 host 欄位中指定的名稱。另外，也會根據您的 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-functions.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 服務。

注意：

這是必填步驟。

服務設定必須建構至新的 Docker 映像檔，因為 Cloud Run 是縮減至零的服務。也就是說，如果沒有流量，系統就會刪除所有執行個體。流量增加時，系統會視需要建立新的執行個體。這類服務執行個體建立作業也稱為「冷啟動」。詳情請參閱 Cloud Run 並行說明文件。

如果 Docker 映像檔未內建服務設定，Cloud Run 就必須在冷啟動時對 Google ServiceManagement 進行兩次 API 呼叫。這些呼叫會計入 Google Service Management API 配額。

將服務設定建構至 ESPv2 Docker 映像檔後，您就能移除這兩項 API 呼叫，避免影響 Google Service Management 服務的配額計數。這個步驟也能加快建立新服務執行個體的速度，並縮短等待新執行個體的要求延遲時間。

您必須重新執行整個步驟，並重新部署新容器：

每次修改並重新部署 Endpoints 服務設定時。否則，服務設定的變更不會傳播至 ESPv2。
發布新版 ESPv2 時。否則，系統會繼續部署舊版 ESPv2。

如要將服務設定建構至新的 ESPv2 Docker 映像檔，請執行下列指令：

將這段指令碼下載到已安裝 gcloud CLI 的本機。

注意：
這個指令碼需要 bash。如果不是使用 macOS/Linux，可以在 Cloud Shell、Compute Engine 或 Windows Subsystem for Linux 上執行。
使用下列指令執行指令碼：
```
chmod +x gcloud_build_image

./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESP_PROJECT_ID
```
注意：
這個指令碼的用途是在 /tmp 目錄中建立資料夾。執行這項指令碼時，請確認您擁有 /tmp 目錄的寫入權。

如果 /tmp 目錄沒有寫入權限，您必須修改指令碼，指定其他有權建立資料夾的目錄。

針對 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，輸出映像檔名稱中的 ESP_VERSION 即為標記。輸出圖片會上傳至：
```
gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-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"
```
注意：
將 -z 旗標傳遞至指令碼，即可在其他登錄檔位置產生映像檔。

舉例來說，如要將產生的 ESPv2 映像檔推送至歐盟資料中心，請將 -z eu 傳遞至指令碼。

部署 ESPv2 容器

使用您在上方建構的新映像檔，部署 ESPv2 Cloud Run 服務。將 CLOUD_RUN_SERVICE_NAME 替換為您在保留 Cloud Run 主機名稱時使用的 Cloud Run 服務名稱：
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESP_PROJECT_ID
```
注意：
如要讓 ESPv2 管理存取權，請使用 --allow-unauthenticated 標記，確保 ESPv2 會驗證 JWT 權杖。如果未使用這個旗標，Cloud Run <a=" docs="" managing-access"="" run="" securing="">存取控制 IAM 伺服器</a>會攔截並驗證 JWT 權杖。由於 IAM 和 ESPv2 使用相同的授權標頭，因此無法同時運作，請務必只使用其中一個。建議使用 IAM 管理存取權，而非 ESPv2。</a=">
如要設定 Endpoints 使用其他 ESPv2 啟動選項，例如啟用 CORS，可以傳送 ESPv2_ARGS 環境變數中的引數：
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESP_PROJECT_ID
```
如要進一步瞭解如何設定 ESPv2_ARGS 環境變數，包括可用選項清單和如何指定多個選項，請參閱「Extensible Service Proxy V2 Beta 標記」。
授予 ESPv2 權限，以呼叫 Service Management 和 Service Control。

前往 Google Cloud 控制台的 Cloud Run 頁面。

前往 Cloud Run 頁面

您會看到已部署的 Cloud Run 執行個體，以及與其相關聯的服務帳戶。
將必要權限授予服務帳戶：

gcloud projects add-iam-policy-binding PROJECT_NAME \
   --member "serviceAccount:SERVICE_ACCOUNT" \
   --role roles/servicemanagement.serviceController

角色和權限是什麼？

授予 ESPv2 權限以叫用您的函式。針對每個函式執行下列指令。在下列指令中：

注意：
如果部署 ESPv2 Cloud Run 服務時未使用 --service-account 標記，且後端服務 BACKEND_SERVICE_NAME 部署在 ESP_PROJECT_NUMBER 專案中，則不需要執行這個步驟。
- 將 FUNCTION_NAME 替換為函式名稱，並將 FUNCTION_REGION 替換為函式部署的區域。如果您使用的是「快速入門導覽課程：使用 Google Cloud CLI」中建立的函式，請使用 helloGET 做為名稱。
- 將 ESP_PROJECT_NUMBER 替換為您為 ESPv2 建立的專案的專案「編號」。找到此編號的方法之一，就是前往 Google Cloud 控制台的 IAM 頁面，並找到預設運算服務帳戶，即 member 旗標中使用的服務帳戶。
```
gcloud functions add-iam-policy-binding FUNCTION_NAME \
   --region FUNCTION_REGION \
   --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
   --role "roles/cloudfunctions.invoker" \
   --project FUNCTIONS_PROJECT_ID
```

詳情請參閱「透過 IAM 管理存取權」一文。

傳送要求至 API

本節會說明如何將要求傳送至您的 API。

建立 Endpoints 服務名稱的環境變數，這是您在 OpenAPI 文件的 host 欄位中指定的名稱，例如：
- Linux 或 macOS：
  
  export ENDPOINTS_HOST=gateway-12345-uc.a.run.app
- Windows 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}/hello"

PowerShell

使用 Invoke-WebRequest，透過您在上一步中設定的 ENDPOINTS_HOST 環境變數傳送 HTTP 要求。

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/hello").Content

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

第三方應用程式

您可以使用第三方應用程式，例如 Chrome 瀏覽器擴充功能 Postman 要求。

選取 GET 做為 HTTP 動詞。
選取 content-type 鍵和 application/json 值做為標頭。
請使用實際網址，而非環境變數，例如：
```
https://gateway-12345-uc.a.run.app/hello
```

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

您已在 Endpoints 中部署並測試了 API！

追蹤 API 活動

如要查看 API 活動圖表，請前往 Google Cloud 主控台的「Endpoints」 >「Service」(服務) 頁面。

查看 Endpoints 活動圖表

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

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本頁所用資源的費用，請按照下列步驟操作。

如要瞭解如何停用本教學課程使用的服務，請參閱刪除 API 和 API 執行個體一文。