建立 API 設定

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

事前準備

建立 API 設定前，請先完成下列步驟：

按照「設定開發環境」一文所述，準備開發環境。
以 OpenAPI 規格建立 API 定義。
如果使用 Google Cloud CLI，可以選擇建立 API。如果 API 不存在，建立 API 設定時就會建立 API。

注意：使用 Google Cloud 控制台時，系統會在將 API 部署至閘道時建立 API 和 API 設定。

API 設定 ID 規定

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

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

建立 API 設定

上傳 API 定義來建立 API 設定。

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

Google Cloud 控制台

在將 API 部署至閘道時，建立 API 設定。

Google Cloud CLI

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

切換至包含 API 定義的目錄。

如要進一步瞭解如何為 API 定義建立 OpenAPI 規格，請參閱 OpenAPI 總覽和快速入門：使用 gcloud CLI 保護服務流量。

如要進一步瞭解如何為 API 定義建立 gRPC 服務定義和設定，請參閱「設定 gRPC 服務」和「開始使用 API 閘道搭配 Cloud Run 和 gRPC」。
請利用下列指令傳回的專案 ID 進行驗證，以確保系統沒有將服務建立在錯誤的專案中。
```
gcloud config list project
```
如要變更預設專案，請執行下列指令，並將 PROJECT_ID 改成要建立服務的專案 ID： Google Cloud
```
gcloud config set project PROJECT_ID
```

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

gcloud api-gateway api-configs create --help

執行下列指令來建立 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 設定的服務帳戶」。
API Gateway 在建立 API 和 API 設定時，會將資訊輸出至終端機。由於 API 設定會傳播至下游系統，這項作業可能需要幾分鐘才能完成。建立複雜的 API 設定最多可能需要十分鐘。建立設定時，請勿嘗試為同一項 API 建立其他設定。每個 API 一次只能建立一個設定。

成功完成之後，您可以使用下列指令查看新 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'

使用 API 的代管服務名稱啟用 API。您可以在 API 登陸頁面的「代管服務」欄中找到 API 的這個值：
```
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
```
建立 API 時，您只需要執行一次這個指令。如果日後修改 API，不必重新執行指令。

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

--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 設定

列出 Google Cloud 專案中部署的所有 API Gateway。

Google Cloud 控制台

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

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

前往 API Gateway
按一下必要的 API。
按一下「Configs」分頁標籤。

頁面會顯示可用的 API 設定清單。

Google Cloud CLI

如要列出特定專案的 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 設定的標籤和顯示名稱外，您無法修改其他設定。

Google Cloud 控制台

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

前往 API Gateway
按一下必要的 API。
按一下「Configs」分頁標籤。
按一下所需的 API 設定。
按一下「編輯」。
編輯「顯示名稱」或「標籤」。
按一下 [儲存]。

Google Cloud CLI

使用下列 `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 設定

如要刪除正在使用的 API 設定，請先採取下列任一做法：

將其他 API 設定部署至閘道。
刪除閘道。

詳情請參閱「將 API 部署至閘道」。

Google Cloud 控制台

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

前往 API Gateway
按一下必要的 API。
按一下「Configs」分頁標籤。
依序按一下「更多」和「刪除」，即可刪除所選的 API 設定。

Google Cloud CLI

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

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

後續步驟

將 API 部署至閘道