Hitachi

Cosminexus V11 BPM/ESB基盤 サービスプラットフォーム 開発ガイド 受付・アダプタ定義編


3.3.13 HTTPアダプタを定義する

HTTPアダプタの定義方法について説明します。実際の設定例に基づいてHTTPアダプタの動作を確認したい場合は,「付録G HTTP受付およびHTTPアダプタを利用したビジネスプロセスの設定例」を参照してください。

〈この項の構成〉

(1) J2EEサーバ用オプション定義ファイルの設定

J2EEサーバ用オプション定義ファイルの設定は,J2EEサーバの互換モードによって異なります。

J2EEサーバ用オプション定義ファイル(usrconf.cfg)の詳細は,マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.2.2 usrconf.cfg(J2EEサーバ用オプション定義ファイル)」を参照してください。

(2) 電文フォーマットの作成

ここでは,HTTPアダプタで使用する電文フォーマットの種類,形式,および作成方法について説明します。

なお,認証フローを使用してアクセストークンを取得する場合の要求電文および応答電文の設定については,マニュアル「サービスプラットフォーム 解説」の「2.15.16 OAuth 2.0に対応したサービスへのアクセス」を参照してください。

(a) 電文フォーマットの種類

HTTPアダプタで使用する電文フォーマットの種類を次の表に示します。

表3‒96 電文フォーマットの種類

大分類

中分類

小分類

説明

編集可否

要求電文フォーマット

ヘッダ変数用(HTTPアダプタ用)

要求電文フォーマット(ヘッダ変数用)

HTTPリクエストヘッダに関する情報などを指定するヘッダ割当変数の電文フォーマットです。

サービスプラットフォームが提供する次のスキーマファイルを使用します。

  • adphttp_header_request1.xsd

    Cookie要素を一括設定する場合に使用します。

  • adphttp_header_request2.xsd

    Cookie要素を個別設定する場合に使用します。

どちらのスキーマファイルもadphttp_header_query_detail.xsdを内包(include)します。

×

クエリ用詳細電文フォーマット

クエリの情報を設定する電文フォーマットです。

サービスプラットフォームが提供するスキーマファイルはadphttp_header_query_detail.xsdです。

パラメタ設定部分を編集して使用します。

ヘッダ変数用(JSON-XML変換用)

要求電文フォーマット(ヘッダ変数用)

JSON-XML変換の定義を設定する電文フォーマットです。

サービスプラットフォームが提供する次のスキーマファイルを使用します。

  • adp_custom_request.xsd

×

ボディ変数用(HTTPアダプタ用)

ファイルデータ用電文フォーマット

ファイルデータだけ送信する場合など,HTTPリクエストのボディ部分を扱わない場合に設定する電文フォーマットです。

サービスプラットフォームが提供するスキーマファイルはadphttp_body_empty.fdxです。

×

フォームデータ用電文フォーマット

HTTPリクエストボディにフォームデータを設定する場合に使用する電文フォーマットです。

サービスプラットフォームが提供するスキーマファイルはadphttp_body_form-data.xsdです。

OAuth 2.0が対応する認証フローを使用して,アクセストークンを取得する場合は,サービスプラットフォームが提供する次のスキーマファイルを使用します。

  • adphttp_body_form-data_jwt_assertion1.xsd

    OAuth 2.0の認証フローとしてJWT Bearer Token Flowを使用し,assertionをHTTPアダプタで作成する場合は,この電文フォーマットを使用します。

  • adphttp_body_form-data_jwt_assertion2.xsd

    OAuth 2.0の認証フローとしてJWT Bearer Token Flowを使用し,HTTPアダプタ以外の発行者が作成したassertionをHTTPアダプタで使用する場合は,この電文フォーマットを使用します。

  • adphttp_body_form-data_password.xsd

    OAuth 2.0の認証フローとしてResource Owner Password Credentials Flowを選択する場合は,この電文フォーマットを使用します。

各スキーマファイルは,パラメタ設定部分を編集して使用します。

