3.3.17　gRPCアダプタを定義する

(a)　gRPCアダプタの要求電文フォーマット

gRPCアダプタの要求電文フォーマット（ヘッダ）について説明します。

ファイルの格納場所は「<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\schema\adpgrpc_metadata_request.xsd」です。

名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/grpc/header/metadata_request」です。

表3‒126　gRPCアダプタの要求電文フォーマット（ヘッダ）

タグ名			種別	出現回数	説明
<grpc-metadata-request>			−	1回	−
	<metadata>		−	0回以上	gRPCサービスに送信するメタデータを指定します。
		<key>	string	1回	gRPCサービスに送信するメタデータのキーを指定します。キーに指定できる値は半角英数字，アンダーバー（_），ハイフン（-），ピリオド（.）です。キーの省略はできません。指定値の大文字・小文字は区別しません。 「grpc-」から始まる要素名は指定できません。「grpc-」から始まる要素名を指定した場合の動作は保証されません。 バイナリ形式で送信する場合，この要素値は「-bin（大文字・小文字を区別する）」で終了してください。ただし，「-bin」だけを指定することはできません。
		<value>	string	1回	メタデータのキーに対する値を指定します。 テキスト形式の場合，0x20および0x21〜0x7Eの範囲の文字列が指定できます。ただし，空白（0x20）は，値の最初または最後には指定できません。 指定できない値を指定した場合の動作は保証されません。 バイナリ形式の場合，Base64でエンコードした値を指定します。

(b)　gRPCアダプタの応答電文フォーマット

gRPCアダプタの応答電文フォーマット（ヘッダ）について説明します。

ファイルの格納場所は「<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\schema\adpgrpc_metadata_response.xsd」です。

名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/grpc/header/metadata_response」です。

表3‒127　gRPCアダプタの応答電文フォーマット（ヘッダ）

タグ名			種別	出現回数	説明
<grpc-metadata-response>			−	1回	−
	<metadata>		−	0回以上	gRPCサービスから返却されたメタデータを指定します。
		<key>	string	1回	gRPCサービスから返却されたメタデータのキーを指定します。 バイナリ形式の場合，この要素値は「-bin」で終了させてください。
		<value>	string	1回	メタデータのキーに対する値を指定します。 バイナリ形式の場合，Base64でエンコードした値を指定します。

(c)　gRPCアダプタのフォルト電文フォーマット

gRPCアダプタでは，gRPCのメッセージ内容^※に沿ったフォルト電文フォーマットを提供しています。このフォルト電文フォーマット（XMLスキーマファイル）は，gRPCアダプタを作成したときに，gRPCアダプタ定義画面（基本）のフォルト電文フォーマットに自動的に設定されます。

注※

gRPCを利用した通信では，google.rpc.Statusのメッセージの処理方式によってエラー処理を行っています。google.rpc.Statusのメッセージ内容，およびエラー処理については，Google社のgoogle.rpc.Statusに関するサイトを参照してください。

gRPCアダプタを作成したあと，必要に応じてフォルト電文フォーマットのXMLスキーマファイルを修正し，再登録できます。再登録することで，XMLスキーマファイルの記述を簡略化できます。

XMLスキーマファイルを修正する手順を次に示します。

1. 次のXMLスキーマファイルを任意の場所にコピーします。

   <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC¥schema\adpgrpc_fault.xsd

2. コピーしたXMLスキーマファイルをテキストエディタで開きます。

3. XMLスキーマファイルに定義されている，/fault/status/details要素以下に定義されている次の要素のうち，使用しない要素を削除します。

   • retry-info

   • debug-info

   • quota-failure

   • error-info

   • precondition-failure

   • bad-request

   • request-info

   • resource-info

   • help

   • localized-message

   • additional-message

   処理に必要な要素を削除した場合の動作は保証されません。

   これらの要素は，Google社が提供するgoogle/rpc/error_details.protoの内容に対応しています。google/rpc/error_details.protoの内容については，Google社のgoogle/rpc/error_details.protoに関するサイトを参照してください。

   なお，additional-messageは，google/rpc/error_details.protoに定義されていない任意の型のメッセージを格納する場合に使用します。

4. 使用しない要素（子要素を含む）を削除したXMLスキーマファイルを保存します。

