Tester les services gRPC avec gRPCurl et gRPCui dans ASP.NET Core

Par James Newton-King

Les outils disponibles pour gRPC permettent aux développeurs de tester des services sans créer d’applications clientes :

• gRPCurl est un outil en ligne de commande open source qui fournit une interaction avec les services gRPC.
• gRPCui s’appuie sur gRPCurl et ajoute une interface utilisateur web interactive open source pour gRPC.

Cet article explique comment :

• Configurer la réflexion du serveur gRPC avec une application ASP.NET Core gRPC.
• Interagir avec gRPC à l’aide des outils de test :
  • Découvrir et tester les services gRPC avec grpcurl.
  • Interagir avec les services gRPC via un navigateur à l’aide de grpcui.

Notes

Pour savoir comment effectuer un test unitaire des services gRPC, consultez Tester les services gRPC dans ASP.NET Core.

Configurer la réflexion gRPC

Les outils doivent connaître le contrat de services Protobuf pour que celui-ci puisse les appeler. Il existe deux façons d'effectuer cette opération :

• Configurez la réflexion gRPC sur le serveur. Les outils, par exemple gRPCurl, utilisent la réflexion pour découvrir automatiquement les contrats de service.
• Ajoutez manuellement les fichiers .proto à l’outil.

Il est plus facile d’utiliser la réflexion gRPC. La réflexion gRPC ajoute un nouveau service gRPC à l’application que les clients peuvent appeler pour découvrir les services.

ASP.NET Core gRPC dispose de la prise en charge intégrée de la réflexion gRPC avec le package Grpc.AspNetCore.Server.Reflection. Pour configurer la réflexion dans une application :

• Ajoutez une référence de package Grpc.AspNetCore.Server.Reflection.
• Inscrivez la réflexion dans Program.cs :
  • AddGrpcReflection pour inscrire les services qui permettent la réflexion.
  • MapGrpcReflectionService pour ajouter un point de terminaison de service de réflexion.

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

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

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

Quand la réflexion gRPC est configurée :

• Un service de réflexion gRPC est ajouté à l’application serveur.
• Les applications clientes qui prennent en charge la réflexion gRPC peuvent appeler le service de réflexion pour découvrir les services hébergés par le serveur.
• Les services gRPC sont encore appelés à partir du client. La réflexion active uniquement la découverte du service et ne contourne pas la sécurité côté serveur. Les points de terminaison protégés par l’authentification et l’autorisation nécessitent que l’appelant transmette des informations d’identification pour que le point de terminaison soit appelé correctement.

Sécurité du service de réflexion

La réflexion gRPC retourne une liste d’API disponibles, qui peuvent contenir des informations sensibles. Veillez à limiter l’accès au service de réflexion gRPC.

La réflexion gRPC est généralement nécessaire uniquement dans un environnement de développement local. Pour le développement local, le service de réflexion ne doit être mappé que lorsque IsDevelopment retourne la valeur true :

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

L’accès au service peut être contrôlé via des méthodes d’extension d’autorisation standard ASP.NET Core, telles que AllowAnonymous et RequireAuthorization.

Par exemple, si une application a été configurée pour exiger une autorisation par défaut, configurez le point de terminaison de réflexion gRPC avec AllowAnonymous pour ignorer l’authentification et l’autorisation.

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

gRPCurl

gRPCurl est un outil en ligne de commande créé par la communauté gRPC. Ses fonctionnalités sont les suivantes :

• Appel de services gRPC, y compris les services de streaming.
• Découverte de service à l’aide de la réflexion gRPC.
• Liste et description des services gRPC.
• Fonctionnement avec des serveurs sécurisés (TLS) et non sécurisés (texte brut).

Pour obtenir des informations sur le téléchargement et l’installation de grpcurl, consultez la page d’accueil GitHub de gRPCurl.

Utilisez grpcurl.

L’argument -help explique les options de ligne de commande grpcurl :

$ grpcurl -help

Découvrir les services

Utilisez le verbe describe pour afficher les services définis par le serveur. Spécifiez <port> comme numéro de port localhost du serveur gRPC. Le numéro de port est attribué de manière aléatoire quand le projet est créé et défini dans 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 );
}

L’exemple précédent :

• Exécute le verbe describe sur le serveur localhost:<port>. Où <port> est attribué de manière aléatoire lorsque le projet de serveur gRPC est créé et défini dans Properties/launchSettings.json
• Imprime les services et les méthodes retournés par la réflexion gRPC.
  • Greeter est un service implémenté par l’application.
  • ServerReflection est le service ajouté par le package Grpc.AspNetCore.Server.Reflection.

Combinez describe avec un service, une méthode ou un nom de message pour afficher ses détails :

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

Appeler les services gRPC

Appelez un service gRPC en spécifiant un nom de service et de méthode ainsi qu’un argument JSON qui représente le message de demande. Le code JSON est converti dans Protobuf et envoyé au service.

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

Dans l'exemple précédent :

• L’argument -d spécifie un message de demande avec JSON. Cet argument doit précéder l’adresse du serveur et le nom de la méthode.
• Appelle la méthode SayHello sur le service greeter.Greeter.
• Affiche le message de réponse en tant que JSON.
• Où <port> est attribué de manière aléatoire lorsque le projet de serveur gRPC est créé et défini dans Properties/launchSettings.json

L’exemple précédent utilise \ pour échapper le caractère ". L’échappement de " est obligatoire dans une console PowerShell, mais ne doit pas être utilisé dans certaines consoles. Par exemple, la commande précédente pour une console macOS :

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

gRPCui

gRPCui est une interface utilisateur web interactive pour gRPC. gRPCui s’appuie sur gRPCurl. gRPCui offre une interface GUI pour la découverte et le test des services gRPC, à l’image des outils HTTP tels que l’IU de Swagger.

Pour obtenir des informations sur le téléchargement et l’installation de grpcui, consultez la page d’accueil GitHub de gRPCui.

Utilisation de grpcui

Exécutez grpcui avec l’adresse du serveur avec laquelle interagir en tant qu’argument :

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

Dans l’exemple précédent, spécifiez <port> comme numéro de port localhost du serveur gRPC. Le numéro de port est attribué de manière aléatoire quand le projet est créé et défini dans Properties/launchSettings.json

L’outil lance une fenêtre de navigateur avec l’interface utilisateur web interactive. Les services gRPC sont découverts automatiquement à l’aide de la réflexion gRPC.

Ressources supplémentaires

• Page d’accueil GitHub de gRPCurl
• Page d’accueil GitHub de gRPCui
• Grpc.AspNetCore.Server.Reflection
• Tester les services gRPC dans ASP.NET Core
• Simuler un client gRPC dans les tests