建立 API 設定

本頁說明如何建立 API 設定，以便部署至 API Gateway。

事前準備

建立 API 設定前，請確認您具備：

  • 按照「設定開發環境」一文所述，準備開發環境。

  • 已建立 API 定義做為 OpenAPI 規格。

  • (選用) 按照「建立 API」一文的說明建立 API。如果 API 不存在，建立 API 設定時就會一併建立。

API 設定 ID 規定

本教學課程中顯示的許多 gcloud 指令，都需要您指定 API 設定的 ID，格式為：CONFIG_ID。 API Gateway 會強制實行下列 API 設定 ID 規定：

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

建立 API 設定

使用 Google Cloud CLI 上傳 API 定義，建立 API 設定。 上傳 API 定義時，您必須指定 API 名稱。如果 API Gateway 中還沒有這個 API，這項指令也會建立 API。

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

  1. 將目錄變更為包含 API 定義的目錄。

    如要進一步瞭解如何為 API 定義建立 OpenAPI 規格，請參閱「OpenAPI 總覽」和「快速入門：在 API Gateway 上部署 API」。

    如要進一步瞭解如何為 API 定義建立 gRPC 服務定義和設定，請參閱「設定 gRPC 服務」和「開始使用 API 閘道搭配 Cloud Run 和 gRPC」。

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

    gcloud config list project

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

    gcloud config set project PROJECT_ID

  3. 查看 api-configs create 指令的說明：

    gcloud api-gateway api-configs create --help

  4. 執行下列指令來建立 API 設定：

    gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    其中：

    • CONFIG_ID 會指定新 API 設定的 ID。
    • API_ID 會指定與這個 API 設定相關聯的 API Gateway API ID。如果 API 尚不存在，這個指令會建立 API。
    • API_DEFINITION：指定包含 API 定義的 OpenAPI 規格名稱。
    • SERVICE_ACCOUNT_EMAIL：指定用於為已設定驗證的後端簽署權杖的服務帳戶。詳情請參閱「設定服務帳戶」。

    API Gateway 在建立 API 和 API 設定時，會將資訊輸出至終端機。API 設定會傳播至下游系統，因此這項作業可能需要幾分鐘才能完成。建立複雜的 API 設定最多可能需要十分鐘才能完成。建立設定時，請勿嘗試為同一 API 建立其他設定。一次只能為任何 API 建立一個設定。

  5. 成功完成之後，您可以使用下列指令查看新 API 設定的詳細資料：

    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

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

    createTime: '2020-02-04T18:33:11.882707149Z'
displayName: CONFIG_ID
gatewayConfig:
  backendConfig:
    googleServiceAccount: 1111111@developer.gserviceaccount.com
labels: ''
name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
serviceRollout:
  rolloutId: 2020-02-04r2
state: ACTIVE
updateTime: '2020-02-04T18:33:12.219323647Z'

  6. 使用 API 的代管服務名稱啟用 API。您可以在 API 登陸頁面的「代管服務」欄中找到 API 的這個值：

    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

    建立 API 時，您只需要執行一次這個指令。如果日後修改 API，不必重新執行指令。

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

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

例如：

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \
  --async --display-name=MyConfig --labels=a=1,b=2

您可以在 describe 指令的輸出內容中查看標籤，也可以在 list 指令中加入 --format 選項：

gcloud api-gateway api-configs list \
  --api=API_ID --format="table(name, labels)"

列出 API 設定

如要列出特定專案的 API 設定：

gcloud api-gateway api-configs list

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

NAME                                                                DISPLAY_NAME  ROLLOUT_ID    STATE   CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

如要列出專案中特定 API 的 API 設定：

gcloud api-gateway api-configs list --api=API_ID

使用 API 和設定 ID，取得 API 設定的詳細資訊：

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

更新 API 設定

除了更新現有 API 設定的標籤和顯示名稱外，您無法修改其他設定。

使用下列 gcloud 更新現有 API 設定：

  • --display-name
  • --update-labels
  • --clear-labels
  • --remove-labels

例如：

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID \
  --update-labels=a=1,b=2

使用下列指令查看所有更新選項：

gcloud api-gateway api-configs update --help

刪除 API 設定

使用下列 gcloud 指令刪除現有的 API 設定：

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

後續步驟