Testar serviços gRPC com gRPCurl e gRPCui no ASP.NET Core

Por James Newton-King

As ferramentas estão disponíveis para gRPC que permite aos desenvolvedores testar serviços sem criar aplicativos cliente:

• gRPCurl é uma ferramenta de linha de comando de código aberto que fornece interação com serviços gRPC.
• gRPCui tem base em gRPCurl e adiciona uma interface do usuário da Web interativa de código aberto para gRPC.

Este artigo discute como:

• Configurar a reflexão do servidor gRPC com um aplicativo gRPC ASP.NET Core.
• Interagir com gRPC usando ferramentas de teste:
  • Descubrir e testar serviços gRPC com grpcurl.
  • Interagir com serviços gRPC por meio de um navegador usando grpcui.

Observação

Para saber como testar a unidade de serviços gRPC, confira Testar serviços gRPC no ASP.NET Core.

Configurar reflexão gRPC

As ferramentas devem conhecer o contrato de serviços de Protobuf antes de poder chamá-los. Há duas maneiras de fazer isso:

• Configure a reflexão gRPC no servidor. Ferramentas, como gRPCurl, usam reflexão para descobrir automaticamente contratos de serviço.
• Adicione arquivos .proto à ferramenta manualmente.

É mais fácil usar a reflexão gRPC. A reflexão gRPC adiciona um novo serviço gRPC ao aplicativo que os clientes podem chamar para descobrir serviços.

gRPC ASP.NET Core tem suporte interno para reflexão gRPC com o pacote Grpc.AspNetCore.Server.Reflection. Para configurar a reflexão em um aplicativo:

• Adicione uma referência de pacote para Grpc.AspNetCore.Server.Reflection.
• Registrar reflexão em Program.cs:
  • AddGrpcReflection para registrar serviços que habilitam a reflexão.
  • MapGrpcReflectionService para adicionar um ponto de extremidade de serviço de reflexão.

builder.Services.AddGrpc();
builder.Services.AddGrpcReflection();

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

Quando a reflexão gRPC é configurada:

• Um serviço de reflexão gRPC é adicionado ao aplicativo de servidor.
• Aplicativos cliente que dão suporte à reflexão gRPC podem chamar o serviço de reflexão para descobrir os serviços hospedados pelo servidor.
• Os serviços gRPC ainda são chamados do cliente. A reflexão apenas habilita a descoberta de serviço e não ignora a segurança do lado do servidor. Os pontos de extremidade protegidos por autenticação e autorização exigem que o chamador passe credenciais para que o ponto de extremidade seja chamado com êxito.

Segurança do serviço de reflexão

A reflexão gRPC retorna uma lista de APIs disponíveis, que podem conter informações confidenciais. Deve-se tomar cuidado para limitar o acesso ao serviço de reflexão gRPC.

A reflexão gRPC geralmente é necessária apenas em um ambiente de desenvolvimento local. Para o desenvolvimento local, o serviço de reflexão só deve ser mapeado quando IsDevelopment retornar true:

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

O acesso ao serviço pode ser controlado por meio de métodos padrão de extensão de autorização do ASP.NET Core, como AllowAnonymous e RequireAuthorization.

Por exemplo, se um aplicativo tiver sido configurado para exigir a autorização por padrão, configure o ponto de extremidade de reflexão gRPC com AllowAnonymous para ignorar a autenticação e a autorização.

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService().AllowAnonymous();
}

gRPCurl

gRPCurl é uma ferramenta de linha de comando criada pela comunidade gRPC. Seus recursos incluem:

• Chamando serviços gRPC, incluindo serviços de streaming.
• Descoberta de serviço usando reflexão de gRPC.
• Listando e descrevendo serviços gRPC.
• Funciona com servidores seguros (TLS) e inseguros (texto sem formatação).

Para obter informações sobre como baixar e instalar grpcurl, confira a página inicial do GitHub gRPCurl.

Use grpcurl.

O argumento -help explica as opções de linha de comando de grpcurl:

$ grpcurl -help

Descobrir serviços

Use o verbo describe para exibir os serviços definidos pelo servidor. Especifique <port> como o número da porta localhost do servidor gRPC. O número de porta é atribuído aleatoriamente quando o projeto do servidor gRPC é criado e definido em Properties/launchSettings.json:

$ grpcurl localhost:<port> describe
greet.Greeter is a service:
service Greeter {
  rpc SayHello ( .greet.HelloRequest ) returns ( .greet.HelloReply );
  rpc SayHellos ( .greet.HelloRequest ) returns ( stream .greet.HelloReply );
}
grpc.reflection.v1alpha.ServerReflection is a service:
service ServerReflection {
  rpc ServerReflectionInfo ( stream .grpc.reflection.v1alpha.ServerReflectionRequest ) returns ( stream .grpc.reflection.v1alpha.ServerReflectionResponse );
}

No exemplo anterior:

• Executa o verbo describe no servidor localhost:<port>. Em que <port> é atribuído aleatoriamente quando o projeto do servidor gRPC é criado e definido em Properties/launchSettings.json
• Imprime serviços e métodos retornados pela reflexão gRPC.
  • Greeter é um serviço implementado pelo aplicativo.
  • ServerReflection é o serviço adicionado pelo pacote Grpc.AspNetCore.Server.Reflection.

Combine describe com um serviço, um método ou um nome de mensagem para exibir seus detalhes:

$ grpcurl localhost:<port> describe greet.HelloRequest
greet.HelloRequest is a message:
message HelloRequest {
  string name = 1;
}

Chamar serviços gRPC

Chame um serviço gRPC especificando um nome de serviço e método junto com um argumento JSON que representa a mensagem de solicitação. O JSON é convertido em Protobuf e enviado para o serviço.

$ grpcurl -d '{ \"name\": \"World\" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

No exemplo anterior:

• O argumento -d especifica uma mensagem de solicitação com JSON. Esse argumento deve vir antes do endereço do servidor e do nome do método.
• Chama o método SayHello no serviço greeter.Greeter.
• Imprime a mensagem de resposta como JSON.
• Em que <port> é atribuído aleatoriamente quando o projeto do servidor gRPC é criado e definido em Properties/launchSettings.json

O exemplo anterior usa \ para escapar o caractere ". O escape de " é necessário em um console do PowerShell, mas não deve ser usado em alguns consoles. Por exemplo, o comando anterior para um console macOS:

$ grpcurl -d '{ "name": "World" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

gRPCui

gRPCui é uma interface do usuário da Web interativa para gRPC. gRPCui se baseia em gRPCurl. gRPCui oferece uma GUI para descobrir e testar serviços gRPC, semelhantes a ferramentas HTTP, como a interface do usuário do Swagger.

Para obter informações sobre como baixar e instalar grpcui, confira a página inicial do gRPCurl no GitHub.

Usando grpcui

Execute grpcui com o endereço do servidor com o qual interagir como um argumento:

$ grpcui localhost:<port>
gRPC Web UI available at http://127.0.0.1:55038/

No exemplo anterior, especifique <port> como o número da porta localhost do servidor gRPC. O número da porta é atribuído aleatoriamente quando o projeto é criado e definido em Properties/launchSettings.json

A ferramenta inicia uma janela do navegador com a interface do usuário da Web interativa. Os serviços do gRPC são descobertos automaticamente usando a reflexão gRPC.

Recursos adicionais

• Página inicial do gRPCurl no GitHub
• Página inicial do gRPCui no GitHub
• Grpc.AspNetCore.Server.Reflection
• Testar os serviços do gRPC no ASP.NET Core
• Cliente gRPC simulado em testes