配置 Cloud Endpoints

本页面介绍了创建由 Endpoints 管理的 gRPC 服务所需的配置文件。

前提条件

首先，本页假定您已完成以下操作：

选择服务名称

Cloud Endpoints 会使用您在 gRPC API 配置 YAML 文件中配置的名称作为服务名称。

您的 API 服务名称在 Google Cloud上必须是唯一的。由于 Endpoints 使用符合 DNS 规范的名称来识别服务，因此建议您使用 API 的域名或子网域名作为服务名称。使用此方法，Endpoints 服务页面上显示的服务名称会与对 API 的请求中使用的名称相匹配。Endpoints 对服务名称有以下要求：

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

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

使用由 Google 管理的网域

cloud.goog 网域归 Google 所有并由其管理。如果您想要使用由 Google 管理的网域，则必须在服务名称中包括您的 Google Cloud 项目 ID。由于 Google Cloud 项目具有全局唯一的项目 ID，因此这项要求可确保您的服务名称是独一无二的。如果您想要使用 cloud.goog 网域，则服务名称必须采用以下格式，其中 YOUR_API_NAME 是 API 的名称，而 YOUR_PROJECT_ID 是您的Google Cloud 项目 ID：

YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`

要将此网域用作 API 的域名，请参阅在 cloud.goog 网域上配置 DNS。

使用自定义网域

如果您不想使用由 Google 管理的网域，则可以使用您有权使用的自定义网域（例如 myapi.mycompany.com）。在部署 API 配置之前，请先按照验证网域所有权中的步骤操作。

配置协议缓冲区

  1. 为您的服务创建一个 .proto 文件。如需了解详情，请阅读开发者指南。

  2. 使用适用于您所用语言的 protoc 编译器来编译 Protocol Buffers。例如：

    protoc
  --proto_path=. \
  --include_imports \
  --include_source_info \
  --descriptor_set_out=api_descriptor.pb \
  bookstore.proto

    在前面的命令中，--proto_path 设置为当前工作目录。在 gRPC 构建环境中，如果为 .proto 输入文件使用不同的目录，请更改 --proto_path，以便编译器搜索您在其中保存了 .proto 文件的目录。

    如果 protoc 命令无法生成描述符文件，请确保以下几点：

    • 您的 protoc 是最新版本。
    • 您已在 --proto_path（简写形式为 -I）中指定用于保存所导入 .proto 文件的根目录。如需了解详情，请参阅 Protocol Buffers 文档。
    • 您已指定 --include_imports。

    如果您希望客户端通过结合使用 HTTP 和 JSON 来访问 gRPC 服务，则需要指定如何将数据从 HTTP 和 JSON 转换为 gRPC。建议您为 .proto 文件中定义的 API 添加注释。如需了解详情，请参阅将 HTTP/JSON 转码为 gRPC。

配置 gRPC 服务配置文件

您需要创建一个 gRPC 服务配置 YAML 文件。在此文件中，您可以指定服务名称和使用限制，例如要求使用 API 密钥。 您可以将 Bookstore 示例中的 api_config.yaml 文件用作模型。

  1. 保存 api_config.yaml 的副本。

  2. 在 name 字段中输入服务的名称。例如：

    name: bookstore.endpoints.example-project-12345.cloud.goog

  3. 输入在 Google Cloud 控制台中 Endpoints > Services 页面上显示的标题。例如：

    title: Bookstore gRPC API

  4. 在 apis:name 字段中输入 API 名称。您输入的文本必须与 .proto 文件中的完全限定 API 名称完全匹配。例如：

    apis:
  - name: endpoints.examples.bookstore.Bookstore

  5. 配置文件的其余部分。例如：

    #
# API usage restrictions.
#
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true

    如需了解详情，请参阅规则和选择器。

后续步骤

其他 gRPC 示例