基本チュートリアル
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バックエンドサーバーを実装する
次に、バックエンドgRPCEchoServerで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('https://: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ライブラリをコンパイルする
最後に、これらすべてをまとめて、ブラウザで使用できる1つのJSライブラリにコンパイルできます。
npm install
npx webpack client.js
次に、dist/main.jsをプロジェクトに埋め込んで、実際に動作する様子を確認してください！