將 API 部署至閘道

事前準備

在 API Gateway 上部署 API 設定前，請確認您具備下列條件：

閘道 ID 相關規定

下方顯示的許多 gcloud 指令都需要您指定網關的 ID，格式如下：GATEWAY_ID。API Gateway 會強制實施下列閘道 ID 相關規定：

  • 長度上限為 49 個半形字元。
  • 只能使用小寫英文字母、數字或破折號。
  • 開頭不得為破折號。
  • 不得包含底線。

定義已部署 API 設定的端點

將 API 設定部署至閘道時，API Gateway 會在 gateway.dev 網域中為閘道建立專屬網址。接著，API 用戶端會使用下列表單中的網址存取已部署的 API 設定：

https://GATEWAY_ID-HASH.REGION_CODE.gateway.dev

其中 GATEWAY_ID 是閘道名稱、HASH 是部署 API 時產生的專屬雜湊碼，而 REGION_CODE 則是部署閘道時的 Cloud 位置代碼。

例如：

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

將 API 設定部署至閘道

使用 Google Cloud CLI 將 API 設定部署至閘道。部署 API 設定時，您必須指定 API 名稱。如果 API 的閘道尚未存在，這個指令也會建立該閘道。

如要將 API 設定部署至閘道，請按照下列步驟操作：

  1. 請利用下列指令傳回的專案 ID 進行驗證，以確保系統沒有在錯誤的專案中建立閘道。

    gcloud config list project

    如要變更預設的專案，請執行下列指令，並將 PROJECT_ID 改成要建立服務的 Google Cloud 專案 ID：

    gcloud config set project PROJECT_ID

  2. 查看 gateway create 指令的說明：

    gcloud api-gateway gateways create --help

  3. 執行下列指令，將 API 設定部署至閘道：

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

    其中：

    • GATEWAY_ID 會指定新閘道的 ID。如果閘道不存在，這個指令會建立閘道。
    • API_ID 會指定與此閘道相關聯的 API Gateway API ID。
    • CONFIG_ID 會指定部署至閘道的 API 設定 ID。建立閘道時，您必須指定 API 設定。

    • GCP_REGION 會指定部署閘道的 Cloud 位置。

    • PROJECT_ID 會指定 Google Cloud 專案 ID。

    gcloud 在建立閘道時，會將資訊輸出至終端機。

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

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

    這項指令會傳回以下內容：

    apiConfig: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: GATEWAY_ID
name: projects/PROJECT_ID/locations/GCP_REGION/gateways/GATEWAY_ID
serviceAccount:
  email: gateway-111111@222222-tp.iam.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

    請注意 defaultHostname 屬性的值。這是閘道網址的主機名稱部分。如要存取部署至此閘道的 API 設定，請使用以下格式的網址：

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

Google Cloud CLI 提供多種選項，包括 gcloud 參考資料中所述的選項。此外，您可以在建立 API Gateway 時設定下列選項：

  • --async：立即將控制權交還至終端機，不必等待作業完成。
  • --display-name=NAME：指定閘道顯示名稱，也就是在 UI 中顯示的名稱。名稱中不可使用空格。請改用連字號和底線。預設值為 GATEWAY_ID。
  • --labels=KEY1=VALUE1,KEY2=VALUE2,...：指定與閘道相關聯的標籤。

列出閘道

如要列出特定專案的閘道，請按照下列步驟操作：

gcloud api-gateway gateways list --project=PROJECT_ID

這個指令會傳回以下格式的輸出內容：

GATEWAY_ID        LOCATION       DISPLAY_NAME     STATE     CREATE_TIME          UPDATE_TIME
my-gateway        us-central1    my-gateway       ACTIVE    2021-01-07T00:04:19  2022-05-21T00:33:46

如要列出特定專案和區域的閘道，請按照下列步驟操作：

gcloud api-gateway gateways list --location=GCP_REGION --project=PROJECT_ID

使用 filter 運算式列出與特定 API 相關聯的閘道：

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/*" \
  --project=PROJECT_ID

或者，您也可以使用這個 filter 來列出特定 API 設定的閘道：

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID" \
  --project=PROJECT_ID

使用專案、區域和閘道 ID 取得閘道的詳細資訊，包括部署至閘道的 API 設定的 ID：

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

更新閘道

更新閘道以便：

  • 將不同的 API 設定部署至閘道
  • 更新顯示名稱
  • 更新標籤

使用以下 gcloud 指令更新現有的閘道，其中 UPDATE_OPTIONS 會替換為您要更新的閘道選項標記和值：

gcloud api-gateway gateways update GATEWAY_ID \
  UPDATE_OPTIONS --api=API_ID --location=GCP_REGION --project=PROJECT_ID

舉例來說，如要更新部署至閘道的 API 設定，請按照下列步驟操作：

gcloud api-gateway gateways update GATEWAY_ID \
  --api-config=NEW_CONFIG_ID --api=API_ID --location=GCP_REGION --project=PROJECT_ID

其中 NEW_CONFIG_ID 會指定要部署至閘道的全新 API 設定。

如需可用更新標記和引數的完整清單，請參閱 gcloud api-gateway gateways update 參考資料，或使用下列指令查看所有更新選項：

gcloud api-gateway gateways update --help

刪除閘道

使用下列 gcloud 指令刪除現有的閘道：

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

後續步驟