Testowanie usług gRPC za pomocą gRPCurl i gRPCui w ASP.NET Core

Autor: James Newton-King

Narzędzia są dostępne dla gRPC, który umożliwia deweloperom testowanie usług bez kompilowania aplikacji klienckich:

• gRPCurl to narzędzie wiersza polecenia typu open source, które zapewnia interakcję z usługami gRPC.
• gRPCui jest oparta na gRPCurl i dodaje interakcyjny internetowy interfejs użytkownika open source dla gRPC.

W tym artykule opisano, jak:

• Skonfiguruj odbicie serwera gRPC za pomocą aplikacji gRPC ASP.NET Core.
• Interakcja z gRPC przy użyciu narzędzi testowych:
  • Odnajdź i przetestuj usługi gRPC za pomocą polecenia grpcurl.
  • Interakcja z usługami gRPC za pośrednictwem przeglądarki przy użyciu polecenia grpcui.

Uwaga

Aby dowiedzieć się, jak testować usługi gRPC, zobacz Testowanie usług gRPC w programie ASP.NET Core.

Konfigurowanie odbicia gRPC

Narzędzia muszą znać umowę Protobuf usług, zanim będzie można je wywołać. Istnieją dwa sposoby wykonania tej czynności:

• Skonfiguruj odbicie gRPC na serwerze. Narzędzia, takie jak gRPCurl, używają odbicia w celu automatycznego odnajdywania kontraktów usług.
• Ręczne dodawanie .proto plików do narzędzia.

Łatwiej jest używać odbicia gRPC. Odbicie gRPC dodaje nową usługę gRPC do aplikacji, którą klienci mogą wywołać w celu odnajdywania usług.

gRPC ASP.NET Core ma wbudowaną obsługę odbicia gRPC z pakietem Grpc.AspNetCore.Server.Reflection . Aby skonfigurować odbicie w aplikacji:

• Dodaj odwołanie do Grpc.AspNetCore.Server.Reflection pakietu.
• Zarejestruj odbicie w pliku Program.cs:
  • AddGrpcReflection do rejestrowania usług, które umożliwiają odbicie.
  • MapGrpcReflectionService aby dodać punkt końcowy usługi odbicia.

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

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

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

Po skonfigurowaniu odbicia gRPC:

• Usługa odbicia gRPC jest dodawana do aplikacji serwera.
• Aplikacje klienckie obsługujące odbicie gRPC mogą wywoływać usługę odbicia w celu odnajdywania usług hostowanych przez serwer.
• Usługi gRPC są nadal wywoływane z klienta. Odbicie włącza tylko odnajdywanie usługi i nie pomija zabezpieczeń po stronie serwera. Punkty końcowe chronione przez uwierzytelnianie i autoryzację wymagają, aby obiekt wywołujący pomyślnie przekazał poświadczenia punktu końcowego.

Zabezpieczenia usługi odbicia

Odbicie gRPC zwraca listę dostępnych interfejsów API, które mogą zawierać poufne informacje. Należy zadbać o ograniczenie dostępu do usługi odbicia gRPC.

Odbicie gRPC jest zwykle wymagane tylko w lokalnym środowisku projektowym. W przypadku programowania lokalnego usługa odbicia powinna być mapowana tylko wtedy, gdy funkcja IsDevelopment zwraca wartość true:

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

Dostęp do usługi można kontrolować za pomocą standardowych metod rozszerzenia autoryzacji ASP.NET Core, takich jak AllowAnonymous i RequireAuthorization.

Jeśli na przykład aplikacja została skonfigurowana tak, aby domyślnie wymagała autoryzacji, skonfiguruj punkt końcowy odbicia gRPC, AllowAnonymous aby pominąć uwierzytelnianie i autoryzację.

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

gRPCurl

gRPCurl to narzędzie wiersza polecenia utworzone przez społeczność gRPC. Jego funkcje obejmują:

• Wywoływanie usług gRPC, w tym usług przesyłania strumieniowego.
• Odnajdywanie usługi przy użyciu odbicia gRPC.
• Wyświetlanie listy i opisywanie usług gRPC.
• Działa z bezpiecznymi (TLS) i niezabezpieczonymi serwerami (zwykły tekst).

Aby uzyskać informacje na temat pobierania i instalowania grpcurlprogramu , zobacz stronę główną usługi GitHub gRPCurl.

Korzystanie z polecenia grpcurl

Argument -help wyjaśnia grpcurl opcje wiersza polecenia:

$ grpcurl -help

Odnajdywanie usług

Użyj czasownika describe , aby wyświetlić usługi zdefiniowane przez serwer. Określ <port> jako numer portu hosta lokalnego serwera gRPC. Numer portu jest losowo przypisywany podczas tworzenia projektu i ustawiany w elemecie 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 );
}

Powyższy przykład:

• describe Uruchamia zlecenie na serwerze localhost:<port>. Gdzie <port> jest losowo przypisywany, gdy projekt serwera gRPC jest tworzony i ustawiany w Properties/launchSettings.json
• Drukuje usługi i metody zwracane przez odbicie gRPC.
  • Greeter to usługa zaimplementowana przez aplikację.
  • ServerReflection jest usługą dodaną Grpc.AspNetCore.Server.Reflection przez pakiet.

Połącz describe z usługą, metodą lub nazwą komunikatu, aby wyświetlić jego szczegóły:

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

Wywoływanie usług gRPC

Wywołaj usługę gRPC, określając nazwę usługi i metody wraz z argumentem JSON reprezentującym komunikat żądania. Kod JSON jest konwertowany na protobuf i wysyłany do usługi.

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

W powyższym przykładzie:

• Argument -d określa komunikat żądania z plikiem JSON. Ten argument musi pochodzić przed adresem serwera i nazwą metody.
• Wywołuje metodę SayHello w usłudze greeter.Greeter .
• Wyświetla komunikat odpowiedzi w formacie JSON.
• Gdzie <port> jest losowo przypisywany, gdy projekt serwera gRPC jest tworzony i ustawiany w Properties/launchSettings.json

W poprzednim przykładzie użyto metody \ w celu ucieczki " znaku. Ucieczka jest wymagana " w konsoli programu PowerShell, ale nie może być używana w niektórych konsolach. Na przykład poprzednie polecenie dla konsoli systemu macOS:

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

gRPCui

gRPCui to interaktywny internetowy interfejs użytkownika gRPC. gRPCui opiera się na gRPCurl. gRPCui oferuje graficzny interfejs użytkownika do odnajdywania i testowania usług gRPC, podobnie jak narzędzia HTTP, takie jak Swagger UI.

Aby uzyskać informacje na temat pobierania i instalowania grpcuiprogramu , zobacz stronę główną usługi GitHub gRPCui.

Korzystanie z akcji grpcui

Uruchom polecenie grpcui z adresem serwera, aby wchodzić w interakcję z argumentem:

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

W poprzednim przykładzie określ <port> jako numer portu hosta lokalnego serwera gRPC. Numer portu jest losowo przypisywany podczas tworzenia i ustawiania projektu w Properties/launchSettings.json

Narzędzie uruchamia okno przeglądarki za pomocą interaktywnego internetowego interfejsu użytkownika. Usługi gRPC są automatycznie odnajdywane przy użyciu odbicia gRPC.

Dodatkowe zasoby

• gRPCurl Strona główna usługi GitHub
• strona główna usługi GitHub gRPCui
• Grpc.AspNetCore.Server.Reflection
• Testowanie usług gRPC w ASP.NET Core
• Pozorowanie klienta gRPC w testach