ASP.NET Core で gRPCurl と gRPCui を使用して gRPC サービスをテストする

作成者: James Newton-King

gRPC 用のツールが用意されており、開発者は、クライアント アプリをビルドせずにサービスをテストできます。

• gRPCurl は、gRPC サービスとのやりとりを可能にするコマンドライン ツールです。
• gRPCui は gRPCurl の上に構築され、gRPC 用のオープンソースの対話型 Web UI を追加します。

この記事では、次の方法について説明します。

• gRPC ASP.NET Core アプリを使用して、gRPC リフレクションを設定します。
• テスト ツールを使用して gRPC とやりとりする:
  • grpcurl を使用して、gRPC サービスの検出とテストを行います。
  • grpcui を使用して、ブラウザー経由で gRPC サービスと対話します。

注意

gRPC サービスの単体テストの方法については、「ASP.NET Core で gRPC サービスをテストする」を参照してください。

gRPC リフレクションの設定

ツールでサービスを呼び出すには、それらの Protobuf コントラクトが認識されている必要があります。 この作業を実行する 2 つの方法があります。

• サーバーで gRPC リフレクション を設定します。 gRPCurl などのツールでは、リフレクションを使用してサービス コントラクトが自動的に検出されます。
• .proto ファイルをツールに手動で追加します。

gRPC リフレクションを使用する方が簡単です。 gRPC リフレクションにより、クライアントがサービスを検出するために呼び出すことができるアプリに新しい gRPC サービスが追加されます。

gRPC ASP.NET Core には、Grpc.AspNetCore.Server.Reflection パッケージとの gRPC リフレクションのサポートが組み込まれています。 アプリでリフレクションを構成するには、次を実行します。

• Grpc.AspNetCore.Server.Reflection パッケージ参照を追加します。
• Program.cs にリフレクションを登録します。
  • AddGrpcReflection でリフレクションを有効にするサービスを登録します。
  • MapGrpcReflectionService を使用して、リフレクション サービス エンドポイントを追加します。

C#

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

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

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

gRPC リフレクションが設定されると、以下が行われます。

• gRPC リフレクション サービスがサーバー アプリに追加されます。
• gRPC リフレクションをサポートするクライアント アプリで、リフレクション サービスを呼び出して、サーバーによってホストされるサービスを検出できます。
• gRPC サービスは引き続きクライアントから呼び出されます。 リフレクションにより、サービス検出のみが有効にされ、サーバー側のセキュリティはバイパスされません。 認証と承認によって保護されるエンドポイントにより、呼び出し側は、エンドポイントが正常に呼び出されるための資格情報を渡す必要があります。

リフレクション サービスのセキュリティ

gRPC リフレクションは、機密情報を含む可能性がある使用可能な API の一覧を返します。 gRPC リフレクション サービスへのアクセスを制限するように、注意する必要があります。

通常 gRPC リフレクションは、ローカル開発環境でのみ必要です。 ローカル開発の場合、リフレクション サービスは、IsDevelopment が true を返す場合にのみマップする必要があります。

C#

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

サービスへのアクセスは、AllowAnonymous や RequireAuthorization などの標準の ASP.NET Core 承認拡張メソッドを使用して制御できます。

たとえば、アプリが既定で承認を要求するように構成されている場合は、gRPC リフレクション エンドポイントに AllowAnonymous を使用して、認証と認可をスキップするように構成します。

C#

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

gRPCurl

gRPCurl は、gRPC コミュニティによって作成されたコマンドライン ツールです。 次のような機能があります。

• ストリーミング サービスを含む、gRPC サービスの呼び出し。
• gRPC リフレクションを使用したサービスの検出。
• gRPC サービスの一覧表示と説明。
• セキュリティで保護されたサーバー (TLS) と安全ではない (プレーンテキスト) サーバーの使用。

grpcurl のダウンロードとインストールの詳細については、gRPCurl GitHub ホームページを参照してください。

grpcurl を使用します

-help 引数では、grpcurl コマンドライン オプションについて説明しています。

コンソール

$ grpcurl -help

サービスの検出

サーバーによって定義されたサービスを表示するには、describe 動詞を使用します。 gRPC サーバーの localhost ポート番号として <port> を指定します。 ポート番号は、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 );
}

上記の例の場合:

• サーバー localhost:<port> で describe Verb を実行します。 <port> は、Properties/launchSettings.json で gRPC サーバー プロジェクトの作成と設定が行われるときにランダムに割り当てられます
• gRPC リフレクションによって返されたサービスとメソッドを出力します。
  • Greeter は、アプリによって実装されるサービスです。
  • ServerReflection は、Grpc.AspNetCore.Server.Reflection パッケージによって追加されたサービスです。

詳細を表示するには、describe をサービス、メソッド、またはメッセージ名と組み合わせます。

PowerShell

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

gRPC サービスの呼び出し

要求メッセージを表す JSON 引数と共にサービス名とメソッド名を指定して、gRPC サービスを呼び出します。 JSON は Protobuf に変換され、サービスに送信されます。

コンソール

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

前の例の場合:

• -d 引数を使用して、JSON を含む要求メッセージを指定します。 この引数は、サーバー アドレスとメソッド名の前で指定する必要があります。
• greeter.Greeter サービスの SayHello メソッドを呼び出します。
• 応答メッセージを JSON として出力します。
• <port> は、Properties/launchSettings.json で gRPC サーバー プロジェクトの作成と設定が行われるときにランダムに割り当てられます

前の例では、\ を使用して " 文字をエスケープしています。 " のエスケープは、PowerShell コンソールでは必要ですが、一部のコンソールでは使用できません。 たとえば、macOS コンソールの場合、上記のコマンドは次のようになります。

コンソール

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

gRPCui

gRPCui は、gRPC の対話型 Web UI です。 gRPCui は gRPCurl の上に構築されています。 gRPCui では、Swagger UI などの HTTP ツールと同様に、gRPC サービスを検出してテストするための GUI が提供されます。

grpcui のダウンロードとインストールの詳細については、gRPCui GitHub ホームページを参照してください。

grpcui の使用

対話するサーバー アドレスを引数に指定して grpcui を実行します。

PowerShell

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

上記の例では、gRPC サーバーの localhost ポート番号として <port> を指定しています。 ポート番号は、Properties/launchSettings.json でプロジェクトの作成と設定が行われるときにランダムに割り当てられます

このツールにより、対話型の Web UI を備えたブラウザー ウィンドウが起動されます。gRPC リフレクションを使用して、gRPC サービスが自動的に検出されます。

その他のリソース

• gRPCurl GitHub ホームページ
• gRPCui GitHub ホームページ
• Grpc.AspNetCore.Server.Reflection
• ASP.NET Core で gRPC サービスをテストする
• テストで gRPC クライアントをモックする