配置 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.googappspot.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

后续步骤