パススルーモード用電文フォーマット

パススルーモードで任意のHTTPリクエストボディを送信したい場合に作成します。

サービスプラットフォームではスキーマファイルを提供していません。

ボディ変数用(JSON-XML変換用)

要求電文フォーマット(ボディ変数用)

JSON変換ツールで作成した情報を設定したHTTPリクエストボディを送信したい場合に作成します。

サービスプラットフォームではスキーマファイルを提供していません。

応答電文フォーマット

ヘッダ変数用(HTTPアダプタ用)

応答電文フォーマット(ヘッダ変数用)

受信したHTTPレスポンスヘッダおよびステータスラインを割り当てるための電文フォーマットです。

サービスプラットフォームが提供する次のスキーマファイルを使用します。

  • adphttp_header_response1.xsd

    Set-Cookie要素を一括設定する場合に使用します。

  • adphttp_header_response2.xsd

    Set-Cookie要素を個別設定する場合に使用します。

×

ボディ変数用(HTTPアダプタ用)

ファイルデータ用電文フォーマット

ファイルデータだけ受信する場合など,HTTPレスポンスのボディ部分を扱わない場合に設定する電文フォーマットです。

サービスプラットフォームが提供するスキーマファイルはadphttp_body_empty.fdxです。

×

パススルーモード用電文フォーマット

パススルーモードで任意のHTTPレスポンスボディを受信したい場合に作成します。

サービスプラットフォームではスキーマファイルを提供していません。

ボディ変数用(JSON-XML変換用)

応答電文フォーマット(ボディ変数用)

JSON変換ツールで作成した情報を設定したHTTPレスポンスボディを送信したい場合に作成します。

サービスプラットフォームではスキーマファイルを提供していません。

フォルト電文フォーマット

任意のステータスコードを受信したときにフォルト情報に割り当てるための電文フォーマットです。

サービスプラットフォームが提供するスキーマファイルはadphttp_fault.xsdです。

×

(凡例)

○:ユーザが作成します。

△:必要に応じて編集できます。

×:編集できません。編集した場合の動作は保証されません。

(b) 電文フォーマットの形式

ここでは,HTTPアダプタで使用する要求電文フォーマット,応答電文フォーマット,およびフォルト電文フォーマットの形式について説明します。

●要求電文フォーマット(ヘッダ変数用(HTTPアダプタ用))(要求電文フォーマット(ヘッダ変数用))

ビジネスプロセスからHTTPアダプタに渡すヘッダ変数の要求電文フォーマットを次に示します。この電文フォーマットのファイル名は「adphttp_header_request1.xsd」または「adphttp_header_request2.xsd」です。名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/header_request」です。

表3‒97 要求電文フォーマット(ヘッダ変数用(HTTPアダプタ用))

タグ名

種別

出現回数

説明

<http-header-request>

1回

<request-id>

string

0または1回

受付で生成されたリクエストIDを設定します。

作業フォルダ内のファイルデータを送信する場合や作業フォルダにファイルを受信する場合に必要です。

<method>※1

string

0または1回

リクエストラインのHTTPメソッドを指定します。

指定できる値は次のどれかです。

  • GET

  • HEAD

  • POST

  • OPTIONS

  • PUT

  • DELETE

上記以外の値を指定した場合の動作は保証されません。

<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属性には認証種別を指定します。

  • 認証情報を送信する場合

    type属性にrawを指定し,この要素にはAuthorizationヘッダのヘッダフィールド値を指定します。

  • 認証情報を送信しない場合

    type属性にnoneを指定します。この要素に値を指定しても無視されます。HTTPリクエストヘッダにはAuthorizationヘッダが設定されません。

  • ベーシック認証の認証情報を送信する場合

    type属性にbasicを指定し,この要素にはHTTPアダプタアカウント定義ファイルに登録したユーザ名を指定します。

