開始使用 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 Gateway」。
  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 Cloud 服務:

名稱 服務名稱
API Gateway API apigateway.googleapis.com
Service Management API servicemanagement.googleapis.com
Service Control API servicecontrol.googleapis.com

如要啟用必要服務,請按照下列步驟操作:

Google Cloud 控制台

  1. 在 Google Cloud 控制台中,依序前往「APIs & Services」(API 與服務) >「API Library」(API 程式庫) 頁面。

    前往 API 程式庫

  2. 在「API Library」(API 程式庫) 頁面的搜尋列中,輸入所需 API 名稱。
  3. 在搜尋結果中選取 API 頁面。
  4. 在 API 頁面中,按一下「啟用」。
  5. 針對上表列出的每項服務,重複執行這些步驟。

Google Cloud CLI

請使用下列指令啟用服務:

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 行為。您需要新增 Google 專用欄位,其中包含每個 Cloud Run 應用程式的網址,這樣 API Gateway 才能取得叫用應用程式所需的資訊。

如要進一步瞭解支援的 OpenAPI 擴充功能,請參閱下列內容:

如要建立 API 設定,請按照下列步驟操作:

  1. 建立名為 openapi-run.yaml 的文字檔案。為方便起見,本頁面會以該檔案名稱來指稱 OpenAPI 說明,但您也可以視需要使用其他名稱。
  2. 將下列檔案的內容複製到 openapi-run.yaml 檔案中:

    OpenAPI 2.0

    # openapi-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
    • 在 title 欄位中,將 API_ID 替換為 API 名稱,並將 optional-string 替換為您選擇的簡短說明。如果 API 尚未存在,建立 API 設定的指令也會建立 API,並使用您指定的名稱。建立 API 金鑰時,系統會使用 title 欄位的值,授予該 API 的存取權。如需 API 命名規範,請參閱「API ID 規定」。
    • 在「x-google-backend」部分的「address」欄位中,將 APP_URL 替換為 Cloud Run 服務的實際網址 (所呼叫 API 的完整路徑)。例如:https://hello-abc1def2gh-uc.a.run.app。

    OpenAPI 3.x

    # openapi-run.yaml
    openapi: 3.0.4
    info:
      title: API_ID optional-string
      description: Sample API on API Gateway with a Cloud Run backend
      version: 1.0.0
    # Define reusable components in x-google-api-management
    x-google-api-management:
      backends:
        cloudrun_backend:
          address: APP_URL
          deadline: 30.0
          pathTranslation: APPEND_PATH_TO_ADDRESS
          protocol: "http/1.1"
    # Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
    x-google-backend: cloudrun_backend
    paths:
      /hello:
        get:
          summary: Greet a user
          operationId: hello
          responses:
            "200":
              description: A successful response
              content:
                application/json:
                  schema:
                    type: string
    • 在 title 欄位中,將 API_ID 替換為 API 名稱,並將 optional-string 替換為您選擇的簡短說明。如果 API 尚未存在,建立 API 設定的指令也會建立 API,並使用您指定的名稱。建立 API 金鑰時,系統會使用 title 欄位的值,授予該 API 的存取權。如需 API 命名規範,請參閱「API ID 規定」。
    • 在 address 欄位中,將 APP_URL 替換為 Cloud Run 服務的實際網址 (所呼叫 API 的完整路徑)。例如:https://hello-687541448612.us-central1.run.app。
  3. 輸入下列指令,其中:
    • 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 設定可能需要十分鐘才能順利完成。

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

部署 API Gateway

現在您可以在 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-687541448612.us-central1.run.app/hello

瀏覽器中應會顯示 Cloud Run 容器正在執行應用程式。

大功告成!閘道會管理 Cloud Run 後端服務的存取權。

追蹤 API 活動

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

  2. 在「Logs Explorer」頁面查看 API 的要求記錄。Google Cloud 控制台的「API Gateway」頁面中,有「Logs Explorer」頁面的連結。

    進入 API Gateway 頁面後:

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

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取這個快速入門導覽課程所用資源的費用,您可以執行以下操作:

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