Cosminexus V9 BPM/ESB基盤 サービスプラットフォーム 開発ガイド 受付・アダプタ定義編
HTTPアダプタの定義方法について説明します。実際の設定例に基づいてHTTPアダプタの動作を確認したい場合は,「付録G HTTP受付およびHTTPアダプタを利用したビジネスプロセスの設定例」を参照してください。
実行環境でHTTPアダプタが動作するために,J2EEサーバのクラスパスにJAX-RSのライブラリ(cjjaxrs.jar)を追加します。J2EEサーバ用オプション定義ファイル(usrconf.cfg)を編集し,次の内容を記述してください。
add.class.path=<サービスプラットフォームのインストールディレクトリ>\jaxrs\lib\cjjaxrs.jar |
J2EEサーバ用オプション定義ファイル(usrconf.cfg)の詳細は,マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.3 usrconf.cfg(J2EEサーバ用オプション定義ファイル)」を参照してください。
ここでは,HTTPアダプタで使用する電文フォーマットの種類,形式,および作成方法について説明します。
なお,認証フローを使用してアクセストークンを取得する場合の要求電文および応答電文の設定については,マニュアル「サービスプラットフォーム 解説」の「2.14.15 OAuth 2.0に対応したサービスへのアクセス」を参照してください。
HTTPアダプタで使用する電文フォーマットの種類を次の表に示します。
表3-93 電文フォーマットの種類
大分類 | 中分類 | 小分類 | 説明 | 編集可否 |
---|---|---|---|---|
要求電文フォーマット | ヘッダ変数用(HTTPアダプタ用) | 要求電文フォーマット(ヘッダ変数用) | HTTPリクエストヘッダに関する情報などを指定するヘッダ割当変数の電文フォーマットです。 サービスプラットフォームが提供する次のスキーマファイルを使用します。
|
× |
クエリ用詳細電文フォーマット | クエリの情報を設定する電文フォーマットです。 サービスプラットフォームが提供するスキーマファイルはadphttp_header_query_detail.xsdです。 パラメタ設定部分を編集して使用します。 |
△ | ||
ヘッダ変数用(JSON-XML変換用) | 要求電文フォーマット(ヘッダ変数用) | JSON-XML変換の定義を設定する電文フォーマットです。 サービスプラットフォームが提供する次のスキーマファイルを使用します。
|
× | |
ボディ変数用(HTTPアダプタ用) | ファイルデータ用電文フォーマット | ファイルデータだけ送信する場合など,HTTPリクエストのボディ部分を扱わない場合に設定する電文フォーマットです。 サービスプラットフォームが提供するスキーマファイルはadphttp_body_empty.fdxです。 |
× | |
フォームデータ用電文フォーマット | HTTPリクエストボディにフォームデータを設定する場合に使用する電文フォーマットです。 サービスプラットフォームが提供するスキーマファイルはadphttp_body_form-data.xsdです。 OAuth 2.0が対応する認証フローを使用して,アクセストークンを取得する場合は,サービスプラットフォームが提供する次のスキーマファイルを使用します。
|
△ | ||
パススルーモード用電文フォーマット | パススルーモードで任意のHTTPリクエストボディを送信したい場合に作成します。 サービスプラットフォームではスキーマファイルを提供していません。 |
○ | ||
ボディ変数用(JSON-XML変換用) | 要求電文フォーマット(ボディ変数用) | JSON変換ツールで作成した情報を設定したHTTPリクエストボディを送信したい場合に作成します。 サービスプラットフォームではスキーマファイルを提供していません。 |
○ | |
応答電文フォーマット | ヘッダ変数用(HTTPアダプタ用) | 応答電文フォーマット(ヘッダ変数用) | 受信したHTTPレスポンスヘッダおよびステータスラインを割り当てるための電文フォーマットです。 サービスプラットフォームが提供する次のスキーマファイルを使用します。
|
× |
ボディ変数用(HTTPアダプタ用) | ファイルデータ用電文フォーマット | ファイルデータだけ受信する場合など,HTTPレスポンスのボディ部分を扱わない場合に設定する電文フォーマットです。 サービスプラットフォームが提供するスキーマファイルはadphttp_body_empty.fdxです。 |
× | |
パススルーモード用電文フォーマット | パススルーモードで任意のHTTPレスポンスボディを受信したい場合に作成します。 サービスプラットフォームではスキーマファイルを提供していません。 |
○ | ||
ボディ変数用(JSON-XML変換用) | 応答電文フォーマット(ボディ変数用) | JSON変換ツールで作成した情報を設定したHTTPレスポンスボディを送信したい場合に作成します。 サービスプラットフォームではスキーマファイルを提供していません。 |
○ | |
フォルト電文フォーマット | 任意のステータスコードを受信したときにフォルト情報に割り当てるための電文フォーマットです。 サービスプラットフォームが提供するスキーマファイルはadphttp_fault.xsdです。 |
× |
ここでは,HTTPアダプタで使用する要求電文フォーマット,応答電文フォーマット,およびフォルト電文フォーマットの形式について説明します。
表3-94 要求電文フォーマット(ヘッダ変数用(HTTPアダプタ用))
タグ名 | 種別 | 出現回数 | 説明 | ||||
---|---|---|---|---|---|---|---|
<http-header-request> | − | 1回 | − | ||||
|
<request-id> | string | 0または1回 | 受付で生成されたリクエストIDを設定します。 作業フォルダ内のファイルデータを送信する場合や作業フォルダにファイルを受信する場合に必要です。 |
|||
<method>※1 | string | 0または1回 | リクエストラインのHTTPメソッドを指定します。 指定できる値は次のどれかです。
|
||||
<uri-scheme-authority>※1 | string | 0または1回 | リクエストラインのURIのスキームとオーソリティ(URIのポート番号まで)を指定します。値のURLエンコードは行われません。 URIを組み立てる際の最初の文字列となります。 |
||||
<uri-path>※1 | string | 0または1回 | リクエストラインのURIのパス部分を指定します。 uri-scheme-authority要素の直後に連結されるため,指定文字列の先頭は原則として「/」で始める必要があります。 ルートパス("/")の場合は指定を省略できます。 |
||||
<uri-query> | string | ※2 | リクエストラインのクエリを指定します。 | ||||
<http-header-Authorization>※1 | string | 0または1回 | HTTPリクエストヘッダのAuthorizationヘッダに対応する認証情報を指定します。 type属性には認証種別を指定します。
|
||||
<http-header-Content-Type>※1 | string | 0または1回 | HTTPリクエストヘッダのContent-Typeヘッダに対応するメディアタイプを指定します。 charset属性には,Content-Typeヘッダのcharset属性に対応する文字コードを指定します。 |
||||
<http-header-Cookies> | − (any) |
0または1回 | HTTPリクエストのCookie情報を指定します。Cookie要素を一括設定するか個別設定するかによって使用するスキーマファイルが異なります。
|
||||
<Cookie> | string | 0回以上 | HTTPリクエストのCookie情報を,Cookie情報ごとにHTTPレスポンスから渡されるSet-Cookieヘッダの形式で指定します。 name属性には,HTTPレスポンスのSet-CookieヘッダのCookie名を指定します。 host属性には,HTTPレスポンスのSet-CookieヘッダのCookieを送信するサーバのホスト(ドメイン)名を指定します。 path属性には,HTTPレスポンスのSet-CookieヘッダのCookieを送信するサーバのパスを指定します。 Cookie要素の各属性値や要素の値は,引き継ぎ対象のCookie情報が格納された応答電文(ヘッダ)のCookie要素の値をそのまま使用してください。任意の値を設定した場合の動作は保証されません。 |
||||
<http-header> | − | 0または1回 | HTTPヘッダ情報を指定します。 | ||||
任意の要素※1 | any | 0から1,024回 | HTTPヘッダ情報を,要素名にヘッダフィールド名,要素値にヘッダフィールド値の形式で指定します。 階層構造や属性値などが指定された場合は無視されます。また,特定のヘッダ情報は指定しても無視されます。詳細はマニュアル「サービスプラットフォーム 解説」の「2.14.3 HTTPリクエストと要求電文の関係」を参照してください。 |
||||
<http-part> | − | 0または1回 | パートのメタ情報を指定します。 | ||||
|
<message> | − | 0または1回 | 要求電文(ボディ)に関する情報を指定します。 | |||
<binding>※1、※3 | string | 1回 | 要求電文(ボディ)の処理方法として次のどれかを指定します。
|
||||
<files> | − | 0または1回 | HTTPリクエストで送信するファイル情報を指定します。 この要素を指定した場合,要求電文(ボディ)が設定されていても,この要素での指定が優先されます。 |
||||
|
<file> | − | 0回以上 | 送信するファイルに関する情報を指定します。 この要素を2つ以上指定した場合は,最初に取得された要素1つが有効になります。 |
|||
|
<input-folder-name>※1 | string | 1回 | 送信対象ファイルが格納されているフォルダとして,次のどちらかを指定します。
|
|||
<local-file-name>※1 | string | 1回 | 送信対象のファイル名を指定します。
|
||||
<output-folder-name>※1 | string | 0または1回 | HTTPレスポンス時にダウンロードファイルを出力するフォルダとして,次のどちらかを指定します。
|
||||
<output-sub-folder> | string | 0または1回 | HTTPレスポンス時にダウンロードファイルを出力する共通フォルダのサブフォルダを設定します。
|
表3-95 クエリ用詳細電文フォーマット(ヘッダ変数用(HTTPアダプタ用))
タグ名 | 種別 | 出現回数 | 説明 | |
---|---|---|---|---|
<uri-query> | − | 0または1回 | − | |
任意の要素※ | string | 0から1,024回 | リクエストラインのクエリの詳細情報を設定します。 |
表3-96 要求電文フォーマット(ヘッダ変数用(JSON-XML変換用))
タグ名 | 種別 | 出現回数※1 | 説明 | |
---|---|---|---|---|
<custom-adapter-request> | − | 1回 | − | |
<json-transfer> | boolean | 0または1回 | HTTPアダプタのリクエスト処理時に,JSON-XML変換するかどうかを指定するタグです。指定値は次のどちらかです。 true:JSON-XML変換します。※2 false:JSON-XML変換しません。
|
表3-97 ファイルデータ用電文フォーマット(ボディ変数用(HTTPアダプタ用))
単純内容要素 | 種別 | 出現回数 | 説明 | |
---|---|---|---|---|
<http-body-common-empty> | − | 1回 | − | |
<data> | string | 0回以上 | 空のデータを渡す要素です。この要素は省略できます。 |
表3-98 フォームデータ用電文フォーマット(ボディ変数用(HTTPアダプタ用))
タグ名 | 種別 | 出現回数 | 説明 | |
---|---|---|---|---|
<http-body-form-data> | − | 1回 | − | |
任意の要素 | string | 0回以上 | 任意の要素を指定します。 |
表3-99 フォームデータ用電文フォーマット(ボディ変数用(HTTPアダプタ用))(OAuth 2.0の認証フローとしてassertionをHTTPアダプタで作成する場合)
タグ名 | 種別 | 出現回数 | 説明 | |||
---|---|---|---|---|---|---|
<http-body-form-data> | − | 1回 | − | |||
|
<grant_type> | string | 1回 | OAuth 2.0の認証フロー(JWT Bearer Token Flow)を使用する場合に,グラントタイプに固定の文字列「urn:ietf:params:oauth:grant-type:jwt-bearer」を設定します。 | ||
任意の要素 | string | 0または1回 | 任意の要素を指定します。 | |||
<auth-info>※1,※2 | − | 1回 | auth-info配下のタグに認証情報を設定します。 | |||
|
<claim> | − | 1回 | − | ||
|
<iss> | string | 0または1回 | JWT発行者の識別子を設定します。 | ||
<aud> | string | 0または1回 | JWT利用者の識別子を設定します。 | |||
<sub> | string | 0または1回 | JWT発行者のユーザ識別子を設定します。 | |||
<exp> | string | 0または1回 | JWTの有効期限を設定します。 | |||
<nbf> | string | 0または1回 | JWTが有効になる日時を設定します。 | |||
<iat> | string | 0または1回 | JWTを発行した時刻を設定します。 | |||
<jti> | string | 0または1回 | JWTのための一意な識別子を設定します。 | |||
任意の要素 | string | 0または1回 | 任意の要素を指定します。 | |||
<header> | − | 1回 | − | |||
|
<alg> | string | 1回 | JWTクレームセットの暗号化に使用するアルゴリズム(JWA RFC7518で定義された設定値)を設定します。 | ||
任意の要素 | string | 0または1回 | 任意の要素を指定します。 | |||
<secretkey> | string | 1回 | 公開鍵認証情報登録・更新コマンドで登録した鍵IDを設定します。※3 鍵IDに対応する秘密鍵ファイルを署名時に使用します。 |
|||
<signature> | string | 1回 | 電子署名に使用するJava暗号化アーキテクチャ標準アルゴリズム名(Signatureアルゴリズム)を設定します。 | |||
<keytype> | string | 1回 | 秘密鍵を変換するJava暗号化アーキテクチャ標準アルゴリズム名(KeyFactoryアルゴリズム)を設定します。 秘密鍵が対応するアルゴリズムを設定します。 |
表3-100 フォームデータ用電文フォーマット(ボディ変数用(HTTPアダプタ用))(OAuth 2.0の認証フローとしてHTTPアダプタ以外の発行者が作成したassertionをHTTPアダプタで使用する場合)
タグ名 | 種別 | 出現回数 | 説明 | |
---|---|---|---|---|
<http-body-form-data> | − | 1回 | − | |
|
<grant_type> | string | 1回 | OAuth 2.0の認証フロー(JWT Bearer Token Flow)を使用する場合に,グラントタイプに固定の文字列「urn:ietf:params:oauth:grant-type:jwt-bearer」を設定します。 |
<assertion> | string | 1回 | JSON Web Tokenを設定します。 assertionをHTTPアダプタで作成しない場合に,発行者が作成したJSON Web Tokenをassertionに設定します。 |
|
任意の要素 | string | 0または1回 | 任意の要素を指定します。 |
表3-101 フォームデータ用電文フォーマット(ボディ変数用(HTTPアダプタ用))(OAuth 2.0の認証フローとしてResource Owner Password Credentials Flowを選択する場合)
タグ名 | 種別 | 出現回数 | 説明 | |
---|---|---|---|---|
<http-body-form-data> | − | 1回 | − | |
|
<grant_type> | string | 1回 | OAuth 2.0の認証フローとしてResource Owner Password Credentials Flowを選択する場合に,グラントタイプに固定の文字列「password」を設定します。 |
<username> | string | 1回 | リソースオーナーのユーザ名を設定します。 パスワード認証情報登録・更新コマンドで登録したユーザ名を指定します。※ |
|
任意の要素 | string | 0または1回 | 任意の要素を指定します。 |
表3-102 応答電文フォーマット(ヘッダ変数用)(HTTPアダプタ用)
タグ名 | 種別 | 出現回数 | 説明 | ||||
---|---|---|---|---|---|---|---|
<http-header-response> | − | 1回 | − | ||||
|
<request-id> | string | 0または1回 | 要求電文で指定したリクエストIDが設定されます。 要求電文で指定しなかった場合,この要素は生成されません。 |
|||
<status-code> | string | 1回 | HTTPレスポンスのステータスラインのステータスコードが設定されます。 | ||||
< reason-phrase> | string | 1回 | ステータスラインの理由フレーズ部分が設定されます。 | ||||
<http-header-Content-Type> | string | 0または1回 | Content-Typeヘッダのメディアタイプが設定されます。 | ||||
<http-header-Cookies> | − (any) |
1回 | HTTPレスポンスのSet-Cookieヘッダが設定されます。Cookie要素を一括設定するか個別に設定するかによって使用するスキーマファイルが異なります。
|
||||
<Cookie> | string | 0回以上 | HTTPレスポンスのSet-Cookieヘッダが,Cookie情報ごとに格納されます。 name属性には,HTTPレスポンスのSet-CookieヘッダのCookie名が設定されます。 host属性には,HTTPレスポンスのSet-CookieヘッダのCookieを送信するサーバのホスト(ドメイン)名が設定されます。 path属性には,HTTPレスポンスのSet-CookieヘッダのCookieを送信するサーバのパスが設定されます。 |
||||
<http-header> | − | 1回 | HTTPレスポンスヘッダが格納されます。 | ||||
任意の要素 | any | 0回以上 | HTTPヘッダ情報が,要素名にヘッダフィールド名,要素値にヘッダフィールド値の形式で設定されます。 | ||||
<http-body> | − | 1回 | HTTPレスポンスボディの情報が設定されます。 | ||||
<output-folder-name> | string | 0または1回 | HTTPレスポンスでダウンロードしたファイルの出力先フォルダが設定されます。 出力先フォルダは要求電文フォーマット(ヘッダ変数用)のoutput-folder-name要素で指定した値と同じです。
|
||||
<http-part> | − | 1回 | パートのメタ情報が設定されます。 | ||||
|
<files> | − | 0または1回 | HTTPレスポンスで受信するファイル情報が設定されます。 | |||
|
<file> | − | 1回 | 受信するファイルに関する情報が格納されます。 | |||
|
<local-file-name> | string | 1回 | 共通フォルダまたは作業フォルダに出力されたファイル名が設定されます。
|
|||
<file-name> | string | 0または1回 | Content-Dispositionヘッダのfilename属性に指定されている値が設定されます。 filename属性がない場合,この要素は生成されません。 |
||||
<context> | − | 1回 | HTTPアダプタの実行情報が格納されます。 | ||||
|
<adapter-name> | string | 1回 | このHTTPレスポンスの基になったHTTPリクエストを送信したアダプタの名称が設定されます。 | |||
<operation-name> | string | 1回 | このHTTPレスポンスの基になったHTTPリクエストを送信したオペレーションの名称が設定されます。 | ||||
<request-method> | string | 1回 | このHTTPレスポンスの基になったHTTPリクエストのメソッド種別が設定されます。 | ||||
<request-uri> | string | 1回 | このHTTPレスポンスの基になったHTTPリクエストのURI(SchemeおよびUserInfoを除くAuthorization,Path)が設定されます。 | ||||
<access-token> | string | 0または1回 | OAuth 2.0の認証フロー実行時に認可サーバから返されるアクセストークンが設定されます。 |
表3-103 フォルト電文フォーマット
タグ名 | 種別 | 出現回数 | 説明 | ||
---|---|---|---|---|---|
<http-fault> | − | 1回 | − | ||
|
<status-code> | string | 1回 | HTTPレスポンスのステータスラインのステータスコードが設定されます。 | |
< reason-phrase> | string | 1回 | ステータスラインの理由フレーズ部分が設定されます。 | ||
<http-header> | − | 1回 | HTTPレスポンスヘッダが格納されます。 | ||
任意の要素 | string | 0回以上 | HTTPヘッダ情報が,要素名にヘッダフィールド名,要素値にヘッダフィールド値の形式で設定されます。 | ||
<context> | − | 1回 | HTTPアダプタの実行情報が格納されます。 | ||
|
<adapter-name> | string | 1回 | このHTTPレスポンスの基になったHTTPリクエストを送信したアダプタの名称が設定されます。 | |
<operation-name> | string | 1回 | このHTTPレスポンスの基になったHTTPリクエストを送信したオペレーションの名称が設定されます。 | ||
<request-method> | string | 1回 | このHTTPレスポンスの基になったHTTPリクエストのメソッド種別が設定されます。 | ||
<request-uri> | string | 1回 | このHTTPレスポンスの基になったHTTPリクエストのURI(SchemeおよびUserInfoを除くAuthorization,Path)が設定されます。 |
HTTPアダプタで使用する電文フォーマットの作成方法について説明します。
サービスプラットフォームが提供する電文フォーマットのXMLスキーマは,「<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\HTTP\schema」に格納されています。編集する場合はフォルダごと任意の場所にコピーしてから編集してください。
次の電文フォーマットの作成方法を次に示します。
cscjson2xsd -in <入力JSONファイルのパス> -out <出力XSDファイルのパス> [-f <JSON-XML変換定義ファイルのパス>]
HTTPアダプタを定義する場合の手順を次に示します。
作成および編集する定義ファイルの種類を次に示します。
なお,これらの定義ファイルの作成および編集は任意です。省略した場合は各定義ファイルのデフォルト値が使用されます。
各定義ファイルの作成手順および編集手順を次に示します。
HTTPアダプタ定義ファイルは,サービスプラットフォームが提供するテンプレートファイルを利用して編集します。
HTTPアダプタ定義ファイルの編集手順を示します。
HTTPアダプタ実行環境プロパティファイルは,HTTPアダプタを開始する際に実行環境に反映されます。このため,HTTPアダプタ実行環境プロパティファイルの内容を変更する場合は,いったんHTTPアダプタを停止する必要があります。
HTTPアダプタ実行環境共通プロパティファイルは,HTTPアダプタを開始する際に実行環境に反映されます。このため,HTTPアダプタ実行環境共通プロパティファイルの内容を変更する場合は,いったんHTTPアダプタを停止する必要があります。
JSON-XML変換定義ファイルは,サービスプラットフォームが提供するテンプレートファイルを独自定義ファイルとして追加し,編集します。ファイルの内容については,ボディ変数用の電文フォーマットの作成時に使用したJSON-XML変換定義ファイルと合わせてください。
JSON-XML変換定義ファイルの編集手順を示します。
プロキシサーバやコネクション継続などの設定が必要な場合は,システムプロパティファイル(usrconf.cfg)で設定します。HTTPアダプタで設定するプロパティについては,マニュアル「サービスプラットフォーム 解説」の「2.14.6 プロキシサーバを経由した通信」およびマニュアル「サービスプラットフォーム 解説」の「2.14.7 コネクション継続(Keep-Alive)を使用した通信」を参照してください。
HTTPアダプタを利用する場合,ビジネスプロセスのサービス呼出アクティビティ,および必要に応じてフォルト処理の設定が必要です。
サービス呼出アクティビティとフォルト処理の設定方法を次に示します。
HTTPアダプタを呼び出すためのサービス呼出アクティビティを定義します。サービス呼出アクティビティの定義方法については,マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「5.6.4 サービス呼出アクティビティ」を参照してください。
[サービス呼出アクティビティ]ダイアログの設定内容を次に示します。
項目 | 設定値 | |
---|---|---|
アクティビティ名 | 任意の名称を設定します。 | |
サービス名 | HTTPアダプタの新規追加時に設定したサービス名を指定します。 | |
オペレーション名 | 「(3) サービスアダプタ定義画面での操作」で設定したオペレーション名を指定します。 | |
要求電文 | ボディ割当変数 | 送信するデータ形式に応じて次のように指定します。 |
ヘッダ割当変数※2 | Cookieの設定方法に応じて次のように指定します。
|
|
応答電文 | ボディ割当変数 | 受信するデータ形式に応じて次のように指定します。
|
ヘッダ割当変数※2 | Cookieの設定方法に応じて次のように指定します。
|
|
割当相関セット群 | 設定しません。 |
正常系として処理できないステータスコードやフォルトに変換したシステム例外をビジネスプロセスでエラーとして処理する場合は,サービス呼出アクティビティや上位のスコープにフォルト処理を定義します。フォルト処理の定義方法については,マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「5.4.4 フォルト処理を定義する」を参照してください。
[フォルト処理の割当]ダイアログの設定内容を次に示します。
項目 | 設定値 |
---|---|
割当変数 |
|
遷移先 | フォルトが発生した場合に遷移する任意のアクティビティを指定します。 |
All Rights Reserved. Copyright (C) 2012, 2019, Hitachi, Ltd.