上記以外の値を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要素を一括設定する場合

    スキーマファイルはadphttp_header_request1.xsdを使用します。any型でCookie情報を指定します。

  • Cookie要素を個別設定する場合

    スキーマファイルはadphttp_header_request2.xsdを使用します。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.15.3 HTTPリクエストと要求電文の関係」を参照してください。

<http-part>

0または1回

パートのメタ情報を指定します。

<message>

0または1回

要求電文(ボディ)に関する情報を指定します。

<binding>※1,※3

string

1回

要求電文(ボディ)の処理方法として次のどれかを指定します。

  • none

    要求電文(ボディ)がない状態でHTTPリクエストを送信します。この値を指定した場合,HTTPリクエストのContent-Typeヘッダは設定されません。

  • raw

    パススルーモードとして,要求電文(ボディ)の内容をそのまま送信します。HTTPリクエストのContent-Typeヘッダには,http-header-Content-Type要素で指定したメディアタイプおよび文字コードが設定されます。

  • form-data

    ノーマルモードとして,要求電文(ボディ)をフォームデータの形式に変換して送信します。HTTPリクエストのContent-Typeヘッダには,application/x-www-form-urlencodedが設定されます。文字コードには,http-header-Content-Type要素で指定した文字コードが設定されます。

  • 上記以外の場合

    システム例外が発生します。

<files>

0または1回

HTTPリクエストで送信するファイル情報を指定します。

この要素を指定した場合,要求電文(ボディ)が設定されていても,この要素での指定が優先されます。

<file>

0回以上

送信するファイルに関する情報を指定します。

この要素を2つ以上指定した場合は,最初に取得された要素1つが有効になります。

<input-folder-name>※1

string

1回

送信対象ファイルが格納されているフォルダとして,次のどちらかを指定します。

  • 作業フォルダの場合

    空文字を指定します(空文字列を指定してもエラーになりません)。

  • 共通フォルダの場合

    共通フォルダ定義名を指定します。

また,common属性には,送信対象ファイルが存在するフォルダを識別するための次の値を指定します。

  • 作業フォルダの場合

    「common="false"」を指定します。

  • 共通フォルダの場合

    「common="true"」を指定します。

<local-file-name>※1

string

1回

送信対象のファイル名を指定します。

  • input-folder-name要素で作業フォルダを指定した場合

    作業フォルダ直下の中間ファイル名を指定します。

    パス変更に関係する指定(/../など)が含まれる場合,エラーになります。

  • input-folder-name要素で共通フォルダを指定した場合

    共通フォルダルート配下のファイル名を指定します。

    共通フォルダルートより上位のパスを指定した場合,エラーになります。

    相対パスの先頭のファイル区切り文字(/)は省略できます。

    サブフォルダを使用する場合は,共通フォルダルートからファイル名までの相対パスを指定してください。

指定した名称のファイルが存在しない場合はシステム例外が発生します。

<output-folder-name>※1

string

0または1回

HTTPレスポンス時にダウンロードファイルを出力するフォルダとして,次のどちらかを指定します。

  • 作業フォルダの場合

    空文字を指定します(空文字列を指定してもエラーになりません)。

  • 共通フォルダの場合

    共通フォルダ定義名を指定します。

また,common属性には,送信対象ファイルが存在するフォルダを識別するための次の値を指定します。

  • 作業フォルダの場合

    「common="false"」を指定します。

  • 共通フォルダの場合

    「common="true"」を指定します。

<output-sub-folder>

string

0または1回

HTTPレスポンス時にダウンロードファイルを出力する共通フォルダのサブフォルダを設定します。

  • 共通フォルダルートからサブフォルダまでの相対パスを指定します。

  • 共通フォルダルートより上位のパスを指定した場合,実行時にエラーになります。

  • 共通フォルダルートからの相対パスで指定したサブフォルダが存在しない場合,サブフォルダを作成します。

  • 相対パスの先頭および末尾のファイル区切り文字(/)は省略できます。

  • output-folder-name要素で,common属性にtrue以外の値を指定した場合,この要素の値は無視されます。

