Testare i servizi gRPC con gRPCurl e gRPCui in ASP.NET Core

Di James Newton-King

Gli strumenti sono disponibili per gRPC che consente agli sviluppatori di testare i servizi senza compilare app client:

• gRPCurl è uno strumento da riga di comando open source che fornisce l'interazione con i servizi gRPC.
• gRPCui si basa su gRPCurl e aggiunge un'interfaccia utente Web interattiva open source per gRPC.

Questo articolo illustra come:

• Configurare la reflection del server gRPC con un'app gRPC ASP.NET Core.
• Interagire con gRPC usando gli strumenti di test:
  • Individuare e testare i servizi gRPC con grpcurl.
  • Interagire con i servizi gRPC tramite un browser usando grpcui.

Nota

Per informazioni su come eseguire unit test dei servizi gRPC, vedere Testare i servizi gRPC in ASP.NET Core.

Configurare la reflection gRPC

Gli strumenti devono conoscere il contratto Protobuf dei servizi prima di poterli chiamare. A questo scopo è possibile procedere in due modi:

• Configurare la reflection gRPC nel server. Gli strumenti, ad esempio gRPCurl, usano la reflection per individuare automaticamente i contratti di servizio.
• Aggiungere .proto file allo strumento manualmente.

È più facile usare la reflection gRPC. La reflection gRPC aggiunge un nuovo servizio gRPC all'app che i client possono chiamare per individuare i servizi.

gRPC ASP.NET Core include il supporto predefinito per la reflection gRPC con il Grpc.AspNetCore.Server.Reflection pacchetto. Per configurare la reflection in un'app:

• Aggiungere un riferimento al Grpc.AspNetCore.Server.Reflection pacchetto.
• Registrare la reflection in Program.cs:
  • AddGrpcReflection per registrare i servizi che abilitano la reflection.
  • MapGrpcReflectionService per aggiungere un endpoint del servizio reflection.

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

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

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

Quando viene configurata la reflection gRPC:

• Un servizio di reflection gRPC viene aggiunto all'app server.
• Le app client che supportano la reflection gRPC possono chiamare il servizio reflection per individuare i servizi ospitati dal server.
• I servizi gRPC vengono comunque chiamati dal client. La reflection abilita solo l'individuazione dei servizi e non ignora la sicurezza lato server. Gli endpoint protetti dall'autenticazione e dall'autorizzazione richiedono al chiamante di passare le credenziali affinché l'endpoint venga chiamato correttamente.

Sicurezza del servizio Reflection

La reflection gRPC restituisce un elenco di API disponibili, che potrebbero contenere informazioni riservate. Prestare attenzione a limitare l'accesso al servizio di reflection gRPC.

La reflection gRPC è in genere necessaria solo in un ambiente di sviluppo locale. Per lo sviluppo locale, il servizio reflection deve essere mappato solo quando IsDevelopment restituisce true:

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

L'accesso al servizio può essere controllato tramite metodi standard ASP.NET di estensione dell'autorizzazione Core, ad esempio AllowAnonymous e RequireAuthorization.

Ad esempio, se un'app è stata configurata per richiedere l'autorizzazione per impostazione predefinita, configurare l'endpoint di reflection gRPC con AllowAnonymous per ignorare l'autenticazione e l'autorizzazione.

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

gRPCurl

gRPCurl è uno strumento da riga di comando creato dalla community gRPC. Sono incluse le funzionalità seguenti:

• Chiamata di servizi gRPC, inclusi i servizi di streaming.
• Individuazione dei servizi tramite reflection gRPC.
• Elencare e descrivere i servizi gRPC.
• Funziona con server sicuri (TLS) e non sicuri (testo normale).

Per informazioni sul download e l'installazione grpcurldi , vedere la home page di GitHub gRPCurl.

Utilizzare grpcurl.

L'argomento -help illustra le grpcurl opzioni della riga di comando:

$ grpcurl -help

Individuare i servizi

Usare il describe verbo per visualizzare i servizi definiti dal server. Specificare <port> come numero di porta localhost del server gRPC. Il numero di porta viene assegnato in modo casuale quando il progetto viene creato e impostato in 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'esempio precedente:

• Esegue il describe verbo nel server localhost:<port>. Dove <port> viene assegnato in modo casuale quando viene creato e impostato il progetto del server gRPC Properties/launchSettings.json
• Stampa i servizi e i metodi restituiti dalla reflection gRPC.
  • Greeter è un servizio implementato dall'app.
  • ServerReflection è il servizio aggiunto dal Grpc.AspNetCore.Server.Reflection pacchetto.

Combinare describe con un servizio, un metodo o un nome di messaggio per visualizzarne i dettagli:

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

Chiamare i servizi gRPC

Chiamare un servizio gRPC specificando un servizio e un nome di metodo insieme a un argomento JSON che rappresenta il messaggio di richiesta. Il codice JSON viene convertito in Protobuf e inviato al servizio.

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

Nell'esempio precedente:

• L'argomento -d specifica un messaggio di richiesta con JSON. Questo argomento deve precedere l'indirizzo del server e il nome del metodo.
• Chiama il SayHello metodo nel greeter.Greeter servizio.
• Stampa il messaggio di risposta come JSON.
• Dove <port> viene assegnato in modo casuale quando viene creato e impostato il progetto del server gRPC Properties/launchSettings.json

Nell'esempio precedente viene \ utilizzato per eseguire l'escape del " carattere . L'escape " è necessario in una console di PowerShell, ma non deve essere usato in alcune console. Ad esempio, il comando precedente per una console macOS:

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

gRPCui

gRPCui è un'interfaccia utente Web interattiva per gRPC. gRPCui si basa su gRPCurl. gRPCui offre un'interfaccia utente grafica per l'individuazione e il test di servizi gRPC, simili a strumenti HTTP come L'interfaccia utente di Swagger.

Per informazioni sul download e l'installazione grpcuidi , vedere la home page di GitHub gRPCui.

uso di grpcui

Eseguire grpcui con l'indirizzo del server per interagire con come argomento:

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

Nell'esempio precedente specificare <port> come numero di porta localhost del server gRPC. Il numero di porta viene assegnato in modo casuale quando il progetto viene creato e impostato in Properties/launchSettings.json

Lo strumento avvia una finestra del browser con l'interfaccia utente Web interattiva. I servizi gRPC vengono individuati automaticamente usando la reflection gRPC.

Risorse aggiuntive

• home page di GitHub gRPCurl
• home page di GitHub gRPCui
• Grpc.AspNetCore.Server.Reflection
• Testare i servizi gRPC in ASP.NET Core
• Simulare il client gRPC nei test