配置 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 服务页面上显示的服务名称会与对 API 的请求中使用的名称相匹配。此外，如果您的服务名称和域名相同，则可以为 API 用户创建 Cloud Endpoints 门户。Endpoints 对服务名称有以下要求：

  • 域名的长度上限为 253 个字符。
  • 域名必须以小写字母开头。
  • 域名中用点分隔开的每个部分均必须满足以下要求：
    • 必须以小写字母开头。
    • 不得以短划线结尾。
    • 其余字符可以是小写字母、数字或短划线。
    • 长度上限为 63 个字符。

您可以注册自己的自定义网域（例如 example.com），也可以使用由 Google 管理的网域。

使用由 Google 管理的网域

cloud.goog 和 appspot.com 网域归 Google 所有并由其管理。如果您想要使用由 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 中必须是唯一的。请参阅说明： operationId 。

后续步骤