5. 修正したXMLスキーマファイルを，サービスアダプタ定義画面（基本）の［フォルト電文］に設定します。

   修正したXMLスキーマファイル以外を設定した場合，動作は保証されません。

gRPCアダプタのフォルト電文フォーマットの形式について説明します。

名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/grpc/fault」です。

表3‒128　gRPCアダプタのフォルト電文フォーマット

タグ名						種別	出現回数	説明
<fault>						−	1回	−
	<status>					−	1回	ステータス情報を指定します。
		<code>				文字列	1回	ステータスコード※を指定します。
		<message>				文字列	0〜1回	開発者向けのエラーメッセージを指定します。
		<details>				−	0〜1回	詳細エラーのメッセージのリストを指定します。子要素として「error_details.proto」のメッセージ構造体に応じた要素が出現します。
			<additional-message>			−	0回以上	「error_details.proto」のメッセージ構造体に定義されていないメッセージの定義内容を指定します。Any型のメッセージとして扱われます。
				<type-url>		文字列	1回	メッセージのタイプ（URL/resource name）を指定します。
				<value>		文字列	1回	メッセージの値をBase64エンコードしたデータを指定します。
			<bad-request>			−	0回以上	メッセージ構造体「BadRequest」の定義内容を指定します。
				<field-violation>		−	0回以上	メッセージ構造体「FieldViolation」の定義内容を指定します。
					<field>	文字列	0〜1回	引数「field」が設定されます。
					<description>	文字列	0〜1回	引数「description」が設定されます。
			<debug-info>			−	0回以上	メッセージ構造体「DebugInfo」の定義内容を指定します。
				<stack-entries>		文字列	0回以上	引数「stack_entries」が設定されます。
				<detail>		文字列	0〜1回	引数「detail」が設定されます。
			<error-info>			−	0回以上	メッセージ構造体「ErrorInfo」の定義内容を指定します。
				<reason>		文字列	0〜1回	引数「reason」が設定されます。
				<domain>		文字列	0〜1回	引数「domain」が設定されます。
				<metadata>		−	0回以上	引数「metadata」が設定されます。
					<key>	文字列	1回	メタデータのキーを指定します。
					<value>	文字列	1回	メタデータの値を指定します。
			<help>			−	0回以上	メッセージ構造体「Help」の定義内容を指定します。
				<link>		−	0回以上	メッセージ構造体「Link」の定義内容を指定します。
					<description>	文字列	0〜1回	引数「description」が設定されます。
					<url>	文字列	0〜1回	引数「url」が設定されます。
			<localized-message>			−	0回以上	メッセージ構造体「LocalizedMessage」の定義内容を指定します。
				<locale>		文字列	0〜1回	引数「locale」が設定されます。
				<message>		文字列	0〜1回	引数「message」が設定されます。
			<precondition-failure>			−	0回以上	メッセージ構造体「PreconditionFailure」の定義内容を指定します。
				<violation>		−	0回以上	メッセージ構造体「Violation」の定義内容を指定します。
					<type>	文字列	0〜1回	引数「type」が設定されます。
					<subject>	文字列	0〜1回	引数「subject」が設定されます。
					<description>	文字列	0〜1回	引数「description」が設定されます。
			<quota-failure>			−	0回以上	メッセージ構造体「QuotaFailure」の定義内容を指定します。
				<violation>		−	0回以上	メッセージ構造体「Violation」の定義内容を指定します。
					<subject>	文字列	0〜1回	引数「subject」が設定されます。
					<description>	文字列	0〜1回	引数「description」が設定されます。
			<request-info>			−	0回以上	メッセージ構造体「RequestInfo」の定義内容を指定します。
				<request-id>		文字列	0〜1回	引数「request_id」が設定されます。
				<serving-data>		文字列	0〜1回	引数「serving_data」が設定されます。
			<resource-info>			−	0回以上	メッセージ構造体「ResourceInfo」の定義内容を指定します。
				<resource-type>		文字列	0〜1回	引数「resource_type」が設定されます。
				<resource-name>		文字列	0〜1回	引数「resource_name」が設定されます。
				<owner>		文字列	0〜1回	引数「owner」が設定されます。
				<description>		文字列	0〜1回	引数「description」が設定されます。
			<retry-info>			−	0回以上	メッセージ構造体「RetryInfo」の定義内容を指定します。
				<retry-delay>		文字列	0〜1回	引数「retry_delay」が設定されます。
					<seconds>	文字列	1回	引数「retry_delay」の秒が設定されます。
					<nanos>	文字列	1回	引数「retry_delay」のナノ秒が設定されます。
	<metadata>					−	0回以上	トレーラ（gRPCサービスから返却されたメタデータ）を指定します。
		<key>				文字列	1回	メタデータのキーを指定します。
		<value>				文字列	1回	メタデータのキーに対する値を指定します。 バイナリ形式の場合，Base64でエンコードした値を設定します。

