Hitachi

Cosminexus V11 BPM/ESB基盤 サービスプラットフォーム 解説

2.13.5　gRPCアダプタの機能

gRPCアダプタは，gRPCで作成されたサービスにメッセージを送信するためのサービスアダプタです。gRPCアダプタがサポートするgRPC電文フォーマットは，proto3以上です。proto2以前の電文フォーマットはサポートしません。

また，gRPCアダプタを使用するには，OSSのインストールが必要です。必要なOSSについては，「2.13.1(1)　gRPCプロトコルを利用した接続に必要なOSS」を参照してください。

gRPCアダプタには，次の機能があります。

gRPCアダプタとgRPCサーバ間では，メッセージはプロトコルバッファと呼ばれるシリアライズ方式を用いて変換されます。

gRPCアダプタのメッセージの処理の流れを次に示します。

図2‒122　gRPCアダプタのメッセージの処理の流れ

[図データ]

  1. ビジネスプロセスからgRPCアダプタに要求電文が渡されます。

  2. 要求電文をgRPCサーバに送信するメッセージに変換します。

    要求電文が電文フォーマット（要求電文ボディ）に沿っていない場合，メッセージの作成でエラーとなり，リクエストが失敗します。

  3. 変換したメッセージをサーバ呼び出し機能に渡します。

  4. gRPCサービスにメッセージを送信します。

  5. gRPCサービスから返却されたメッセージを受け取ります。

  6. proto-XML変換機能にメッセージを渡します。

  7. メッセージを応答電文に変換します。

    応答メッセージがメソッド定義の戻り値に沿っていない場合，応答メッセージの受信でエラーとなり，リクエストが失敗します。

  8. 応答電文をビジネスプロセスに渡します。

gRPCアダプタのオペレーション（サービスアダプタ定義画面の「オペレーション」）は，gRPCアダプタの開発時に指定したサービス定義のメソッド（protoファイルのサービス定義）で設定します。

例えば，サービス定義内にメソッド「SayHello」「SayGoodbye」が定義されている場合，gRPCアダプタのオペレーションに「SayHello」「SayGoodbye」が定義されます。サービスアダプタ定義画面でオペレーション「SayHello」を呼び出した場合は，gRPCサービスのメソッド「SayHello」が呼び出されます。

gRPCアダプタの定義の詳細については，マニュアル「サービスプラットフォーム 開発ガイド 受付・アダプタ定義編」の「3.2.17　gRPCアダプタを新規に追加する」を参照してください。

〈この項の構成〉

(1)　gRPCアダプタの構成

gRPCサーバは，複数のgRPCサービスで構成されている場合があります。gRPCアダプタがメッセージを送信するgRPCサービスは，gRPCアダプタの開発時に決定するため，リクエスト時に変更することはできません。

図2‒123　gRPCアダプタの構成

[図データ]

ページの先頭へ

(2)　メタデータ

gRPCアダプタは，メッセージ（プロトコルバッファ）に加え，メタデータ（キーと値のペアの任意のセット）を送受信できます。

メタデータ送受信の処理の流れを次に示します。

図2‒124　メタデータ送受信の処理の流れ

[図データ]
gRPCサービスへ送信するメタデータ

ビジネスプロセスから渡されたヘッダ電文の設定内容からメタデータを作成し，gRPCサービスにメタデータを送信します。

データ形式がバイナリ形式のメタデータを送信する場合，ヘッダ電文内の該当するメタデータの値にはBase64でエンコードした値を設定します。

gRPCアダプタ内で，デコードした値をメタデータの値に設定します。

gRPCサービスから受信したメタデータ

gRPCサービスから，ステータスコード「OK」が返された場合は，gRPCサービスから受信したメタデータの設定内容からヘッダ電文を作成し，ビジネスプロセスに渡します。ヘッダ電文に設定するメタデータは，gRPCサービスが設定したメタデータ，およびgRPC内で設定されたメタデータとします。

また，フォルト応答で，gRPCサービスから返却された例外にメタデータが設定されている場合，例外に設定されているメタデータをフォルト電文に設定します。

メタデータのデータ形式がバイナリ形式の場合，gRPCアダプタは該当するメタデータの値をBase64でエンコードした値をヘッダ電文に設定します。

送受信するメタデータの値は，テキスト形式またはバイナリ形式で設定できます。どちらのデータ形式かは，メタデータのキー名によって判断します。

データ形式はメタデータのキーごとに設定できます。

メタデータの設定内容は，ヘッダ電文で扱われます。ただし，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アダプタでは，次の認証方式をサポートしています。

(a)　SSL/TLSの設定

SSL/TLS認証を設定する場合，gRPCアダプタ実行環境（共通）プロパティファイルのadpgrpc.request.use-plaintextにfalseを設定する必要があります。

また，設定する項目は，認証方式によって異なります。認証方式ごとの設定項目を次に示します。

表2‒52　認証方式ごとの設定項目

認証方式

設定項目

プロパティ

設定の要否

サーバ認証

サーバのルート証明書

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についての設定項目を次に示します。

表2‒53　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アダプタ独自定義ファイルで設定します。

表2‒54　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で指定できるタイムアウトの関係を次に示します。

図2‒125　gRPCで指定できるタイムアウトの関係

[図データ]

  1. リクエストの実行期限

  2. キープアライブ（未処理のRPCがない場合に，キープアライブを実行する場合）

  3. キープアライブ（未処理のRPCがない場合に，キープアライブを実行しない場合）

  4. アイドルタイムアウト時間

キープアライブタイムアウトの流れを次に示します。

図2‒126　キープアライブタイムアウトの流れ

[図データ]

キープアライブPINGの送信間隔が10分の場合，「キープアライブPINGの応答」の10分後に，gRPCアダプタはキープアライブPINGを送信します。

キープアライブタイムアウトが20秒の場合，gRPCアダプタがキープアライブPINGを送信してから20秒以内に「キープアライブPINGの応答」がないときはタイムアウトしたとみなされます。

ページの先頭へ

商品名称に関する表示

All Rights Reserved. Copyright (C) 2020, 2024, Hitachi, Ltd.