(凡例)

−:該当する項目はありません。

注※1

要素の指定がない場合は,HTTPアダプタ実行環境プロパティファイルまたはHTTPアダプタ実行環境共通プロパティファイルの指定が有効になります。要求電文とプロパティファイルの対応関係については,マニュアル「サービスプラットフォーム 解説」の「2.15.13 要求電文(ヘッダ)とHTTPアダプタ実行環境(共通)プロパティファイルのパラメタの対応関係」を参照してください。

注※2

include先のクエリ用詳細電文フォーマットの指定に従います。

注※3

JSON-XML変換をする場合,HTTPアダプタ実行環境プロパティファイルのadphttp.request.part.message.bindingプロパティで「raw」以外の値を設定しているときは,binding要素の値に「raw」を指定してください。http-header-Content-type要素の値については,「application/json」の設定を推奨します。

●要求電文フォーマット(ヘッダ変数用(HTTPアダプタ用))(クエリ用詳細電文フォーマット)

要求電文フォーマット(ヘッダ変数用)に内包(include)されるクエリ用詳細電文フォーマットを次に示します。この電文フォーマットのファイル名は「adphttp_header_query_detail.xsd」です。名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/header_request」です。

表3‒98 クエリ用詳細電文フォーマット(ヘッダ変数用(HTTPアダプタ用))

タグ名

種別

出現回数

説明

<uri-query>

0または1回

任意の要素

string

0から1,024回

リクエストラインのクエリの詳細情報を設定します。

(凡例)

−:該当する項目はありません。

注※

要素の指定がない場合は,HTTPアダプタ実行環境プロパティファイルまたはHTTPアダプタ実行環境共通プロパティファイルの指定が有効になります。要求電文とプロパティファイルの対応関係については,マニュアル「サービスプラットフォーム 解説」の「2.15.13 要求電文(ヘッダ)とHTTPアダプタ実行環境(共通)プロパティファイルのパラメタの対応関係」を参照してください。

●要求電文フォーマット(ヘッダ変数用(JSON-XML変換用))

JSON-XML変換の定義を設定するヘッダ変数用の要求電文フォーマットを次に示します。この電文フォーマットのファイル名は,「adp_custom_request.xsd」です。名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/custom/request」です。

表3‒99 要求電文フォーマット(ヘッダ変数用(JSON-XML変換用))

タグ名

種別

出現回数※1

説明

<custom-adapter-request>

1回

<json-transfer>

boolean

0または1回

HTTPアダプタのリクエスト処理時に,JSON-XML変換するかどうかを指定するタグです。指定値は次のどちらかです。

true:JSON-XML変換します。※2

false:JSON-XML変換しません。

  • タグがあって値が「true」または「false」の場合

    指定した値が適用されます。

  • タグがあって値が「true」または「false」のどちらでもない場合

    システム例外を返します。

  • タグがあって値がない場合

    デフォルトの「false」が使用されます。

  • タグがない場合

    HTTPアダプタ定義ファイルのadphttp.request.switchover.json-transfer.modeプロパティの値が有効になります。

(凡例)

−:該当する項目はありません。

注※1

規定の出現回数を超える場合の動作は保証されません。

注※2

HTTPアダプタ定義ファイルのadphttp.request.switchover.json-transfer.modeプロパティの値に「true」が設定されていない場合,JSON-XML変換をしません。

●要求電文フォーマット(ボディ変数用(HTTPアダプタ用))(ファイルデータ用電文フォーマット)

空のHTTPメッセージボディを表すファイルデータ用電文フォーマットの形式を次に示します。この電文フォーマットのファイル名は「adphttp_body_empty.fdx」です。

表3‒100 ファイルデータ用電文フォーマット(ボディ変数用(HTTPアダプタ用))

単純内容要素

種別

出現回数

説明

<http-body-common-empty>

1回

<data>

string

0回以上

空のデータを渡す要素です。この要素は省略できます。

(凡例)

−:該当する項目はありません。