注※

フォルト電文に設定できるステータスコードを次に示します。次に示すステータスコード以外の値が設定された場合，リクエストがエラーとなります。

• CANCELLED

• UNKNOWN

• INVALID_ARGUMENT

• DEADLINE_EXCEEDED

• NOT_FOUND

• ALREADY_EXISTS

• PERMISSION_DENIED

• RESOURCE_EXHAUSTED

• FAILED_PRECONDITION

• ABORTED

• OUT_OF_RANGE

• UNIMPLEMENTED

• INTERNAL

• UNAVAILABLE

• DATA_LOSS

• UNAUTHENTICATED

(a)　gRPCアダプタ独自定義ファイル

gRPCアダプタ独自定義ファイルは，サービスプラットフォームが提供するテンプレートファイルを利用して編集します。

gRPCアダプタ独自定義ファイルの編集手順を示します。

1. サービスアダプタ定義画面（詳細）の［独自定義ファイル］で「cscadpgrpc.properties」を選択し，［編集］ボタンをクリックします。

   gRPCアダプタ独自定義ファイルを編集するためのエディタが起動します。

2. エディタ上でgRPCアダプタ独自定義ファイルを編集します。

   gRPCアダプタ独自定義ファイルで編集できる定義内容については，マニュアル「サービスプラットフォーム リファレンス」の「3.16.1　gRPCアダプタ独自定義ファイル」を参照してください。

3. Eclipseのメニューから［ファイル］−［保存］を選択し，定義内容を保存します。

(b)　gRPCアダプタ実行環境プロパティファイル

gRPCアダプタ実行環境プロパティファイルの設定方法を次に示します。

1. テンプレートファイル（<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\config\templates\serviceid.properties）をコピーして，次のディレクトリに格納します。

   全HCSCサーバ共通の定義の場合

   <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\config

   特定のHCSCサーバ用の定義の場合

   サブディレクトリ<HCSCサーバ名>を作成して格納してください。Windowsの場合，HCSCサーバ名の大文字・小文字は区別されます。

   <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\config\<HCSCサーバ名>

2. コピーしたテンプレートファイルのファイル名を「<サービスID^※>.properties」に変更します。

3. 定義内容を編集して保存します。

   gRPCアダプタ実行環境プロパティファイルで編集できる定義内容については，マニュアル「サービスプラットフォーム リファレンス」の「6.19.1　gRPCアダプタ実行環境プロパティファイル」を参照してください。

注※

サービスIDは，gRPCアダプタを新規に追加するときにサービスアダプタ定義画面で指定する任意の文字列です。

(c)　gRPCアダプタ実行環境共通プロパティファイル

gRPCアダプタ実行環境共通プロパティファイルの設定方法を次に示します。

1. テンプレートファイル（<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\config\templates\adpgrpccom.properties）をコピーして，次のディレクトリに格納します。

   全HCSCサーバ共通の定義の場合

   commonディレクトリはユーザが作成してください。

   <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\config\common

   特定のHCSCサーバ用の定義の場合

   サブディレクトリ<HCSCサーバ名>と「common」はユーザが作成してください。Windowsの場合，HCSCサーバ名の大文字・小文字は区別されます。

   <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\config\<HCSCサーバ名>\common

2. 定義内容を編集して保存します。

   ファイル名は変更しないでください。

   gRPCアダプタ実行環境プロパティファイルで編集できる定義内容については，マニュアル「サービスプラットフォーム リファレンス」の「6.19.2　gRPCアダプタ実行環境共通プロパティファイル」を参照してください。

(a)　要求電文（ヘッダ）および応答電文（ヘッダ）の変数の設定

要求電文（ヘッダ）および応答電文（ヘッダ）の変数の設定手順を次に示します。

