修改 Cloud Endpoints 以使用 OpenAPI 3.x

本頁說明如何使用 OpenAPI 3.x 規格設定 Endpoints。

事前準備

  • 確認您已設定現有的 Endpoints 執行個體，並使用 OpenAPI 2.0 規格。
  • 安裝 gcloud CLI。詳情請參閱「安裝 Google Cloud CLI」。

修改 Endpoints 設定，改用 OpenAPI 3.x

如要修改現有的 OpenAPI 2.0 Endpoints 設定，改用 OpenAPI 3.x，請完成下列步驟。

查看部署記錄

如何檢視部署記錄：

  1. 在 Google Cloud 控制台中，前往「Endpoints」 >「Services」(服務) 頁面。

    前往 Endpoints 服務頁面

  2. 從專案清單中選取您的專案。

  3. 如果您有多個 API，請從清單中選取一個 API。

  4. 如要查看服務設定部署作業的清單，請按一下 [Deployment history] (部署記錄) 分頁標籤。清單會顯示下列項目：

    • 設定 ID。
    • 服務設定的部署日期。
    • 部署服務設定的人員。

查看服務設定

在「Deployment history」(部署記錄) 分頁上，從清單中選取最近的部署作業。畫面隨即會顯示已部署服務設定檔的內容。

將 OpenAPI 文件轉換為 OpenAPI 3.x

將 OpenAPI 2.0 文件轉換為 OpenAPI 3.x。您可以使用支援這項轉換的工具，將 OpenAPI 2.0 轉換為 OpenAPI 3.x。舉例來說，Swagger 編輯器提供轉換公用程式。

初步轉換為 OpenAPI 3.x 後，請手動對文件套用任何其他變更，以符合 OpenAPI 3.x，並確保與 Endpoints 擴充功能和功能相容。

下表說明必要變更：

功能 OpenAPI 2.0 OpenAPI 3.x 變更說明
API 金鑰 securityDefinitions securitySchemes API 金鑰使用現成的 OpenAPI API 金鑰支援功能。轉換工具通常會自動處理這項作業。無須手動變更。
JWT 驗證 x-google-audiences 等 x-google-auth 在 OpenAPI 2.0 擴充功能中，您可以使用 securityDefinition 執行個體上的個別擴充功能定義 OAuth 設定。轉換工具會將安全機制執行個體轉換為 #/components/securitySchemes，並保留擴充功能。手動修改這些擴充功能，使其成為 x-google-auth 的子項，並移除 x-google- 前置字元。值保持不變。
配額 x-google-management、x-google-quota x-google-api-management、x-google-quota 在 OpenAPI 2.0 擴充功能中，您可以在 x-google-management 中定義指標和配額，並使用 x-google-quota 附加這些項目。轉換工具會保留這些擴充功能。手動將指標和配額設定從 x-google-management 移至 x-google-api-management。將設定變更為使用 YAML 鍵，並移除 valueType、metricKind 和 unit。從 x-google-quota 的執行個體中移除 metricCosts。
後端 x-google-backend x-google-api-management、x-google-backend 在 OpenAPI 2.0 擴充功能中，您可以在 x-google-backend 中定義後端，而設定會套用至定義位置。在 OpenAPI 3.x 擴充功能中，您可以在 x-google-api-management 中定義後端，然後使用 x-google-backend 套用。轉換工具會保留這個擴充功能。手動將設定移至 x-google-api-management。修改 x-google-backend 的執行個體，以參照該設定。
端點 x-google-endpoints x-google-endpoint、servers 在 OpenAPI 2.0 擴充功能中，您可以在 x-google-endpoints 中定義端點設定。在 OpenAPI 3.x 擴充功能中，您會使用 x-google-endpoint，但這是 servers 的擴充功能，而不是根層級的擴充功能。轉換工具會保留這個擴充功能。請手動將此項目移至 servers，並移除 name 欄位。例如：
# OpenAPI 2.0
x-google-endpoints:
- name: "my-api.apigateway.my-project.cloud.goog"
  allowCors: True
# OpenAPI 3.x
servers:
- url: https://my-api.apigateway.my-project.cloud.goog/
  x-google-endpoint:
    allowCors: True
API 名稱 x-google-api-name x-google-api-management 在 OpenAPI 2.0 擴充功能中，您可以在 x-google-api-name 中定義 API 名稱。在 OpenAPI 3.x 擴充功能中，您可以使用 x-google-api-management 中的 apiName 欄位。手動將這項設定移至 x-google-api-management。
允許所有流量 x-google-allow 尚未支援 請從 OpenAPI 文件中移除這項設定。Endpoints 不支援 OpenAPI 3.x 中的這項功能。

重新部署服務設定

每次您變更 OpenAPI 文件的部分內容後，請務必再次部署，Endpoints 才能取得您的 API 服務設定的最新版本。如果您之前部署 ESP 時將 rollout 選項設為 managed，則無須重新部署或重新啟動 ESP。這個選項可將 ESP 設為使用最新部署的服務設定。指定此選項時，在您部署新服務設定後最多 5 分鐘內，ESP 會偵測到變更並自動開始使用新設定。建議您指定此選項而非讓 ESP 使用特定的設定 ID。

如何部署 OpenAPI 文件：

  1. 將目錄變更為包含 OpenAPI 文件的位置。

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

    gcloud config list project

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

    gcloud config set project <var>YOUR_PROJECT_ID</var>

  3. 執行下列指令，並將 YOUR_OPENAPI_DOCUMENT 改成描述您的 API 的 OpenAPI 文件名稱：

    gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>

首次執行上述指令時，Service Management 會在預設專案中使用您在 OpenAPI 文件 host 欄位裡指定的名稱建立新的 Endpoints 服務，並上傳您的服務設定。

Service Management 在建立和設定服務時，會將資訊輸出至終端機。成功完成後，您會看到下列顯示服務設定 ID 和服務名稱的一行文字：

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

在上方範例中，2017-02-13r0 是服務設定 ID，echo-api.endpoints.example-project-12345.cloud.goog 則是服務名稱。

成功部署後，您可在 Google Cloud 主控台的「Endpoints」 >「Services」(服務) 頁面查看 API。

如果您收到錯誤訊息，請參閱 Endpoints 設定部署疑難排解一文。

後續步驟