管理
AP to AP (REST)インターフェースの登録手順は、下記のとおりである。
1. 電文レイアウト登録
電文レイアウトは、共通部、個別部のレイアウトを登録・管理する機能である。
共通部はシステムごとの共通電文であるため、エンジン設定時に登録する。
個別部は、各インターフェースの担当者がMessage Management > Message Layout画面を利用して登録する。
電文レイアウトはフィールド名、タイプ、長さなどの情報を含むレイアウト情報である。電文レイアウト登録時、反復部項目に別の電文レイアウトを設定して処理することができる。
反復部と下位電文のレイアウト例は、下記のとおりである。
上記の例のように、複数のアドレス情報を管理する場合、郵便番号やアドレス、詳細アドレスを持つAddrInfoをレイアウトに登録する。
その後id、pwとアドレス情報のレイアウトであるAddrInfoを含むUserInfoレイアウトを作成する。
電文にはバージョンがあり、インターフェースに使用される電文レイアウトID単位で、変更ログを管理するために管理するために使用される。
インターフェースの電文レイアウトが変更する場合、既存のレイアウト情報を修正し、バージョンアップして登録すると、電文レイアウトの画面から、現在のバージョンおよび過去のバージョンに関する変更ログが確認できる。
登録手順
Message Management > Message Layout画面でグリッド右上のボタンをクリックし、新規電文レイアウトの登録画面を開く。- 右上の行追加ボタンをクリックし、電文の各フィールド項目のフィールド名およびタイプ、長さなどを設定して登録する。
☑基本情報
- Version :
Setting > Layout Version Managementに登録されているバージョンを選択する。 - Target Space Name : XMLのネームスペース名を入力する。入力しなかった場合、レイアウトIDがネームスペース名になる。
- Root Element Name : JSONやXML電文のRootエレメント名を入力する。入力しなかった場合、レイアウトIDがRootエレメント名になる。
- Copy Message Layout : 登録済みの電文レイアウトをコピーして新しいレイアウトを作成する。
☑フィールド情報
| カラム | 説明 |
|---|---|
| Element Name | JSONやXML電文で使用するフィールドのエレメント名を意味する。入力しない場合、フィールド名がエレメント名になる。 |
| Field Name | フィールドの英語名を意味する。 |
| Field Description | フィールドの説明を意味する。 |
| Type | 登録できるデータタイプはBoolean、Byteなどがある。当該データタイプはjavaのデータタイプと同じであり、そのうちDTO選択の場合、電文レイアウトとして登録されたレイアウトを意味する。 |
| Length | フィールド長を意味する。 |
| Offset | フィールドのOffset値を意味する。 |
| Decimal Length | フィールドの小数点以下の長さを意味する。 |
| Format | 当該フィールドの日付や時間に関するフォーマットを意味する。 |
| Array Reference Field | 繰り返される電文レイアウトの大きさ(値)を持つフィールド名、または反復回数を直接入力する項目を意味する。 |
| Encryption | フィールドで暗号・復号化を使用するかどうかを意味する。暗号・復号化の処理情報はエンジン設定時に登録され、電文レイアウトでは使用するかどうかを選択する。 |
| Code Conversion | フィールドのコード変換方式を意味する。ASCII、EBCDICなどのエンコーディング、デコーディングに使用するコード変換方式を登録する。 |
| Default Value | フィールドがnullの場合(入力していない場合)に使用するデフォルト値を意味する。 |
| Order | 当該フィールドの並べ替え方式で、leftとrightのうち１つを値として持つ。タイプがStringの場合にはleft、intなどの数字の場合にはrightがデフォルト値となる。 |
2. インターフェース登録
Interface Management > Online Interface画面を利用して登録する。
インターフェースID、インターフェース名は、インターフェースを識別値で設定する。
各構成項目に関する説明は、下記のとおりである。
構成項目
☑基本情報
- Institution Code : 機関コード
- External Business Code : 機関で使用する業務コード
- System Code : システムコード
- Internal Business Code : システムで使用する業務コード
- Apply Date : 当該インターフェースを適用する日付。 当日から実行する場合、今日より過去の日付を登録する。
- Service Code : 呼び出す時に同じURLを使用し、共通部のサービスコードを使用する方式で共通部のサービスコードの値を登録する。
基本設定管理 > システム別業務でサービス呼び出し区分コードがURL方式の場合、代わりにコンテキストURLを設定できるが、これはURL単位で呼び出す方式の時に呼び出しURLを定義する。 - Synchronization Y/N : 同期/非同期方式に関する設定
- Response Y/N : 応答するかどうかを設定
- Request Type : 対外機関が要求する取引の場合には対外要求、対内システムが要求する取引の場合には対内要求
- Request Flow ID :FEPで要求処理時に使用するフロー
- Response Flow ID : FEPで応答処理時に使用するフロー
☑ 電文情報
- Request Message Layout Name :送信システムの要求電文レイアウト
- Response Message Layout Name : 受信システムの応答電文レイアウト
- Request Header Message Transformation ID : 要求電文の共通ヘッダー部を変換するための変換情報
- Response Header Message Transformation ID : 応答電文の共通ヘッダー部を変換するための変換情報
- Request Body Message Transformation ID : 要求電文レイアウトを登録した場合、電文を変換するための変換情報
- Response Body Message Transformation ID : 応答電文レイアウトを登録した場合、電文を変換するための変換情報
☑ 追加情報
- Request User Process Program ID : 対内システムの対象サービス、または対外機関にサービスを要求する前に、特別な処理が必要な場合に設定する。
- Response User Process Program ID : 対内システムの対象サービス、または対外機関に応答を送信する前に、特別な処理が必要な場合に設定する。
- Transaction Control Code : 受信サービスの障害などによりインターフェースの取引を制御したい場合に使用される。 取引制御を行うと受信サービスに伝達されなかった場合、設定値によって無応答処理やエラー応答処理を行うことができる。 エラー応答プログラムは、エンジン設定時に定義される。
- Throttle ID : インターフェースに適用する流量制御ポリシー処理件数方式に対応する。
- Timeout Time(Sec) : 応答がない場合にタイムアウト処理をするための時間設定
- Timeout Response Y/N : タイムアウト時に応答するかどうか
- Transmission Error Response Y/N : 伝送エラーやタイムアウト発生時にエラー応答電文を作成して要求機関に送信するかどうか
- Delay Response Transmission Y/N :タイムアウト処理後に応答を受信した場合、対内システムに送信するかどうか
- Flow Process Logging Y/N : ルーター入出力に対してロギングするかどうか
- Root Element Name : 電文マーシャル時にボディのルートエレメント名が
dataではなく、当該ルートエレメント名に変換
上記の項目のうち、インターフェース処理の詳細タイプおよび要求/応答電文レイアウトについては、下記で詳細説明する。
要求/応答電文レイアウト
電文レイアウトとしては、要求電文レイアウトと応答電文レイアウトを登録する。 要求電文レイアウトは図で1に当たり、応答電文レイアウトは上の図で2に当たる。
3. 電文変換の登録
REST取引はREST連携側(機関、システム)がヘッダー部が存在しないため、個別部のみ必要に応じて電文変換を行う。
電文変換は、要求と応答に対してそれぞれ行われる。
したがって、電文変換を登録する際に、要求と応答に対してそれぞれ電文変換情報を登録する必要がある。
電文変換は、入力電文を出力電文に変換する情報を登録することであり、
Message Management > Message Transformationから入力と出力電文を選択してマッピング情報を登録する。
電文変換は、入力と出力電文の項目をマッピングする機能の他に、出力電文に定数やシステム日付などを設定できる。
REST取引はREST連携側にヘッダー部が存在しない。
登録プロセス
Message Management > Message TransformationからMessage Transformation Typeを、それぞれの電文変換タイプで選択する。- 共通部の電文変換、または個別部の電文変換の場合、
Request Response Divisionとして、要求や応答を選択する。 - 電文変換対象の入力レイアウトや出力レイアウトを登録した後、
1:1 Mappingボタンを押してマッピングする。 - 情報登録後、保存ボタンを押して完了する。
電文変換に登録されたマッピング情報以外に追加でマッピングが必要な場合、User Programを呼び出してマッピングできる。
電文変換に登録されたマッピング後に呼び出される。
電文変換の種類
共通部の電文変換
REST取引は共通部の電文変換しない。
個別部の電文変換
個別部の電文変換は、入力として受信した電文の個別部に該当する部分を、サービス入力の個別部に合わせて変換(マッピング)する。 要求、応答の電文変換をそれぞれ登録する必要がある。
反復部の電文変換
反復部の電文変換は、繰り返される下位電文レイアウトに関する、電文変換を登録することを意味する。 登録された反復部の電文変換情報は、繰り返し使用できる。
マッピング情報
| カラム | 説明 |
|---|---|
| Attribute name | 入力レイアウトのフィールド名のうち１つを選択する。出力レイアウトのフィールドに、選択した入力レイアウトのフィールドデータが保存される。 |
| Constant | 特定の定数値を入力する。出力レイアウトのフィールドに、入力した定数値が保存される。 |
| Special word | スペシャルワードの意味によって値を設定する。例えば、GUIDを選択した場合、出力レイアウトのフィールドには、作成されたGUID値が保存される。現在、基本のスペシャルワードはGUIDである。詳細については、ユーザースペシャルワード処理方法を参照する。 |
| System date | 現在の日付や時間のフォーマットをリストから選択する。 |
| script | 入力値に補正を行う必要がある場合そのscriptを入力する。詳細については、スクリプトを参照する。 |
| Submaps | サブレイアウトの場合、反復部の電文変換に登録したサブマッピングを選択する。 |
| No transformation | 当該出力レイアウトフィールドにデータが保存されない。 |
☑ ユーザースペシャルワード処理方法
ユーザーが定義したスペシャルワードの処理方式は、ユーザープログラムを利用して処理する。
ユーザーはユーザースペシャルワードを処理するプログラムを開発し、スペシャルワードを決めてspecialword.propertiesに登録する。
ユーザースペシャルワードはワード別にユニークな名前で登録する必要がある。
ユーザースペシャルワードの登録プロセスは下記のとおりである。
- ユーザースペシャルワードを処理するプログラムを、スプリングビーンプログラムとして開発する。
Base Setting Management > Program Informationで開発したプログラムを登録する。specialword.propertiesファイルに、スペシャルワードとユーザープログラムをマッピングして登録する。 下記はユーザースペシャルワードの登録例である。
# Special word for message transformation
# form: upper case special word=user bean program id
#
SEQUENCE_NO=customSequenceNumber
☑ スクリプト
| 設定値 | 説明 |
|---|---|
| substring | 文字列を分離する。ex) txCode.substring(1,4) |
| toUpperCase | 文字列を大文字に変換する。ex) txCode.toUpperCase() |
| toLowerCase | 文字列を小文字に変換する。ex) txCode.toLowerCase() |
| lpad | 文字列の左側をパディングする。パディングする文字列が指定されていない場合は、0にパディングする。 ex) txCode.lpad(10,A), txCode.lpad(10) |
| rpad | 文字列の右側をパディングする。パディングする文字列が指定されていない場合は、0にパディングする。 ex) txCode.rpad(10), txCode.rpad(10,A) |
| value | 入力レイアウトのデータを特定の値に変換する。 右側の例で、txCodeの値がsource1の場合はtarget1、source2の場合はtarget2に変換する。 ex) txCode.value(source1=target1, source2=target2) |
4. Rest情報の登録
BXIのAPtoAPインターフェースのうちREST方式を使用する場合、ドメインごとに共通して使用される属性の定義が必要である。 プロトコル区分、ホスト、ポート番号のような共通情報が登録され、Restful対応のための詳細情報はAPI情報を通じて登録する。
該設定は機関(REST連携)設定であり、システム設定は既存のAP to APと同じである。
ドメイン情報
API Information Management > Domain Informationで登録する。
構成項目
☑基本情報
- Connection Type : 当該ドメインの
サーバー/クライアント区分を登録する。 - Protocol Division : ドメインが使用するプロトコルを
HTTP/HTTPSの中から選択して登録する。 - Communication Type : 当該ドメインの通信方式をRESTとSOAPの中から選択して登録する。
- Apply Date : 当該ドメインを適用する日付。当日から実行する場合、今日より過去の日付を登録する。
- サーバードメイン : 外部からBXIエンジンに入るインバウンドのREST取引時に使用する。
正常に登録した場合、エンジン起動時、サーバーの当該ポートが
LISTEN状態にオープンする。 - クライアントドメイン : BXIエンジンが外部に要求するアウトバウンドのREST取引時に使用する。
☑基本情報
- URL : IPとPORTを含むドメインのURL情報を登録する。
- Node ID : URLがオープンするノードを登録する。当該ドメインがサーバーの場合にのみ有効となる。
- Instance ID : URLがオープンするインスタンスを登録する。当該ドメインがサーバーの場合にのみ有効となる。
☑ CORS情報
- Access Control Allow Origins : 当該ドメインが
サーバーの場合、CORS要求処理のために登録する。登録されたドメインからの要求のみサーバーのリソースにアクセスできるようにする。 - Access Control Allow Headers : Access Control Allow Originsを登録した場合、要求で使用できるHTTP Headerを指定する。
- Access Control Allow Methods : Access Control Allow Originsを登録した場合、サーバーのリソースにアクセスできるHTTP Method方式を指定する。
☑ 追加情報
- Max Send Receive Message Length : 一度に送受信できる最大電文長を制限する。
- Proxy ID : プロキシを使用する場合に登録する。
- Polling IP : 当該ドメインに対するポーリングIPを登録する。
- Ok Status Code Range : 対象ドメインに対するREST取引時に返される状態コード値の正常範囲を設定する。
API情報
API情報は、Restfulインターフェースに対応するための詳細情報を意味し、APIとMethodに区分される。
API Information Management > API Informationで登録する。
1. API
URI Path別に登録され、状態管理の対象になる。下位に多数のMethod情報を構成できる。
登録プロセス
- 左のツリーに定義済みのドメイン情報が表示され、右にはAPIリストと詳細情報が表示される。
当該ドメインでマウス右クリック後、
Add API Informationを選択してAPI情報を登録する。 - API ID、API名、API状態コード、URIパスなどの基本情報を設定する。
構成項目
☑基本情報
- API Status Code : APIサービスの現在の状態
| 設定値 | 説明 |
|---|---|
| CREATED | 当該APIが作成状態であることを意味 |
| PUBLISHED | 当該APIが使用できる状態であることを意味 |
| BLOCKED | 当該APIが中止状態であることを意味 |
| DEPRECATED | 当該APIがこれ以上提供されないことを意味 |
- Apply Date : 当該APIを適用する日付。当日から実行する場合、今日より過去の日付を登録する。
☑ 追加情報
- Encryption Method : APIの暗号・復号化方式を設定する。暗号・復号化を参照する。
- Sending/Receiving Encryption Y/N : 暗号化方式が「全電文暗号・復号化」の場合に表現される。
| 設定値 | 説明 |
|---|---|
| Bi-directional | 送信する際に、暗号化、受信する際に、復号化する。 |
| Send | 送信する際のみ暗号化する。 |
| Receive | 受信する際のみ復号化する。 |
- HTTP Header Process Program ID : HTTPヘッダーを処理するプログラム。カスタマイズを参照する。
2. Method
Method情報は、RESTful方式のインターフェースを処理するための設定情報である。
登録プロセス
API別6つのMethod情報(GET、POST、PUT、DELETE、PATCH、HEAD)を登録することができる。
- 当該APIをクリックする。
- 登録したいMethodタイプのチェックボックスをチェックしてメソッド情報を設定する。
- 登録済みのインターフェースIDを選択する。
- 選択されたインターフェースIDに登録された要求/応答パラメータが自動登録されるが、必要に応じて別の電文に変更する。
構成項目
Interface ID : 当該Methodで処理するインターフェースのIDを登録する。インターフェースIDは、オンラインインターフェース画面で登録したインターフェースでなければならない。
Request/Response Media Type : 要求と応答の際に、使用するメディアタイプを登録する。
Request Parameter : REST取引時にBXIがパラメータをどのように受信するかを定義する。(RESTインバウンド)/ REST取引時にBXIがパラメータをどのように送信するかを定義する。(RESTアウトバウンド)
Response Parameter : REST取引時にBXIがパラメータをどのように送信するかを定義する。(RESTインバウンド)/ REST取引時にBXIがパラメータをどのように受信するかを定義する。(RESTアウトバウンド)
| 設定値 | 説明 |
|---|---|
| BODY | 要求/応答ペイロードで使用されるパラメータ |
| QUERY | GETメソッドの要求URLに使用されるパラメータ |
| HEAD | カスタムヘッダーに使用されるパラメータ |
| PATH | URLパスに使用されるパラメータ |
例
REST INBOUND取引を例として説明する。
URL patternがhttp://0.0.0.0:57013/inbound001/{address}/abc/v21であるため、要求パラメータのaddressパラメータタイプをPATHと定義する必要がある。
BXIは、当該URLを外部にオープンさせ、要求を待つ。
外部から当該URLにHTTP要求すると、BXIはREST INBOUND取引を行う。
例えば、外部からcurl -X POST -d '{"name":"hong"}' -H "Content-Type:application/json" http://0.0.0.0:57013/inbound001/seoul/abc/v21でHTTP要求を行う場合、BXIは定義された要求パラメータによってname=hong、address=seoulで値を満たしてBXI内部フローを行う。
REST INBOUNDで応答パラメータは、RESTFul方式で応答をどのように返すかを意味する。
この例にはname、addressが両方ともBODYで定義されていたため、{"name":"xxx.."、"address":"xxx.."}に応答する。
もし、応答パラメータのnameがHEAD、addressはBODYでパラメータタイプが指定されている場合、応答する時、ボディ部にaddressだけが含まれ、nameはヘッダーオプションとして含まれる。
REST非同期取引
REST取引は基本的に同期取引であるが、BXIは非同期取引に対応する。非同期であるため、200の応答を受け取る。
- RESTインバウンド非同期 : RESTインバウンド非同期取引は同期応答インターフェース
1つで行う。
Interface Management > Online Interfaceで同期するかどうかをSync、応答するかどうかをResponseに設定する。(既存の同期取引と同一)API Information Management > API Informationでサーバーモードに同期するかどうかをAsyncとAPIを登録する。サーバーモードは非同期を選択した場合、応答URLと応答Methodを入力することができる。- 要求、応答パラメータを設定する。RESTインバウンド非同期で応答パラメータは、応答Method方式で応答URLにデータを伝送しようとする事実上の要求パラメータと認識すればいい。
下の図は、http://0.0.0.0:57013/inbound001/abc にPOST取引の入力を受けて内部システムに伝達した後、内部システムから受信した応答を要求トしたところではなくhttp://localhost:6020/rest/{address}にDELETE方式で要求する取引の例である。
- RESTアウトバウンド非同期 : RESTアウトバウンド非同期取引は非同期応答インターフェース
2つで行う。
Interface Management > Online Interfaceで同期するかどうかをAsync、応答するかどうかをNot response、要求区分を対内要求と要求インターフェースを登録する。(無応答のためタイマーを解除できないため要求フローからタイマー登録を除外)Interface Management > Online Interfaceで同期するかどうかをAsync、応答するかどうかをNot response、要求区分を対外要求と応答インターフェースを登録する。(無応答のためタイマーを解除できないため要求フローからタイマー登録を除外)API Information Management > API Informationでクライアントモードに同期するかどうかをAsyncとAPIを登録する。API Information Management > API Informationでサーバーモードに同期するかどうかをAsyncとAPIを登録する。(応答URL、応答パラメータは登録しない。応答Methodは変更しても実際に適用しない)
RESTアウトバウンド非同期は要求と応答が別のインターフェースで処理されるため、Log Monitoring > Transaction Historyで1回の取引当り2つの取引内訳が表示される。
RESTアウトバウンドの非同期取引はターゲットに要求を送った時、ターゲットが4番のプロセスで登録したサーバーに再要求してから応答処理ができる。