開始使用 API Gateway 和 Cloud Run

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

工作清單

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

  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 控制台中，前往「資訊主頁」頁面，然後選取或建立 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 enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

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

建立 API 設定

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

您可以使用包含特殊註解的 OpenAPI 說明建立 API 設定，定義所選的 API Gateway 行為。您需要加入含有各個 Cloud Run 應用程式網址的 Google 專用欄位，這樣 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 的 API 金鑰時，會使用 title 欄位的值。如需 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 名稱。系統會使用 title 欄位的值，鑄造可授予此 API 存取權的 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 閘道

現在您可以在 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. 如要查看 API 活動圖表，請前往Google Cloud 控制台的「API Gateway」頁面。按一下 API，即可在「Overview」(總覽) 頁面中查看活動圖表。要求可能需要一些時間才能反映在圖表中。

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

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

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

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取這個快速入門導覽課程所用資源的費用，您可以：

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