基本チュートリアル
gRPC-webの基本チュートリアルを紹介します。
基本チュートリアル
このチュートリアルでは、ブラウザからgRPC-Webを使用する方法の基本を紹介します。
この例を進めることで、以下の方法を学びます。
- .protoファイルでサービスを定義する。
- プロトコルバッファコンパイラを使用してクライアントコードを生成する。
- gRPC-Web APIを使用して、サービス用の単純なクライアントを作成する。
プロトコルバッファについての基本的な知識があることを前提としています。
gRPCとgRPC-Webを使用する理由
gRPCを使用すると、.protoファイルでサービスを一度定義し、gRPCがサポートする任意の言語でクライアントとサーバーを実装できます。それらは、大規模なデータセンター内のサーバーから自分のタブレットまで、さまざまな環境で実行できます。異なる言語と環境間の通信の複雑さはすべて、gRPCによって処理されます。また、効率的なシリアル化、シンプルなIDL、簡単なインターフェース更新など、プロトコルバッファを使用するすべての利点も得られます。gRPC-Webを使用すると、ブラウザからこの方法で構築されたgRPCサービスに、慣用的なAPIを使用してアクセスできます。
サービスを定義する
gRPCサービスを作成する最初のステップは、プロトコルバッファを使用してサービスメソッドとそれらのリクエストおよびレスポンスメッセージタイプを定義することです。この例では、echo.protoというファイルでEchoServiceを定義します。プロトコルバッファとproto3構文の詳細については、protobufドキュメントを参照してください。
message EchoRequest {
string message = 1;
}
message EchoResponse {
string message = 1;
}
service EchoService {
rpc Echo(EchoRequest) returns (EchoResponse);
}
gRPCバックエンドサーバーを実装する
次に、バックエンドのgRPC EchoServerでNodeを使用してEchoServiceインターフェースを実装します。これはクライアントからのリクエストを処理します。詳細については、node-server/server.jsファイルを参照してください。
サーバーはgRPCでサポートされている任意の言語で実装できます。詳細については、メインページを参照してください。
function doEcho(call, callback) {
callback(null, {message: call.request.message});
}
Envoyプロキシを構成する
この例では、Envoyプロキシを使用して、gRPCブラウザのリクエストをバックエンドサーバーに転送します。完全な構成ファイルは、envoy.yamlで確認できます。
gRPCリクエストをバックエンドサーバーに転送するには、次のようなブロックが必要です
admin:
address:
socket_address: { address: 0.0.0.0, port_value: 9901 }
static_resources:
listeners:
- name: listener_0
address:
socket_address: { address: 0.0.0.0, port_value: 8080 }
filter_chains:
- filters:
- name: envoy.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
codec_type: auto
stat_prefix: ingress_http
route_config:
name: local_route
virtual_hosts:
- name: local_service
domains: ["*"]
routes:
- match: { prefix: "/" }
route: { cluster: echo_service }
http_filters:
- name: envoy.grpc_web
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
clusters:
- name: echo_service
connect_timeout: 0.25s
type: LOGICAL_DNS
typed_extension_protocol_options:
envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
"@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
explicit_http_config:
http2_protocol_options: {}
lb_policy: ROUND_ROBIN
load_assignment:
cluster_name: echo_service
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: node-server
port_value: 9090
ブラウザがクロスオリジンコンテンツをリクエストできるように、CORS設定を追加する必要がある場合もあります。
この簡単な例では、ブラウザはポート:8080にgRPCリクエストを行います。Envoyは、ポート:9090でリッスンしているバックエンドgRPCサーバーにリクエストを転送します。
Protobufメッセージとサービスクライアントスタブを生成する
echo.protoからprotobufメッセージクラスを生成するには、次のコマンドを実行します。
$ protoc -I=$DIR echo.proto \
--js_out=import_style=commonjs:$OUT_DIR
--js_outフラグに渡されるimport_styleオプションは、生成されたファイルにCommonJSスタイルのrequire()ステートメントがあることを確認します。
gRPC-Webサービスクライアントスタブを生成するには、最初にgRPC-Web protocプラグインが必要です。プラグインprotoc-gen-grpc-webをコンパイルするには、リポジトリのルートディレクトリからこれを実行する必要があります
$ cd grpc-web
$ sudo make install-plugin
サービスクライアントスタブファイルを生成するには、次のコマンドを実行します
$ protoc -I=$DIR echo.proto \
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR
上記の--grpc-web_outパラメーターで
modeは、grpcwebtext（デフォルト）またはgrpcwebにすることができますimport_styleは、closure（デフォルト）またはcommonjsにすることができます
コマンドは、デフォルトで、echo_grpc_web_pb.jsファイルにクライアントスタブを生成します。
JSクライアントコードを作成する
これで、JSクライアントコードを作成する準備ができました。これをclient.jsファイルに配置します。
const {EchoRequest, EchoResponse} = require('./echo_pb.js');
const {EchoServiceClient} = require('./echo_grpc_web_pb.js');
var echoService = new EchoServiceClient('http://localhost:8080');
var request = new EchoRequest();
request.setMessage('Hello World!');
echoService.echo(request, {}, function(err, response) {
// ...
});
package.jsonファイルが必要です
{
"name": "grpc-web-commonjs-example",
"dependencies": {
"google-protobuf": "^3.6.1",
"grpc-web": "^0.4.0"
},
"devDependencies": {
"browserify": "^16.2.2",
"webpack": "^4.16.5",
"webpack-cli": "^3.1.0"
}
}
JSライブラリをコンパイルする
最後に、これらをすべてまとめて、関連するすべてのJSファイルを、ブラウザで使用できる1つのJSライブラリにコンパイルできます。
$ npm install
$ npx webpack client.js
次に、dist/main.jsをプロジェクトに埋め込んで、実際に動作を確認してください！