開始使用 API Gateway 和 Cloud Run

本頁面說明如何設定 API Gateway，以便管理及保護 Cloud Run 後端服務。

工作清單

在逐步進行本教學課程時，請使用以下工作清單。您必須完成所有工作，才能為 Cloud Run 後端服務部署 API Gateway。

  1. 建立或選取 Google Cloud 專案。
  2. 如果您尚未部署自己的 Cloud Run，請部署範例服務。請參閱「事前準備」中的步驟 7。
  3. 啟用必要的 API Gateway 服務。
  4. 建立說明 API 的 OpenAPI 規格，並設定連至 Cloud Run 後端服務的路徑。請參閱「建立 API 設定」。
  5. 使用 API 設定部署 API 閘道。請參閱「部署 API 閘道」。
  6. 追蹤您服務的活動。請參閱追蹤 API 活動一節。
  7. 避免系統向您的 Google Cloud 帳戶收取費用。請參閱「清除所用資源」一節。

事前準備

  1. 在 Google Cloud 控制台中，前往「Dashboard」頁面，選取或建立 Google Cloud 專案。

    前往資訊主頁

  2. 請確認您已為專案啟用計費功能。

    啟用計費功能

  3. 請記下要用於本教學課程的專案 ID。在本頁的其餘部分，這個專案 ID 又稱為 PROJECT_ID。

  4. 下載並安裝 Google Cloud CLI。

    下載 gcloud CLI

  5. 更新 gcloud 元件：

    gcloud components update

  6. 設定預設專案。將 PROJECT_ID 替換為您的 Google Cloud 專案 ID

    gcloud config set project PROJECT_ID

  7. 如果尚未部署您自己的 Cloud Run 服務，請按照快速入門導覽課程：部署預先建立的範例容器一文中的步驟，選擇或建立 Google Cloud 專案並部署範例後端。記下應用程式網址，以及部署應用程式的地區和專案 ID。

啟用必要服務

API Gateway 要求您啟用下列 Google 服務：

名稱 標題
apigateway.googleapis.com API Gateway API
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

如要確認必要服務已啟用，請執行：

gcloud services list

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

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

如要進一步瞭解 gcloud 服務，請參閱 gcloud 服務。

建立 API 設定

您必須先設定 API，才能使用 API Gateway 管理傳送至已部署 Cloud Run 後端的流量。

您可以使用包含專屬註解的 OpenAPI 規格建立 API 設定，藉此定義所選 API Gateway 行為。您必須加入內含各 Cloud Run 應用程式網址的 Google 專用欄位，這樣 API Gateway 才能取得叫用應用程式所需的資訊。

  1. 建立名為 openapi2-run.yaml 的文字檔案。(為方便起見，本頁會以該檔案名稱來稱呼 OpenAPI 規格，但是您可以依據需求替該檔案命名)。
  2. 在 openapi2-run.yaml 檔案的 paths 區段中列出每個應用程式，如以下範例所示：
    # openapi2-run.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
schemes:
- https
produces:
- application/json
x-google-backend:
  address: APP_URL
paths:
  /assets/{asset}:
    get:
      parameters:
        - in: path
          name: asset
          type: string
          required: true
          description: Name of the asset.
      summary: Assets
      operationId: getAsset
      responses:
        '200':
          description: A successful response
          schema:
            type: string
  /hello:
    get:
      summary: Cloud Run hello world
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string
  3. 在 title 欄位中，將 API_ID 替換為 API 名稱，並將 optional-string 替換為您選擇的簡短說明。如果 API 尚未存在，建立 API 設定的指令也會建立您指定名稱的 API。當您要鑄造可授予此 API 存取權的 API 金鑰時，就會使用 title 欄位的值。如要瞭解 API 命名規則，請參閱「API ID 規定」。
  4. 在 x-google-backend 區段的 address 欄位中，將 APP_URL 替換為 Cloud Run 服務的實際網址 (呼叫 API 的完整路徑)。例如：https://hello-abc1def2gh-uc.a.run.app。
  5. 輸入下列指令，其中：
    • CONFIG_ID 會指定 API 設定的名稱。
    • API_ID 會指定 API 名稱。如果 API 尚未存在，這個指令會建立 API。
    • PROJECT_ID 會指定 Google Cloud 專案的名稱。
    • SERVICE_ACCOUNT_EMAIL 會指定用於為已設定驗證的後端簽署權杖的服務帳戶。詳情請參閱「建立服務帳戶」。 
    gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=openapi2-run.yaml \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    由於 API 設定會傳播至下游系統，因此這項作業可能需要幾分鐘才能完成。建立複雜的 API 設定最多可能需要十分鐘才能順利完成。

  6. API 設定建立完成後，執行下列指令即可查看詳細資料：
    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

部署 API 閘道

您現在可以在 API Gateway 上部署 API。在 API Gateway 上部署 API 時，也會定義 API 用戶端可用來存取 API 的外部網址。

執行下列指令，將您剛建立的 API 設定部署至 API Gateway：

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

其中：

  • GATEWAY_ID 會指定閘道的名稱。
  • API_ID 會指定與此閘道相關聯的 API Gateway API 名稱。
  • CONFIG_ID 會指定部署至閘道的 API 設定名稱。

  • GCP_REGION 是部署閘道的Google Cloud 區域。

  • PROJECT_ID 會指定 Google Cloud 專案的名稱。

成功完成後，您可以使用下列指令查看網關的詳細資料：

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

請記下這項指令輸出內容中的 defaultHostname 屬性值。這是網關網址的主機名稱部分，您會在下一個步驟中使用這個值測試部署作業。

測試 API 部署作業

現在，您可以使用部署閘道時產生的網址，傳送要求至 API。

在網路瀏覽器中輸入下列網址，其中：

  • DEFAULT_HOSTNAME 會指定已部署的閘道網址的主機名稱部分。
  • hello 是 API 設定中指定的路徑。
https://DEFAULT_HOSTNAME/hello

例如：

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

您應該會在瀏覽器中看到 Cloud Run 容器正在執行應用程式。

大功告成！你的網關會管理 Cloud Run 後端服務的存取權。

追蹤 API 活動

  1. 在Google Cloud 主控台的「API Gateway」頁面中查看 API 活動圖表。按一下 API，即可在「總覽」頁面中查看活動圖表。要求可能需要一些時間才能反映在圖表中。

  2. 在「Logs Explorer」頁面中查看您的 API 要求記錄。您可以在Google Cloud 控制台的「API Gateway」頁面中找到「Logs Explorer」頁面的連結。

    進入 API Gateway 頁面後，請按照下列步驟操作：

    1. 選取要查看的 API。
    2. 按一下 [Details] (詳細資料) 分頁標籤。
    3. 按一下「Logs」下方的連結。

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取您在本快速入門中所用資源的費用，您可以：

或者，您也可以刪除本教學課程中使用的 Google Cloud 專案。