Comprobación de servicios gRPC con gRPCurl y gRPCui en ASP.NET Core

Por James Newton-King

Hay herramientas disponibles para gRPC que permiten a los desarrolladores probar servicios sin necesidad de compilar aplicaciones cliente:

• gRPCurl es una herramienta de línea de comandos de código abierto que proporciona interacción con los servicios de gRPC.
• gRPCui se basa en gRPCurl y agrega una interfaz de usuario web interactiva de código abierto para gRPC.

En este artículo se describe cómo:

• Configurar la reflexión del servidor de gRPC con una aplicación gRPC de ASP.NET Core.
• Interactuar con gRPC mediante herramientas de prueba:
  • Detectar y probar servicios gRPC con grpcurl.
  • Interactuar con servicios gRPC a través de un explorador mediante grpcui.

Nota

Para obtener información sobre cómo realizar pruebas unitarias de los servicios gRPC, consulte Prueba de servicios gRPC en ASP.NET Core.

Configuración de la reflexión gRPC

Las herramientas deben conocer el contrato de servicios de Protobuf para poder llamarlos. Existen dos formas de hacerlo:

• Configurando una reflexión gRPC en el servidor. Las herramientas como gRPCurl usan la reflexión para detectar automáticamente contratos de servicio.
• Agregue archivos .proto a la herramienta manualmente.

Es más fácil usar la reflexión gRPC. La reflexión gRPC agrega un nuevo servicio gRPC a la aplicación al que los clientes pueden llamar para detectar servicios.

gRPC de ASP.NET Core tiene compatibilidad integrada con la reflexión gRPC con el paquete Grpc.AspNetCore.Server.Reflection. Para configurar la reflexión en una aplicación:

• Agregue una referencia de paquete Grpc.AspNetCore.Server.Reflection.
• Registre la reflexión en Program.cs:
  • AddGrpcReflection para registrar los servicios que habilitan la reflexión.
  • MapGrpcReflectionService para agregar un punto de conexión de servicio de reflexión.

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

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

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

Cuando la reflexión gRPC está configurada:

• Un servicio de reflexión gRPC se agrega a la aplicación de servidor.
• Las aplicaciones cliente que admiten la reflexión gRPC pueden llamar al servicio de reflexión para detectar los servicios hospedados por el servidor.
• Los servicios gRPC se siguen llamando desde el cliente. La reflexión solo habilita la detección de servicios, y no omite la seguridad del servidor. Los puntos de conexión protegidos por la autenticación y autorización requieren que el autor de la llamada pase unas credenciales determinadas para poder llamar al punto de conexión correctamente.

Seguridad del servicio de reflexión

La reflexión de gRPC devuelve una lista de las API disponibles, que podrían contener información confidencial. Se debe tener cuidado para limitar el acceso al servicio de reflexión de gRPC.

La reflexión de gRPC normalmente solo es necesaria en un entorno de desarrollo local. Para el desarrollo local, el servicio de reflexión solo se debe asignar cuando IsDevelopment devuelve true:

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

El acceso al servicio se puede controlar mediante métodos estándar de extensión de autorización de ASP.NET Core, como AllowAnonymous y RequireAuthorization.

Por ejemplo, si una aplicación se ha configurado para requerir autorización de forma predeterminada, configure el punto de conexión de reflexión de gRPC con AllowAnonymous para omitir la autenticación y la autorización.

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

gRPCurl

gRPCurl es una herramienta de línea de comandos creada por la comunidad de gRPC. Sus características incluyen:

• Llamada a servicios gRPC, incluidos los servicios de streaming.
• Detección de servicios mediante la reflexión gRPC.
• Enumeración y descripción de servicios gRPC.
• Funciona con servidores seguros (TLS) e inseguros (texto sin formato).

Para más información sobre la descarga e instalación de grpcurl, consulte la página principal de GitHub de gRPCurl.

Use grpcurl

En el argumento -help se explican las opciones de la línea de comandos grpcurl:

$ grpcurl -help

Detección de servicios

Utilice el verbo describe para ver los servicios definidos por el servidor. Especifique <port> como número de puerto localhost del servidor gRPC. El número de puerto se asigna aleatoriamente cuando se crea el proyecto y se establece en 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 );
}

Ejemplo anterior:

• Ejecuta el verbo describe en el servidor localhost:<port>. Donde <port> se asigna aleatoriamente cuando se crea el proyecto de servidor gRPC y se establece en Properties/launchSettings.json
• Imprime los servicios y métodos devueltos por la reflexión gRPC.
  • Greeter es un servicio implementado por la aplicación.
  • ServerReflection es el servicio agregado por el paquete Grpc.AspNetCore.Server.Reflection.

Combine describe con un nombre de servicio, método o mensaje para ver sus detalles:

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

Llamada a servicios gRPC

Llame a un servicio gRPC especificando un nombre de método y servicio, junto con un argumento JSON que representa el mensaje de solicitud. El formato JSON se convierte a Protobuf y se envía al servicio.

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

En el ejemplo anterior:

• El argumento -d especifica un mensaje de solicitud con JSON. Este argumento debe ir delante de la dirección del servidor y el nombre del método.
• Llama al método SayHello en el servicio greeter.Greeter.
• Imprime el mensaje de respuesta como JSON.
• Donde <port> se asigna aleatoriamente cuando se crea el proyecto de servidor gRPC y se establece en Properties/launchSettings.json

En el ejemplo anterior se usa \ para realizar el escape del carácter ". El escape de " es necesario en una consola de PowerShell, pero no se debe usar en algunas consolas. Por ejemplo, el comando anterior para una consola de macOS:

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

gRPCui

gRPCui es una interfaz de usuario web interactiva para gRPC. gRPCui se basa en gRPCurl. gRPCui ofrece una interfaz gráfica de usuario para detectar y probar servicios gRPC, de forma similar a herramientas HTTP como la interfaz de usuario de Swagger.

Para más información sobre la descarga e instalación de grpcui, consulte la página principal de GitHub de gRPCui.

Usar grpcui

Ejecute grpcui con la dirección del servidor con el que se va a interactuar como argumento:

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

En el ejemplo anterior, especifique <port> como número de puerto localhost del servidor gRPC. El número de puerto se asigna aleatoriamente cuando se crea el proyecto y se establece en Properties/launchSettings.json

La herramienta inicia una ventana del explorador con la interfaz de usuario web interactiva. Los servicios gRPC se detectan automáticamente mediante la reflexión gRPC.

Recursos adicionales

• Página principal de GitHub de gRPCurl
• Página principal de GitHub de gRPCui
• Grpc.AspNetCore.Server.Reflection
• Prueba de servicios gRPC en ASP.NET Core
• Simulación del cliente gRPC en pruebas