1. サービスアダプタ定義画面のキャンバス上の［変数・相関セット］アイコンをダブルクリックします。

   ［変数・相関セット一覧］ダイアログが表示されます。

2. ［変数名］に任意の名称を指定します。

3. ［種別］ドロップダウンリストから「XML」を選択します。

4. ［電文フォーマット］の［参照］ボタンをクリックします。

   電文フォーマットを指定するダイアログが表示されます。

5. 変数に応じて次のファイルを指定します。

   • 要求電文（ヘッダ）の変数

     <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\schema\adpgrpc_metadata_request.xsd

   • 応答電文（ヘッダ）の変数

     <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\gRPC\schema\adpgrpc_metadata_response.xsd

6. ［変数・相関セット一覧］ダイアログで［追加］ボタンをクリックします。

   変数が追加されます。

(b)　要求電文（ボディ），応答電文（ボディ），およびフォルト電文の変数の設定

要求電文（ボディ），応答電文（ボディ），およびフォルト電文の変数の設定手順を次に示します。

1. ビジネスプロセス定義画面のキャンバス上の［変数・相関セット］アイコンをダブルクリックします。

   ［変数・相関セット一覧］ダイアログが表示されます。

2. ［変数名］に任意の名称を指定します。

3. ［種別］ドロップダウンリストから「XML」を選択します。

4. ［電文フォーマット］の［取込］ボタンをクリックします。

   ［電文フォーマットの取込］ダイアログが表示されます。

5. ［サービス名］をチェックし，ドロップダウンリストからサービスアダプタ定義画面で設定したgRPCアダプタの名称を選択します。

6. ［オペレーション名］ドロップダウンリストからgRPCアダプタに設定したオペレーションを選択します。

7. 変数に応じて［電文種別］ドロップダウンリストで電文種別を選択します。

   • 要求電文（ボディ）の変数の場合

     ［要求電文（ボディ）］を選択します。

   • 応答電文（ボディ）の変数の場合

     ［応答電文（ボディ）］を選択します。

   • フォルト電文の変数の場合

     ［フォルト電文］を選択します。

8. ［電文フォーマット］に任意の名称を入力します。

9. ［OK］ボタンをクリックします。

10. ［変数・相関セット一覧］ダイアログで［追加］ボタンをクリックします。

    変数が追加されます。

(c)　サービス呼出アクティビティの設定

gRPCアダプタを呼び出すためのサービス呼出アクティビティを定義します。サービス呼出アクティビティの定義方法については，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「5.6.4　サービス呼出アクティビティ」を参照してください。

［サービス呼出アクティビティ］ダイアログの設定内容を次に示します。

項目		設定値
アクティビティ名		任意の名称を設定します。
サービス名		gRPCアダプタの新規追加時に設定したサービス名を指定します。
オペレーション名		「(3)　サービスアダプタ定義画面での操作」で設定したオペレーション名を指定します。
要求電文	ボディ割当変数	「(b)　要求電文（ボディ），応答電文（ボディ），およびフォルト電文の変数の設定」で設定した要求電文の変数を指定します。
	ヘッダ割当変数※	「(a)　要求電文（ヘッダ）および応答電文（ヘッダ）の変数の設定」でヘッダ割当変数に設定した要求電文（ヘッダ）の変数を指定します。
応答電文	ボディ割当変数	「(b)　要求電文（ボディ），応答電文（ボディ），およびフォルト電文の変数の設定」で設定した応答電文の変数を指定します。
	ヘッダ割当変数※	「(a)　要求電文（ヘッダ）および応答電文（ヘッダ）の変数の設定」でヘッダ割当変数に設定した応答電文（ヘッダ）の変数を指定します。
割当相関セット群		設定しません。

(d)　フォルト処理の設定

正常系として処理できないステータスコードやフォルトに変換したシステム例外をビジネスプロセスでエラーとして処理する場合は，サービス呼出アクティビティや上位のスコープにフォルト処理を定義します。フォルト処理の定義方法については，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「5.4.4　フォルト処理を定義する」を参照してください。

［フォルト処理の割当］ダイアログの設定内容を次に示します。

項目	設定値
割当変数	「(b)　要求電文（ボディ），応答電文（ボディ），およびフォルト電文の変数の設定」で設定したフォルト電文の変数を指定します。
遷移先	フォルトが発生した場合に遷移する任意のアクティビティを指定します。