●要求電文フォーマット(ボディ変数用(HTTPアダプタ用))(フォームデータ用電文フォーマット)

ビジネスプロセスからHTTPアダプタに渡すフォームデータ用電文フォーマットを次に示します。この電文フォーマットのファイル名は「adphttp_body_form-data.xsd」です。名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/body_form_data」です。

表3‒101 フォームデータ用電文フォーマット(ボディ変数用(HTTPアダプタ用))

タグ名

種別

出現回数

説明

<http-body-form-data>

1回

任意の要素

string

0回以上

任意の要素を指定します。

(凡例)

−:該当する項目はありません。

●要求電文フォーマット(ボディ変数用(HTTPアダプタ用))(フォームデータ用電文フォーマット)(OAuth 2.0の認証フローとしてassertionをHTTPアダプタで作成する場合)

OAuth 2.0の認証フローとしてJWT Bearer Token Flowを使用し,assertionをHTTPアダプタで作成する場合の電文フォーマットを次に示します。この電文フォーマットのファイル名は「adphttp_body_form-data_jwt_assertion1.xsd」です。名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/body_form_data」です。

表3‒102 フォームデータ用電文フォーマット(ボディ変数用(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アルゴリズム)を設定します。

秘密鍵が対応するアルゴリズムを設定します。

(凡例)

−:該当する項目はありません。

注※1

設定が必要な項目および設定値は認可サーバによって異なるため,接続する認可サーバに合わせて適切な設定をする必要があります。

注※2

HTTPアダプタは,grant_type要素の設定値がurn:ietf:params:oauth:grant-type:jwt-bearerで,かつassertion要素が設定されていない場合,設定された認証情報を基に,フォームデータとしてassertionを作成します。

assertionは,次の形式で作成されます。

a.b.c

(凡例)

 a:JSON形式のヘッダ情報をBase64変換した文字列

 b:JSON形式のクレーム情報をBase64変換した文字列

 c:aとbをピリオド(.)で連結した文字列に,電子署名で使用する暗号化キーのタイプ,アルゴリズム,および秘密鍵を使用して署名し,Base64変換した文字列

作成されたassertionは,ほかのフォームデータと同様に,フォームデータとして送信されます。

注※3

公開鍵認証情報登録・更新コマンドについては,マニュアル「サービスプラットフォーム リファレンス」の「csakeyadd(公開鍵認証の秘密鍵情報の登録・更新)」を参照してください。

●要求電文フォーマット(ボディ変数用(HTTPアダプタ用))(フォームデータ用電文フォーマット)(OAuth 2.0の認証フローとしてHTTPアダプタ以外の発行者が作成したassertionをHTTPアダプタで使用する場合)

OAuth 2.0の認証フローとしてJWT Bearer Token Flowを使用し,HTTPアダプタ以外の発行者が作成したassertionをHTTPアダプタで使用する場合の電文フォーマットを次に示します。この電文フォーマットのファイル名は「adphttp_body_form-data_jwt_assertion2.xsd」です。名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/body_form_data」です。

表3‒103 フォームデータ用電文フォーマット(ボディ変数用(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回

任意の要素を指定します。

(凡例)

−:該当する項目はありません。

●要求電文フォーマット(ボディ変数用(HTTPアダプタ用))(フォームデータ用電文フォーマット)(OAuth 2.0の認証フローとしてResource Owner Password Credentials Flowを選択する場合)

OAuth 2.0の認証フローとしてResource Owner Password Credentials Flowを選択する場合の電文フォーマットを次に示します。この電文フォーマットのファイル名は「adphttp_body_form-data_password.xsd」です。名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/body_form_data」です。

表3‒104 フォームデータ用電文フォーマット(ボディ変数用(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回

任意の要素を指定します。

(凡例)

−:該当する項目はありません。

注※

パスワード認証情報登録・更新コマンドについては,マニュアル「サービスプラットフォーム リファレンス」の「csauseradd(パスワード認証のユーザ情報の登録・更新)」を参照してください。

●応答電文フォーマット(ヘッダ変数用(HTTPアダプタ用))(応答電文フォーマット(ヘッダ変数用))

HTTPアダプタが呼び出し元のビジネスプロセスに返すヘッダ変数の応答電文フォーマットを次に示します。この電文フォーマットのファイル名は「adphttp_header_response1.xsd」または「adphttp_header_response2.xsd」です。名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/header_response」です。

表3‒105 応答電文フォーマット(ヘッダ変数用)(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要素を一括設定する場合

    スキーマファイルはadphttp_header_response1.xsdを使用します。Cookie情報はany型で一括設定されます。

  • Cookie要素を個別設定する場合

    スキーマファイルはadphttp_header_response2.xsdを使用します。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要素で指定した値と同じです。

  • 作業フォルダの場合

    空文字が設定されます。

  • 共通フォルダの場合

    共通フォルダ定義名が指定されます。

また,common属性には,送信対象ファイルが存在するフォルダを識別するための値が設定されます。

  • 作業フォルダの場合

    「common="false"」が設定されます。

  • 共通フォルダの場合

    「common="true"」が設定されます。

ダウンロードするファイルがない場合,この要素は生成されません。

<http-part>

1回

パートのメタ情報が設定されます。

<files>

0または1回

HTTPレスポンスで受信するファイル情報が設定されます。

<file>

1回

受信するファイルに関する情報が格納されます。

<local-file-name>

string

1回

共通フォルダまたは作業フォルダに出力されたファイル名が設定されます。

  • 出力フォルダが共通フォルダの場合

    HTTPアダプタ内で一意となる名称で出力されたファイル名が設定されます。

    サブフォルダに出力する場合は,共通フォルダルートからの相対パスが設定されます。

  • 出力フォルダが作業フォルダの場合

    出力された中間ファイル名が設定されます。

<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の認証フロー実行時に認可サーバから返されるアクセストークンが設定されます。

(凡例)

−:該当する項目はありません。

●フォルト電文フォーマット

HTTPアダプタが呼び出し元のビジネスプロセスに返すフォルト電文フォーマットを次に示します。この電文フォーマットのファイル名は「adphttp_fault.xsd」です。名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/fault」です。

表3‒106 フォルト電文フォーマット

タグ名

種別

出現回数

説明

<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)が設定されます。

(凡例)

−:該当する項目はありません。

(c) 電文フォーマットの作成方法

HTTPアダプタで使用する電文フォーマットの作成方法について説明します。

サービスプラットフォームが提供する電文フォーマットのXMLスキーマは,「<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\HTTP\schema」に格納されています。編集する場合はフォルダごと任意の場所にコピーしてから編集してください。

次の電文フォーマットの作成方法を次に示します。

  • クエリ用詳細電文フォーマット

  • フォームデータ用電文フォーマット

  • パススルーモード用電文フォーマット

  • ボディ変数用(JSON-XML変換用)電文フォーマット

●クエリ用詳細電文フォーマットの作成
  1. XMLスキーマファイル(adphttp_header_query_detail.xsd)をXMLエディタなどで開き,次のように編集します。

    [図データ]

    xsd:any型の要素を,クエリ名をローカル名とするxsd:string型の要素に変更します。出現回数は任意に指定できます。

    注意事項

    uri-query要素直下に指定できるクエリ要素の上限は1,024個までです。1,025個以上の要素を指定した場合の動作は保証されません。

  2. XMLスキーマファイルを上書き保存します。

●フォームデータ用電文フォーマットの作成
  1. XMLスキーマファイル(adphttp_body_form-data.xsd)をXMLエディタなどで開き,次のように編集します。

    [図データ]

    xsd:any型の要素を,フォームデータのキー名をローカル名とするxsd:string型の要素に変更します。出現回数は任意に指定できます。

  2. XMLスキーマファイルを上書き保存します。

●パススルーモード用電文フォーマットの作成
  1. エディタなどで任意の電文フォーマットを作成します。

  2. 任意のファイル名で保存します。

    注意事項
    • 変数の型は,XML型,non-XML型,any型のどれでも指定できます。ただし,XML型の場合はXMLフォーマット定義ファイル,non-XML型の場合はバイナリフォーマット定義ファイルの電文フォーマットを作成する必要があります。

    • HTTPリクエストボディの文字コードはContent-Typeヘッダのcharset属性で指定できますが,HTTPアダプタでは指定された文字コードに変換しません。このため,ボディデータは要求電文(ボディ)に設定する前にあらかじめユーザ自身で文字コード変換をする必要があります。

●ボディ変数用(JSON-XML変換用)電文フォーマット

ボディ変数用の電文フォーマットは,JSON変換ツールで作成します。JSON形式の要求電文,および応答電文のサンプルファイルを入力JSONファイルとして用意し,JSON変換ツールでXSDファイルを作成してください。HTTPアダプタでJSON-XML変換の動作を変更する場合は,JSON-XML変換定義ファイルをJSON変換ツールの実行時に指定してください。

JSON変換ツールの実行形式を次に示します。

cscjson2xsd -in <入力JSONファイルのパス> -out <出力XSDファイルのパス> [-f <JSON-XML変換定義ファイルのパス>]

JSON変換ツールの詳細は,マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「13. JSON変換ツールを使用したデータ変換」を参照してください。

(3) サービスアダプタ定義画面での操作

HTTPアダプタを定義する場合の手順を次に示します。

  1. サービスアダプタ定義画面を表示します。

    サービスアダプタ定義画面の表示方法については,「3.3.1(4) サービスアダプタ定義画面の表示」を参照してください。

  2. サービスアダプタ定義画面(基本)で定義情報を設定します。

    サービスアダプタ定義画面(基本)で設定が必要な項目については,「3.3.18(13) HTTPアダプタの場合」およびマニュアル「サービスプラットフォーム リファレンス」の「1.2.2 サービスアダプタ定義画面」を参照してください。

  3. [サービスアダプタ定義(詳細)]タブをクリックします。

    サービスアダプタ定義画面(詳細)が表示されます。

  4. サービスアダプタ定義画面(詳細)で定義情報を設定します。

    サービスアダプタ定義画面(詳細)で設定が必要な項目については,「3.3.18(13) HTTPアダプタの場合」を参照してください。

(4) HTTPアダプタの定義ファイルの作成および編集

作成および編集する定義ファイルの種類を次に示します。

なお,これらの定義ファイルの作成および編集は任意です。省略した場合は各定義ファイルのデフォルト値が使用されます。

各定義ファイルの作成手順および編集手順を次に示します。

(a) HTTPアダプタ定義ファイル

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

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

  1. サービスアダプタ定義画面(詳細)の[独自定義ファイル]で「cscadphttp.properties」を選択し,[編集]ボタンをクリックします。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

注※

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

HTTPアダプタ実行環境プロパティファイルは,HTTPアダプタを開始する際に実行環境に反映されます。このため,HTTPアダプタ実行環境プロパティファイルの内容を変更する場合は,いったんHTTPアダプタを停止する必要があります。

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

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

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

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

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

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

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

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

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

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

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

HTTPアダプタ実行環境共通プロパティファイルは,HTTPアダプタを開始する際に実行環境に反映されます。このため,HTTPアダプタ実行環境共通プロパティファイルの内容を変更する場合は,いったんHTTPアダプタを停止する必要があります。

(d) JSON-XML変換定義ファイル

JSON-XML変換定義ファイルは,サービスプラットフォームが提供するテンプレートファイルを独自定義ファイルとして追加し,編集します。ファイルの内容については,ボディ変数用の電文フォーマットの作成時に使用したJSON-XML変換定義ファイルと合わせてください。

JSON-XML変換定義ファイルの編集手順を示します。

  1. サービスアダプタ定義画面(詳細)の[独自定義ファイル]の[追加]ボタンをクリックして,JSON-XML変換定義ファイルを追加します。

    「<サービスプラットフォームのインストールディレクトリ>\CSC\config\msg\templates」に格納されているJSON-XML変換定義ファイルのテンプレートファイル(csc_json_converter.properties)を選択してください。

  2. [独自定義ファイル]の[編集]ボタンをクリックします。

    JSON-XML変換定義ファイルを編集するためのエディタが起動します。

  3. エディタ上でJSON-XML変換定義ファイルを編集します。

    JSON-XML変換定義ファイルで編集できる定義内容については,マニュアル「サービスプラットフォーム リファレンス」の「3.15.1 JSON-XML変換定義ファイル」を参照してください。

  4. Eclipseのメニューから[ファイル]−[保存]を選択し,定義内容を保存します。

(5) J2EEサーバ用オプション定義ファイルの設定

プロキシサーバやコネクション継続などの設定が必要な場合は,J2EEサーバ用オプション定義ファイル(usrconf.cfg)で設定します。HTTPアダプタで設定するプロパティについては,マニュアル「サービスプラットフォーム 解説」の「2.15.6 プロキシサーバを経由した通信」およびマニュアル「サービスプラットフォーム 解説」の「2.15.7 コネクション継続(Keep-Alive)を使用した通信」を参照してください。

(6) ビジネスプロセスの設定

HTTPアダプタを利用する場合,ビジネスプロセスのサービス呼出アクティビティ,および必要に応じてフォルト処理の設定が必要です。

サービス呼出アクティビティとフォルト処理の設定方法を次に示します。

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

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

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

項目

設定値

アクティビティ名

任意の名称を設定します。

サービス名

HTTPアダプタの新規追加時に設定したサービス名を指定します。

オペレーション名

(3) サービスアダプタ定義画面での操作」で設定したオペレーション名を指定します。

要求電文

ボディ割当変数

送信するデータ形式に応じて次のように指定します。

  • ノーマルモードで送信する場合

    (2)(c)で作成したフォームデータ送信用の電文フォーマットを割り当てた変数を指定します。

  • パススルーモードで送信する場合

    (2)(c)で作成したパススルーモードでのデータ送信用の電文フォーマットを割り当てた変数を指定します。

  • ファイルデータを送信する場合

    adphttp_body_empty.fdxを割り当てた変数を指定します。※1

ヘッダ割当変数※2

Cookieの設定方法に応じて次のように指定します。

  • Cookieを一括設定する場合

    adphttp_header_request1.xsdを割り当てた変数を指定します。

  • Cookieを個別設定する場合

    adphttp_header_request2.xsdを割り当てた変数を指定します。

応答電文

ボディ割当変数

受信するデータ形式に応じて次のように指定します。

  • パススルーモードで受信する場合

    (2)(c)で作成したパススルーモードでのデータ受信用の電文フォーマットを割り当てた変数を指定します。

  • ファイルデータを受信する場合

    adphttp_body_empty.fdxを割り当てた変数を指定します。※3

ヘッダ割当変数※2

Cookieの設定方法に応じて次のように指定します。

  • Cookieを一括設定する場合

    adphttp_header_response1.xsdを割り当てた変数を指定します。

  • Cookieを個別設定する場合

    adphttp_header_response2.xsdを割り当てた変数を指定します。

割当相関セット群

設定しません。

注※1

サービスを呼び出す前に変数を初期化しておく必要があります。

注※2

要求電文(ヘッダ)または応答電文(ヘッダ)を使用しない場合,設定は不要です。

注※3

サービス呼び出し後に空文字列が設定されます。

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

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

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

項目

設定値

割当変数

  • HTTPアダプタのフォルトをキャッチする場合

    adphttp_fault.xsdを割り当てた任意の変数を指定します。

  • システム例外のフォルトをキャッチする場合

    cscfault.xsdを割り当てた任意の変数を指定します。

遷移先

フォルトが発生した場合に遷移する任意のアクティビティを指定します。