2.13.5 gRPCアダプタの機能
gRPCアダプタは,gRPCで作成されたサービスにメッセージを送信するためのサービスアダプタです。gRPCアダプタがサポートするgRPC電文フォーマットは,proto3以上です。proto2以前の電文フォーマットはサポートしません。
また,gRPCアダプタを使用するには,OSSのインストールが必要です。必要なOSSについては,「2.13.1(1) gRPCプロトコルを利用した接続に必要なOSS」を参照してください。
gRPCアダプタには,次の機能があります。
-
サーバ呼び出し機能
gRPCサーバと通信を行い,gRPCサービスにメッセージを送受信します。リクエスト処理の延長でgRPCサーバと接続するため,gRPCアダプタの起動時に接続先のgRPCサーバを起動しておく必要がありません。gRPCアダプタが呼び出すメソッドは,gRPCアダプタの開発時に指定したprotoファイルに定義されているサービス定義のメソッドです。
-
proto-XML変換機能
ビジネスプロセスから渡された要求電文をgRPCサービスに送信し,メッセージ(プロトコルバッファ)に変換します。メッセージは,メソッド定義の引数に沿って作成されます。
また,gRPCサービスから返されたメッセージ(プロトコルバッファ)を応答電文に変換します。応答電文は,開発環境で設定された応答電文スキーマに沿って作成されます。
gRPCアダプタとgRPCサーバ間では,メッセージはプロトコルバッファと呼ばれるシリアライズ方式を用いて変換されます。
gRPCアダプタのメッセージの処理の流れを次に示します。
|
-
ビジネスプロセスからgRPCアダプタに要求電文が渡されます。
-
要求電文をgRPCサーバに送信するメッセージに変換します。
要求電文が電文フォーマット(要求電文ボディ)に沿っていない場合,メッセージの作成でエラーとなり,リクエストが失敗します。
-
変換したメッセージをサーバ呼び出し機能に渡します。
-
gRPCサービスにメッセージを送信します。
-
gRPCサービスから返却されたメッセージを受け取ります。
-
proto-XML変換機能にメッセージを渡します。
-
メッセージを応答電文に変換します。
応答メッセージがメソッド定義の戻り値に沿っていない場合,応答メッセージの受信でエラーとなり,リクエストが失敗します。
-
応答電文をビジネスプロセスに渡します。
gRPCアダプタのオペレーション(サービスアダプタ定義画面の「オペレーション」)は,gRPCアダプタの開発時に指定したサービス定義のメソッド(protoファイルのサービス定義)で設定します。
例えば,サービス定義内にメソッド「SayHello」「SayGoodbye」が定義されている場合,gRPCアダプタのオペレーションに「SayHello」「SayGoodbye」が定義されます。サービスアダプタ定義画面でオペレーション「SayHello」を呼び出した場合は,gRPCサービスのメソッド「SayHello」が呼び出されます。
gRPCアダプタの定義の詳細については,マニュアル「サービスプラットフォーム 開発ガイド 受付・アダプタ定義編」の「3.2.17 gRPCアダプタを新規に追加する」を参照してください。
- 〈この項の構成〉
(1) gRPCアダプタの構成
gRPCサーバは,複数のgRPCサービスで構成されている場合があります。gRPCアダプタがメッセージを送信するgRPCサービスは,gRPCアダプタの開発時に決定するため,リクエスト時に変更することはできません。
|
-
gRPCアダプタとgRPCサーバの数量関係は1:Nです。
-
gRPCアダプタとgRPCサービスの数量関係は1:1です。
-
gRPCアダプタとメソッドの数量関係は1:Nです。ただし,1回のリクエストで呼び出せるメソッドは1つだけです。
-
メソッドは同期で呼び出します。非同期呼び出しは設定できません。
(2) メタデータ
gRPCアダプタは,メッセージ(プロトコルバッファ)に加え,メタデータ(キーと値のペアの任意のセット)を送受信できます。
メタデータ送受信の処理の流れを次に示します。
|
- gRPCサービスへ送信するメタデータ
-
ビジネスプロセスから渡されたヘッダ電文の設定内容からメタデータを作成し,gRPCサービスにメタデータを送信します。
データ形式がバイナリ形式のメタデータを送信する場合,ヘッダ電文内の該当するメタデータの値にはBase64でエンコードした値を設定します。
gRPCアダプタ内で,デコードした値をメタデータの値に設定します。
- gRPCサービスから受信したメタデータ
-
gRPCサービスから,ステータスコード「OK」が返された場合は,gRPCサービスから受信したメタデータの設定内容からヘッダ電文を作成し,ビジネスプロセスに渡します。ヘッダ電文に設定するメタデータは,gRPCサービスが設定したメタデータ,およびgRPC内で設定されたメタデータとします。
また,フォルト応答で,gRPCサービスから返却された例外にメタデータが設定されている場合,例外に設定されているメタデータをフォルト電文に設定します。
メタデータのデータ形式がバイナリ形式の場合,gRPCアダプタは該当するメタデータの値をBase64でエンコードした値をヘッダ電文に設定します。
送受信するメタデータの値は,テキスト形式またはバイナリ形式で設定できます。どちらのデータ形式かは,メタデータのキー名によって判断します。
-
バイナリ形式:メタデータのキー名が-bin(大文字小文字を区別する)で終わる場合
-
テキスト形式:メタデータのキー名が-bin以外で終わる場合
データ形式はメタデータのキーごとに設定できます。
メタデータの設定内容は,ヘッダ電文で扱われます。ただし,gRPCサービスから返された例外に設定されているメタデータは含まれません。
ヘッダ電文の設定については,マニュアル「サービスプラットフォーム 開発ガイド 受付・アダプタ定義編」の「3.3.17 gRPCアダプタを定義する」を参照してください。
(3) フォルト応答
gRPCアダプタでは,次のフォルト応答を設定できます。
-
ステータスコードに応じたフォルト応答
-
システム例外発生時のフォルト応答
それぞれのフォルト応答について説明します。
(a) ステータスコードに応じたフォルト応答
gRPCアダプタでは,gRPC呼び出し実行時に返されたステータスコードが「OK」以外の場合に,フォルト応答としてフォルトを返す設定ができます。フォルト応答は,gRPCアダプタ独自定義ファイルのadpgrpc.response-code.faultで設定します。
gRPCサービスから返されたステータスコードが,gRPCアダプタ独自定義ファイルのadpgrpc.response-code.faultに指定したステータスコードのどれかと一致する場合にフォルト応答を行います。
gRPCアダプタのフォルト応答では,例外情報を基にフォルト電文を作成し,フォルト応答としてフォルト電文をビジネスプロセスに返します。
フォルト電文の設定については,マニュアル「サービスプラットフォーム 開発ガイド 受付・アダプタ定義編」の「3.3.17 gRPCアダプタを定義する」を参照してください。
ステータス情報には詳細メッセージが設定されている場合があります。詳細メッセージが,gRPCが提供しているprotoファイルであるerror_details.proto(エラーの詳細に関する標準エラーペイロードのセット)内に定義されているメッセージのとき,gRPCアダプタはフォルト電文内の詳細メッセージを設定するための要素に,メッセージの内容を設定します。対象のメッセージを次に示します。
-
RetryInfo
-
DebugInfo
-
QuotaFailure
-
ErrorInfo
-
PreconditionFailure
-
BadRequest
-
RequestInfo
-
ResourceInfo
-
Help
-
LocalizedMessage
error_details.proto内に定義されていないメッセージの場合,フォルト電文のadditional-messageタグにメッセージの内容を設定します。
(b) システム例外発生時のフォルト応答
gRPCアダプタでシステム例外が発生した場合,またはgRPC呼び出し実行時に例外が発生した場合,システム例外をフォルトに変換して,ビジネスプロセスにフォルト応答を返すことができます。
システム例外発生時のフォルト応答を行うには,次の条件をすべて満たす必要があります。
-
gRPCアダプタ独自定義ファイルのadpgrpc.response-code.faultに指定したステータスコードのどれとも一致しない。
-
サービスアダプタ定義画面で[システム例外をフォルトに変換する]をチェックしている。
(4) メッセージの圧縮と解凍
gRPCサービスにgzip形式で圧縮したメッセージを送信できます。また,gRPCサービスからgzip形式で圧縮されたメッセージが返された場合,メッセージを解凍します。メッセージの圧縮は,gRPCアダプタ独自定義ファイルのadpgrpc.protocol.message-compression.enabledで設定します。gRPCサービスから返されたメッセージがgzip形式以外で圧縮されたデータの場合,リクエストはエラーとなります。
(5) gRPCアダプタのセキュリティ
gRPCアダプタとgRPCサーバ間で交換されるすべてのデータを暗号化できます。gRPCアダプタでは,次の認証方式をサポートしています。
-
SSL/TLS
-
Token-based authentication with Google
(a) SSL/TLSの設定
SSL/TLS認証を設定する場合,gRPCアダプタ実行環境(共通)プロパティファイルのadpgrpc.request.use-plaintextにfalseを設定する必要があります。
また,設定する項目は,認証方式によって異なります。認証方式ごとの設定項目を次に示します。
認証方式 |
設定項目 |
プロパティ |
設定の要否 |
---|---|---|---|
サーバ認証 |
サーバのルート証明書 |
adpgrpc.security.tls.certificate-chain |
任意 |
双方向認証※ |
サーバのルート証明書 |
adpgrpc.security.tls.certificate-chain |
任意 |
クライアントの証明書チェーン |
adpgrpc.security.tls.client.certificate-chain |
必須 |
|
クライアントの秘密鍵 |
adpgrpc.security.tls.client.private-key |
必須 |
|
クライアントの秘密鍵のパスワード |
adpgrpc.security.tls.client.private-key-password |
任意 |
- 注※
-
双方向認証をする場合,必須の情報がすべて設定されている必要があります。設定されていない場合は,双方向認証は行われません。
(b) Token-based authentication with Googleの設定
gRPCアダプタからGoogle API(Google社が提供する各種サービスにアクセスする機能)を呼び出す場合に必要な認証です。
Token-based authentication with Googleの設定は,gRPCアダプタ実行環境(共通)プロパティファイルで設定します。Token-based authentication with Googleについての設定項目を次に示します。
設定項目 |
プロパティ |
設定の要否 |
説明 |
---|---|---|---|
スコープ |
adpgrpc.security.token-based-auth.scope |
任意 |
Google APIへのアクセスに必要となるOAuth 2.0スコープを指定します。 認証されたユーザを承認するかどうかを判定するために設定します。 |
クレデンシャル |
adpgrpc.security.token-based-auth.credentials |
必須 |
サービスアカウントキーファイルを指定します。ファイルの内容がJSON形式でない場合の動作は保証されません。 |
アクセストークンの有効期限が切れた場合,自動的にアクセストークンはリフレッシュされます。そのため,ユーザがアクセストークンを手動で再取得する必要はありません。
(6) gRPCアダプタのタイムアウト
gRPCアダプタのタイムアウトは,gRPCアダプタ独自定義ファイルで設定します。
設定項目 |
プロパティ |
説明 |
|
---|---|---|---|
キープアライブ |
PINGの送信間隔 |
adpgrpc.protocol.keepalive-time |
キープアライブPINGの送信間隔を指定します。 |
タイムアウト時間 |
adpgrpc.protocol.keepalive-timeout |
キープアライブタイムアウト時間を指定します。 設定した時間が経過しても接続先から応答がない場合,接続を終了します。再度RPC要求があるまで再接続はしません。 |
|
未処理のRPCがない場合の動作 |
adpgrpc.protocol.keepalive-without-calls |
未処理のRPCがない場合に,キープアライブを実行するかどうかを指定します。 |
|
アイドルタイムアウト時間 |
adpgrpc.protocol.idle-timeout |
チャネルの状態をアイドル状態に移行するまでの時間を指定します。 アイドル状態になった場合,再度RPC要求があるまで再接続はしません。 |
|
リクエストの実行期限 |
adpgrpc.protocol.deadline |
RPCがDEADLINE_EXCEEDEDでエラー終了する前の,RPCの完了待ち時間を指定します。 gRPCアダプタの接続先が利用できるようになるまで,gRPC呼び出しを待機します。実行期限が経過してもRPCが完了しなかった場合,リクエストはエラーとなり,ステータスコード「DEADLINE_EXCEEDED」が返されます。 |
gRPCで指定できるタイムアウトの関係を次に示します。
|
-
リクエストの実行期限
-
キープアライブ(未処理のRPCがない場合に,キープアライブを実行する場合)
-
キープアライブ(未処理のRPCがない場合に,キープアライブを実行しない場合)
-
アイドルタイムアウト時間
キープアライブタイムアウトの流れを次に示します。
|
キープアライブPINGの送信間隔が10分の場合,「キープアライブPINGの応答」の10分後に,gRPCアダプタはキープアライブPINGを送信します。
キープアライブタイムアウトが20秒の場合,gRPCアダプタがキープアライブPINGを送信してから20秒以内に「キープアライブPINGの応答」がないときはタイムアウトしたとみなされます。