將 API 部署至閘道

本頁說明如何將 API 部署至 API Gateway。

必要條件

將 API 部署至 API Gateway 前，請務必完成下列事項：

按照「設定開發環境」一文所述，準備開發環境。
如果使用 Google Cloud CLI，請建立 API。
注意：使用 Google Cloud 控制台時，部署 API 時會完成這個步驟，詳情請參閱下文。
建立 OpenAPI 規格來定義 API。
從 API 定義建立 API 設定。

閘道 ID 規定

下列許多 gcloud CLI 指令都需要您指定閘道 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 部署至閘道

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

Google Cloud 控制台

前往 Google Cloud 控制台的「API Gateway」頁面。

前往 API Gateway
按一下「建立閘道」
系統會顯示「建立閘道」頁面。
在「選取 API」中，選取「選取 API」欄位中的「建立新的 API」。
在「Display Name」(顯示名稱) 欄位中，輸入 API 的顯示名稱。
在「API ID」欄位中，輸入 API 的 ID。如需 API 命名指南，請參閱「API ID 規定」。
(選用) 為 API 新增標籤。
在「API 設定」部分，選取「選取設定」欄位中的「建立新的 API 設定」
在「上傳 API 規格」欄位中，上傳 .yaml 或 .json 檔案。如需 API 定義，請參閱 OpenAPI 2.0 和 OpenAPI 3.x 檔案格式。
在「Display Name」(顯示名稱) 欄位中，輸入 API 設定的顯示名稱。
在「選取服務帳戶」清單中，選取所需服務帳戶。API Gateway 會使用這個服務帳戶做為身分。
(選用) 為 API 設定新增標籤。
在「閘道詳細資料」部分，輸入閘道的顯示名稱。
在「Location」(位置) 欄位中，選取要部署閘道的 Google Cloud 區域。
(選用) 為 API Gateway 新增標籤。
按一下「建立閘道」。

新建立的 API 會顯示在 API Gateway 首頁。

Google Cloud CLI

請利用下列指令傳回的專案 ID 進行驗證，以確保系統沒有將閘道建立在錯誤的專案中。
```
gcloud config list project
```
如要變更預設的專案，請執行下列指令，並將 PROJECT_ID 改成要建立服務的 Google Cloud 專案 ID：
```
gcloud config set project PROJECT_ID
```

查看 gateway create 指令的說明：

gcloud api-gateway gateways create --help

執行下列指令，將 API 設定部署至閘道：
```
gcloud api-gateway gateways create GATEWAY_ID \
 --api=API_ID --api-config=CONFIG_ID \
 --location=GCP_REGION 
```
其中：
- GATEWAY_ID 指定新閘道的 ID。如果閘道不存在，這項指令會自動建立該閘道。
- API_ID 會指定與這個閘道相關聯的 API Gateway API ID。
- CONFIG_ID 會指定部署至閘道的 API 設定 ID。建立閘道時，您必須指定 API 設定。
- GCP_REGION 會指定已部署閘道的 Cloud 位置。
注意：
有效值為：
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
gcloud CLI 會在建立閘道時，將資訊輸出至終端機。

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

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

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

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

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

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

列出閘道

本節說明如何查看 Google Cloud 專案中部署的所有 API Gateway 清單。

Google Cloud 控制台

在 Google Cloud 控制台中，依序前往「API Gateway」(API 閘道) >「Gateways」(閘道) 頁面。

前往「閘道」頁面

Google Cloud CLI

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

gcloud api-gateway gateways list

這項指令會傳回下列格式的輸出內容：

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

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

gcloud api-gateway gateways list \
--filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_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 設定身分：

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

更新閘道

將閘道更新為：

將其他 API 設定部署至閘道
更新顯示名稱
更新標籤

Google Cloud 控制台

請按照下列步驟更新 API Gateway 詳細資料：

前往 Google Cloud 控制台的「API Gateway」頁面。

前往 API Gateway
按一下必要的 API。
按一下「閘道」分頁標籤。
按一下所需閘道。
按一下「編輯」。
編輯「顯示名稱」或「標籤」。
選取所需的「API 設定」，或按一下「建立新的 API 設定」，然後建立設定，如這裡所示。
按一下「Update」。
按一下返回閘道清單頁面。
在閘道清單頁面中，您可以查看更新後的閘道。

Google Cloud CLI

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

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

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

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

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

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

gcloud api-gateway gateways update --help

刪除閘道

本節說明如何刪除現有的 API Gateway。請按照下列步驟，從 Google Cloud 專案中永久移除閘道及其相關設定。

Google Cloud 控制台

在 Google Cloud 控制台中，依序前往「API Gateway」(API 閘道) >「Gateways」(閘道) 頁面。

前往「閘道」頁面
按一下「更多」，然後按一下「刪除」，即可刪除所選的 API Gateway。

Google Cloud CLI

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

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

將 API 部署至閘道

必要條件

閘道 ID 規定

定義已部署 API 設定的端點

將 API 部署至閘道

Google Cloud 控制台

Google Cloud CLI

列出閘道

Google Cloud 控制台

Google Cloud CLI

更新閘道

Google Cloud 控制台

Google Cloud CLI

刪除閘道

Google Cloud 控制台

Google Cloud CLI

後續步驟