Testování služeb gRPC pomocí gRPCurl a gRPCui v ASP.NET Core

Autor: James Newton-King

Nástroje jsou k dispozici pro gRPC, které vývojářům umožňují testovat služby bez vytváření klientských aplikací:

• gRPCurl je opensourcový nástroj příkazového řádku, který poskytuje interakci se službami gRPC.
• gRPCui vychází z gRPCurl a přidá opensourcové interaktivní webové uživatelské rozhraní pro gRPC.

Tento článek popisuje, jak:

• Nastavení reflexe serveru gRPC pomocí aplikace gRPC ASP.NET Core
• Interakce s gRPC pomocí testovacích nástrojů:
  • Zjišťování a testování služeb gRPC pomocí grpcurlnástroje .
  • Interakce se službami gRPC prostřednictvím prohlížeče pomocí grpcui.

Poznámka:

Informace o tom, jak testovat služby gRPC jednotek, najdete v tématu Testování služeb gRPC v ASP.NET Core.

Nastavení reflexe gRPC

Nástroje musí znát smlouvu Protobuf o službách, aby je mohly volat. Toto lze provést dvěma způsoby:

• Nastavte odraz gRPC na serveru. Nástroje, jako je například gRPCurl, používají reflexi k automatickému zjišťování kontraktů služeb.
• Přidejte .proto soubory do nástroje ručně.

Je jednodušší použít reflexi gRPC. Reflexe gRPC přidá do aplikace novou službu gRPC, kterou můžou klienti volat ke zjišťování služeb.

gRPC ASP.NET Core má integrovanou podporu reflexe gRPC s balíčkem Grpc.AspNetCore.Server.Reflection . Konfigurace reflexe v aplikaci:

• Přidejte odkaz na Grpc.AspNetCore.Server.Reflection balíček.
• Zaregistrovat reflexi v Program.cs:
  • AddGrpcReflection k registraci služeb, které umožňují reflexi.
  • MapGrpcReflectionService přidání koncového bodu služby reflexe.

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

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

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

Při nastavení reflexe gRPC:

• Do serverové aplikace se přidá služba reflexe gRPC.
• Klientské aplikace, které podporují reflexi gRPC, mohou volat službu reflexe ke zjišťování služeb hostovaných serverem.
• Služby gRPC se stále volají z klienta. Reflexe umožňuje pouze zjišťování služeb a neobejde zabezpečení na straně serveru. Koncové body chráněné ověřováním a autorizací vyžadují, aby volající předal přihlašovací údaje pro úspěšné volání koncového bodu.

Zabezpečení služby Reflexe

Reflexe gRPC vrátí seznam dostupných rozhraní API, která můžou obsahovat citlivé informace. Je třeba věnovat pozornost omezení přístupu ke službě reflexe gRPC.

Reflexe gRPC se obvykle vyžaduje jenom v místním vývojovém prostředí. Pro místní vývoj by se služba reflexe měla mapovat pouze v případě, že IsDevelopment vrátí hodnotu true:

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

Přístup ke službě lze řídit standardními metodami rozšíření autorizace ASP.NET Core, jako AllowAnonymous je například a RequireAuthorization.

Pokud je například aplikace nakonfigurovaná tak, aby ve výchozím nastavení vyžadovala autorizaci, nakonfigurujte koncový bod reflexe gRPC tak AllowAnonymous , aby přeskočil ověřování a autorizaci.

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

gRPCurl

gRPCurl je nástroj příkazového řádku vytvořený komunitou gRPC. Mezi její funkce patří:

• Volání služeb gRPC, včetně streamovacích služeb
• Zjišťování služeb pomocí reflexe gRPC
• Výpis a popis služeb gRPC
• Funguje se zabezpečenými servery (TLS) a nezabezpečenými servery (prostý text).

Informace o stahování a instalaci grpcurlnajdete na domovské stránce GitHubu gRPCurl.

Použití grpcurl

Argument -help vysvětluje grpcurl možnosti příkazového řádku:

$ grpcurl -help

Zjišťování služeb

describe Příkaz použijte k zobrazení služeb definovaných serverem. Zadejte <port> jako číslo portu localhost serveru gRPC. Číslo portu je náhodně přiřazeno při vytvoření projektu a nastavení v 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 );
}

Předchozí příklad:

• describe Spustí příkaz na serveru localhost:<port>. Kde <port> je náhodně přiřazen při vytvoření a nastavení projektu serveru gRPC Properties/launchSettings.json
• Vytiskne služby a metody vrácené reflexí gRPC.
  • Greeter je služba implementovaná aplikací.
  • ServerReflection je služba přidaná balíčkem Grpc.AspNetCore.Server.Reflection .

Zkombinujte describe s názvem služby, metody nebo zprávy a zobrazte jeho podrobnosti:

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

Volání služeb gRPC

Volání služby gRPC zadáním názvu služby a metody spolu s argumentem JSON, který představuje zprávu požadavku. JSON se převede na Protobuf a odešle se do služby.

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

V předchozím příkladu:

• Argument -d určuje zprávu požadavku s JSON. Tento argument musí být před názvem adresy serveru a metody.
• Volá metodu SayHello ve službě greeter.Greeter .
• Vytiskne zprávu odpovědi jako JSON.
• Kde <port> je náhodně přiřazen při vytvoření a nastavení projektu serveru gRPC Properties/launchSettings.json

Předchozí příklad používá \ k řídicímu znaku " . Escaping " se vyžaduje v konzole PowerShellu, ale v některých konzolách se nesmí používat. Například předchozí příkaz pro konzolu macOS:

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

gRPCui

gRPCui je interaktivní webové uživatelské rozhraní pro gRPC. gRPCui vychází z gRPCurl. gRPCui nabízí grafické uživatelské rozhraní pro zjišťování a testování služeb gRPC, podobně jako nástroje HTTP, jako je Swagger UI.

Informace o stahování a instalaci grpcuinajdete na domovské stránce githubu gRPCui.

Používání akce grpcui

Spusťte grpcui s adresou serveru, se kterou chcete pracovat jako argument:

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

V předchozím příkladu zadejte <port> jako číslo portu localhost serveru gRPC. Číslo portu se náhodně přiřadí při vytvoření a nastavení projektu v Properties/launchSettings.json

Nástroj spustí okno prohlížeče s interaktivním webovým uživatelským rozhraním. Služby gRPC se automaticky zjistí pomocí reflexe gRPC.

Další materiály

• Domovská stránka GitHubu gRPCurl
• Domovská stránka GitHubu gRPCui
• Grpc.AspNetCore.Server.Reflection
• Testování služeb gRPC v ASP.NET Core
• Napodobení klienta gRPC v testech