設定 Cloud Endpoints

Cloud Endpoints 支援使用 OpenAPI 規範 2.0 版說明的 API。您可以在 OpenAPI 文件中說明 API 介面並設定 Endpoints 功能，例如驗證規則或配額。

Endpoints 會以特殊的方式使用 OpenAPI 文件中的下列必填欄位：

  • host
  • info.title
  • info.version
  • operationId

本頁提供 Endpoints 如何使用上述欄位的相關資訊。有了這項資訊，您就可以完成 OpenAPI 文件準備以進行部署。

必備條件

本頁假設您已經：

host

Cloud Endpoints 會使用您在 OpenAPI 文件的 host 欄位中設定的名稱做為您的服務名稱。

API 服務的名稱在 Google Cloud上不得重複。因為 Endpoints 會使用與 DNS 相容的名稱來識別服務，因此建議您使用 API 的網域名稱或子網域名稱做為服務名稱。使用這個方法時，「Endpoints Services」(Endpoints 服務) 頁面中顯示的服務名稱，會與用來要求您的 API 時所使用的名稱相符。Endpoints 對服務名稱有以下要求：

  • 網域名稱的長度上限為 253 個字元。
  • 網域名稱開頭必須為小寫英文字母。
  • 網域名稱中以點分隔的每個部分都具有下列需求條件：
    • 開頭必須為小寫字母。
    • 不得以破折號結尾。
    • 剩餘字元可為小寫字母、數字或破折號。
    • 長度上限為 63 個半形字元。

您可以註冊自訂網域 (如 example.com)，也可以使用 Google 代管的網域。

使用 Google 代管的網域

Google 擁有並管理 cloud.goog 和 appspot.com 網域。如果您要使用 Google 代管的網域，就必須使用您的Google Cloud 專案 ID 做為服務名稱的一部分。因為Google Cloud 專案具備全域不重複的專案 ID，因此這項要求可確保您擁有不重複的服務名稱。

您使用的網域名稱視託管您 API 的後端而定：

  • 若在 App Engine 彈性環境中託管 API，您必須使用 appspot.com 網域，且服務名稱必須採用下列格式，其中 YOUR_PROJECT_ID 是您的 Google Cloud 專案 ID：

    YOUR_PROJECT_ID.appspot.com

    將 API 部署至 App Engine 時，系統會自動建立名稱格式為 YOUR_PROJECT_ID.appspot.com 的 DNS 項目。

  • 若在 Compute Engine、Google Kubernetes Engine 或 Kubernetes 中託管 API，您必須使用 cloud.goog 網域，且服務名稱必須採用下列格式，其中 YOUR_API_NAME 是您的 API 名稱：

    YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog

    如要使用這個網域做為 API 的網域名稱，請參閱「在 cloud.goog 網域上設定 DNS」一文。

使用自訂網域

如果不想使用 Google 代管的網域，則可採用您已獲授權使用的自訂網域 (例如 myapi.mycompany.com)。在部署 API 設定之前，請先按照「驗證網域擁有權」中的步驟進行。

info.title

info.title 欄位是 API 的易記名稱。 Google Cloud 控制台的「Endpoints」 >「Services」頁面會顯示您在 info.title 欄位中設定的文字。如果每個 Google Cloud 專案擁有多個 API，在您第一次開啟頁面時，API 名稱會顯示在清單中。您可以按一下 API 名稱以開啟另一個頁面，該頁面會顯示 API 的指標、部署記錄和其他資訊。

info.version

Google Cloud 主控台中的「Endpoints」 >「Services」頁面會顯示 API 的版本號碼。在首次部署 API 設定之前，請先執行下列操作：

  • 將 info.version 欄位中的版本號碼設為適用的 API 版本，例如 1.0。

  • 將 basePath 欄位設為主要版本號碼，例如 /v1。

如要進一步瞭解如何進行 API 版本管理，請參閱 API 生命週期管理一文。

operationId

雖然 operationId 是 OpenAPI 規範中的選填欄位，但 Endpoints 需要這個欄位以用於作業的內部識別。您用於 operationId 的字串不能在 API 中重複。如需命名的相關指南，請參閱 OpenAPI 規範中的 operationId 說明。

後續步驟