配置 Cloud Endpoints

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

前提条件

首先,本页假定您已完成以下操作:

选择服务名称

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

您的 API 服务名称在 Google Cloud 上必须是唯一的。由于 Endpoints 使用符合 DNS 规范的名称来识别服务,因此建议您使用 API 的域名或子网域名作为服务名称。使用此方法,Endpoints 服务页面上显示的服务名称会与对 API 的请求中使用的名称相匹配。此外,如果您的服务名称和域名相同,则可以为 API 用户创建 Cloud Endpoints 门户。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 示例