Postman 使用服务定义
gRPC 是一个模式驱动的框架。这意味着客户端和服务器在调用和执行请求时必须遵守标准协议(架构)。服务定义可以实现这一点。在客户端,服务定义使客户端了解服务器支持的所有服务和方法以及消息负载结构、支持的字段和数据类型。任何不遵循服务定义强制执行的规定的行为都会导致错误。在请求执行过程中,服务定义用于序列化双方交换的信息。
gRPC 使用protobuf(协议缓冲区)作为接口定义语言(IDL)来定义服务定义。创建 gRPC 请求时,您需要将适当的服务定义添加到请求以选择要调用的方法。您可以通过前往gRPC 请求中的“服务定义”选项卡来配置服务定义。
创建新请求时,如果未配置服务定义,Postman 会在您选择“方法选择”下拉列表时提示您进行配置。此接口可作为一种快速方式来添加您的服务定义并继续调用您的请求。.proto从这个菜单中,您可以选择工作区中可用的 protobuf API,或者通过将文件从本地系统拖放到 Postman 中来导入新 API 。
要将服务定义加载到请求中,您可以使用服务器反射来加载服务定义,或者使用 protobuf API 作为服务定义。
内容
使用服务器反射
如果由服务器启用,服务器反射可能是将服务定义添加到客户端的最简单方法。它从服务器获取模式中可用的最新信息,而无需您手动加载文件.proto或创建 protobuf 模式。输入 URL,Postman 会自动加载服务定义。
使用 protobuf API
如果服务器未启用服务器反射,您可以使用 protobuf API 作为请求的服务定义。为此,您可以在工作区中选择现有的 protobuf API,或者将文件.proto作为 protobuf API 导入 Postman。您还可以使用 Postman API Builder 创建新的 protobuf API。
从工作区中选择现有的 protobuf API
转到Service definition选项卡并选择Select a protobuf API from this workspace。这将打开API 选择下拉列表,您可以在其中浏览可用的 API 并选择您要使用的 API。
在测试服务时,您还可以通过选择API 名称旁边的版本选择器来切换到所选 API 的不同版本。
导入 .proto 文件
如果您的工作区中没有可用的 protobuf API,您还可以将.proto文件作为 protobuf API 导入 Postman,并将其用作服务定义。
要导入.proto文件,请执行以下操作:
- 转到服务定义选项卡并选择导入 .proto 文件。
- .proto您可以从本地系统拖放文件或选择选择文件以打开文件资源管理器。
- 选择文件后,选择下一步。这会将您带到Import as API界面。
- 为您的新 API 命名,添加版本名称,然后选择Import as API。
这将从文件中创建一个新的 protobuf API .proto,并将其作为服务定义用于请求中。
您还可以将该.proto文件导入为现有 API 的更新。在Import as API界面上,您可以从工作区的可用 API 列表中选择一个 API,并将该.proto文件添加为新版本。您还可以通过从列表中选择现有版本来将其替换为现有版本。
除了.proto从本地系统导入文件,您还可以.proto通过在导入界面中输入 URL 而不是选择Choose a file来从 URL 获取文件。
Postman 支持导入多文件模式。您可以导入.proto包含引用其他文件的指令的文件import。
添加导入路径
有时,gRPC 模式可以分为多个 .proto 文件。这些 .proto 文件通过模式中的导入指令引用。/Users/johndoe/projects/my-app/protos/enums/NumericEnum.proto包含绝对路径(例如)和相对路径( )的导入指令../enums/NumericEnum.proto由 Postman 自动解析,不需要任何额外配置。如果导入指令不包含绝对路径或相对路径,则必须添加它们的父目录。
考虑这个示例文件结构:
在此示例中,root.proto包含引用文件夹.proto中其他文件的导入指令protos。这些导入指令在架构中可能看起来像这样:
import "enums/NumericEnum.proto"
import "messages/EmptyMessage.proto"
import "messages/HelloResponse.proto"
import "messages/HelloRequest.proto"
在这种情况下,您需要将enums和messages(换句话说,protos)的父目录配置为您在 Postman 中的导入路径。添加的导入路径可能如下所示:/Users/johndoe/projects/my-app/protos/. 选择要导入的文件后,您可以使用导入流程中的导入路径选项在请求中配置导入路径。
创建一个新的 protobuf API
转到服务定义选项卡并选择创建新 API。这将启动创建新 API 流程,您必须在其中命名新 API 和版本,并选择要创建的 API 类型。Postman 支持在protobuf 语言的版本 2 和 3 中创建 protobuf API 。完成后,选择Create New API。这将在新选项卡中的 Postman API Builder 中打开 API。
下一步
了解有关使用 API Builder 创建和管理 protobuf API 的更多信息。