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 サービスと対話します。
Note
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
を使用して、リフレクション サービス エンドポイントを追加します。
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 サービスは引き続きクライアントから呼び出されます。 リフレクションにより、サービス検出のみが有効にされ、サーバー側のセキュリティはバイパスされません。 認証と承認によって保護されるエンドポイントにより、呼び出し側は、エンドポイントが正常に呼び出されるための資格情報を渡す必要があります。
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
をサービス、メソッド、またはメッセージ名と組み合わせます。
$ 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
を実行します。
$ grpcui localhost:<port>
gRPC Web UI available at http://127.0.0.1:55038/
上記の例では、gRPC サーバーの localhost ポート番号として <port>
を指定しています。 ポート番号は、Properties/launchSettings.json
でプロジェクトの作成と設定が行われるときにランダムに割り当てられます
このツールにより、対話型の Web UI を備えたブラウザー ウィンドウが起動されます。gRPC リフレクションを使用して、gRPC サービスが自動的に検出されます。
その他のリソース
gRPC 用のツールが用意されており、開発者は、クライアント アプリをビルドせずにサービスをテストできます。
- gRPCurl は、gRPC サービスとのやりとりを可能にするコマンドライン ツールです。
- gRPCui は gRPCurl の上に構築され、gRPC 用のオープンソースの対話型 Web UI を追加します。
この記事では、次の方法について説明します。
- gRPC ASP.NET Core アプリを使用して、gRPC リフレクションを設定します。
- テスト ツールを使用して gRPC とやりとりする:
grpcurl
を使用して、gRPC サービスの検出とテストを行います。grpcui
を使用して、ブラウザー経由で gRPC サービスと対話します。
Note
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
パッケージ参照を追加します。Startup.cs
にリフレクションを登録します。AddGrpcReflection
でリフレクションを有効にするサービスを登録します。MapGrpcReflectionService
を使用して、リフレクション サービス エンドポイントを追加します。
public void ConfigureServices(IServiceCollection services)
{
services.AddGrpc();
services.AddGrpcReflection();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapGrpcService<GreeterService>();
if (env.IsDevelopment())
{
endpoints.MapGrpcReflectionService();
}
});
}
gRPC リフレクションが設定されると、以下が行われます。
- gRPC リフレクション サービスがサーバー アプリに追加されます。
- gRPC リフレクションをサポートするクライアント アプリで、リフレクション サービスを呼び出して、サーバーによってホストされるサービスを検出できます。
- gRPC サービスは引き続きクライアントから呼び出されます。 リフレクションにより、サービス検出のみが有効にされ、サーバー側のセキュリティはバイパスされません。 認証と承認によって保護されるエンドポイントにより、呼び出し側は、エンドポイントが正常に呼び出されるための資格情報を渡す必要があります。
gRPCurl
gRPCurl は、gRPC コミュニティによって作成されたコマンドライン ツールです。 次のような機能があります。
- ストリーミング サービスを含む、gRPC サービスの呼び出し。
- gRPC リフレクションを使用したサービスの検出。
- gRPC サービスの一覧表示と説明。
- セキュリティで保護されたサーバー (TLS) と安全ではない (プレーンテキスト) サーバーの使用。
grpcurl
のダウンロードとインストールの詳細については、gRPCurl GitHub ホームページを参照してください。
grpcurl
を使用します
-help
引数では、grpcurl
コマンドライン オプションについて説明しています。
$ grpcurl -help
サービスの検出
サーバーによって定義されたサービスを表示するには、describe
動詞を使用します。
$ grpcurl localhost:5001 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:5001
でdescribe
Verb を実行します。 - gRPC リフレクションによって返されたサービスとメソッドを出力します。
Greeter
は、アプリによって実装されるサービスです。ServerReflection
は、Grpc.AspNetCore.Server.Reflection
パッケージによって追加されたサービスです。
詳細を表示するには、describe
をサービス、メソッド、またはメッセージ名と組み合わせます。
$ grpcurl localhost:5001 describe greet.HelloRequest
greet.HelloRequest is a message:
message HelloRequest {
string name = 1;
}
gRPC サービスの呼び出し
要求メッセージを表す JSON 引数と共にサービス名とメソッド名を指定して、gRPC サービスを呼び出します。 JSON は Protobuf に変換され、サービスに送信されます。
$ grpcurl -d '{ \"name\": \"World\" }' localhost:5001 greet.Greeter/SayHello
{
"message": "Hello World"
}
前の例の場合:
-d
引数を使用して、JSON を含む要求メッセージを指定します。 この引数は、サーバー アドレスとメソッド名の前で指定する必要があります。greeter.Greeter
サービスのSayHello
メソッドを呼び出します。- 応答メッセージを JSON として出力します。
前の例では、\
を使用して "
文字をエスケープしています。 "
のエスケープは、PowerShell コンソールでは必要ですが、一部のコンソールでは使用できません。 たとえば、macOS コンソールの場合、上記のコマンドは次のようになります。
$ grpcurl -d '{ "name": "World" }' localhost:5001 greet.Greeter/SayHello
{
"message": "Hello World"
}
gRPCui
gRPCui は、gRPC の対話型 Web UI です。 gRPCui は gRPCurl の上に構築されています。 gRPCui では、Swagger UI などの HTTP ツールと同様に、gRPC サービスを検出してテストするための GUI が提供されます。
grpcui
のダウンロードとインストールの詳細については、gRPCui GitHub ホームページを参照してください。
grpcui
の使用
対話するサーバー アドレスを引数に指定して grpcui
を実行します。
$ grpcui localhost:5001
gRPC Web UI available at http://127.0.0.1:55038/
このツールにより、対話型の Web UI を備えたブラウザー ウィンドウが起動されます。gRPC リフレクションを使用して、gRPC サービスが自動的に検出されます。
その他のリソース
ASP.NET Core
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示