1. Web APIについて
Commandメタデータとして定義したカスタムロジックをWeb APIメタデータを利用して、 外部からRESTful形式(以下、REST)、 SOAP WSDL形式 で呼び出すことが可能です。
またEntityに対するCRUD操作やメタデータ定義に対するCRUD操作、 バイナリファイルのアップロード、ダウンロードを行うApiを提供します。
Web APIには以下の機能・特徴があります。
カスタマイズコマンドの実行
カスタマイズで作成したCommandをWeb API経由で呼び出し実行可能です。
本機能はREST形式、 SOAP WSDL形式 に対応しています。Entityに対するCRUD操作の実行
Entityデータに対して、CRUD操作を実行するApiを提供しています。
本機能はREST形式にのみ対応しています。メタデータに対するCRUD操作の実行
メタデータ定義に対するCRUD操作を実行するApiを提供しています。
本機能はREST形式にのみ対応しています。バイナリデータのアップロード、ダウンロード
マルチパートを利用し、バイナリデータのアップロード、ダウンロードが可能です。
本機能はREST形式、 SOAP WSDL形式 に対応しています。
尚、iPLAssではアクセス方法について以下の通り定義し、今後の説明では以下の呼称で記載します。
| iPLAssでの名称 | 概要 |
|---|---|
REST FORM | クライアントから送信されるMIMEメディアタイプがapplication/x-www-form-urlencoded、multipart/form-dataに対応するREST通信を "REST FORM" と呼びます。 |
REST JSON | クライアントから送信されるMIMEメディアタイプがapplication/jsonに対応するREST通信を "REST JSON" と呼びます。 |
REST XML | クライアントから送信されるMIMEメディアタイプがapplication/xmlに対応するREST通信を "REST XML" と呼びます。 |
SOAP WSDL | 一般のSOAP、WSDL形式での通信と同義です。 |
| REST FORM、REST JSON、REST XMLを総称してREST形式、SOAP WSDLをSOAP形式と記載します。 |
2. カスタム WebApi
カスタマイズで作成したCommandをWeb API経由で実行可能にするには、WebApiメタデータを定義します。
2.1. WebApi定義(AdminConsole)
WebApi定義の作成
WebApiアイコンを右クリックして「WebApiを作成する」を選択してください。
WebApiの設定項目
共通設定
name はAPIを呼び出す際のURLのパスとなります。
呼び出し時のパスは以下となります。
http(s)://[server]/[tenantContextPath]/api/[nameで指定したパス]また、 name の最後に許可するMETHODを付けることも可能です。
例えば、Web API名として mtp/entity/GET 、mtp/entity/PUT と2つ定義した場合、以下のリクエストが対象になります。
GET http(s)://[server]/[tenantContextPath]/api/mtp/entity
⇒ mtp/entity/GET が実行されるPUT http(s)://[server]/[tenantContextPath]/api/mtp/entity
⇒ mtp/entity/PUT が実行される固有設定
| 項目 | 内容 | アノテーション |
|---|---|---|
Allow Method | アクセス可能なHTTPメソッド(GET, POST, PUT, DELETE)を指定します。 | methods |
| 項目 | 内容 | アノテーション | ||
|---|---|---|---|---|
privilege execute | WebApi内の処理において、権限の制約を一切受けずに(特権として)実行する事ができます。 | privilaged | ||
public webapi | 未ログインユーザでもアクセス可能になります。
| publicWebApi | ||
check X-Requested-With header |
| checkXRequestedWithHeader | ||
synchroize on session | 同一Sessionのリクエストを同期します。
| synchronizeOnSession | ||
State Type |
| state |
| 項目 | 内容 | アノテーション |
|---|---|---|
Token Check | CSRF(XSRF)対策用Tokenのチェックを行うか否かを設定します。
Tokenのチェックを行う場合は、Tokenの値を送信元画面に埋め込み、リクエストパラメータで送信する必要があります。 詳しくはTokenチェックを参照してください。 |
tokenCheck
@WebApiTokenCheck
executeCheck
|
use fixed Token | Tokenチェックに、セッション単位に固定に払いだされる固定Tokenを利用します。 CSRF(XSRF)対策のみ必要な場合は固定Tokenを利用可能です。 固定Tokenを利用する場合、送信元画面には固定Tokenの値を埋め込む必要があります。 |
tokenCheck
@WebApiTokenCheck
useFixedToken
|
consume a Token | このWebApi実行時にチェックしたTokenを消費します。 |
tokenCheck
@WebApiTokenCheck
consume
|
rollback on exception | Exception発生時にTokenを消費しません。 |
tokenCheck
@WebApiTokenCheck
exceptionRollback
|
| 項目 | 内容 | アノテーション | ||||
|---|---|---|---|---|---|---|
Cache Control | レスポンスのキャッシュ設定を指定します。
| cacheControlType | ||||
Max Age | クライアントへ当該コンテンツのキャッシュ有効期間(秒)を通知します。 レスポンスのキャッシュが許可された場合( | cacheControlMaxAge |
| 項目 | 内容 | アノテーション | ||
|---|---|---|---|---|
Allow Request Content Types | 許可するcontentTypeを指定します。未指定の場合は全て許可します。
| allowRequestContentTypes | ||
Max Request Body Size | リクエストボディの最大サイズ(Byte)を指定します。 | maxRequestBodySize | ||
Max File Size | リクエストされるファイルの最大サイズ(Byte)を指定します。 | maxFileSize |
| 項目 | 内容 | アノテーション |
|---|---|---|
Access-Control-Allow-Origin | CORS (Cross-Origin Resource Sharing) の設定です。 | accessControlAllowOrign |
Access-Controll-Allow-Credentials | CORS (Cross-Origin Resource Sharing) の設定です。 | accessControlAllowCredentials |
| 項目 | 内容 | アノテーション |
|---|---|---|
support Bearer Token | RFC6750規格に基づいたBearer Tokenによる認証を許可します。 | supportBearerToken |
Scopes | OAuth2.0 のScopeを定義します。AccessTokenベースでのアクセスの際、当該Scopeを保持するClientのみアクセス可能となります。 adminConsoleで指定する場合、scopeをスペースで区切った場合、ANDを意味し、改行で区切った場合ORを意味します。 scopeA scopeB 上記の定義をした場合、
このWebApiにアクセスするためには、
| oauthScopes |
| 項目 | 内容 | アノテーション | ||
|---|---|---|---|---|
Request Type | 許可するリクエストの種類を選択します。 | accepts | ||
REST JSON parameter |
リクエストに含まれるJSON文字列をオブジェクトに変換する処理の設定です。 WebApiのクライアントからは、JSONは次の形で指定します。
サーバ側では、JSON文字列を、 変換されたオブジェクトは、RequestContextから 例
parameter nameにvalueXを指定し、parameter typeにSomeTypeを指定した場合、 SomeType valueX = (SomeType) request#getAttribute("valueX")で取得可能です。
| restJson @RestJson | ||
REST XML Parameter |
リクエストに含まれるXML文字列をオブジェクトに変換する処理の設定です。 WebApiのクライアントからは、XMLは次の形で指定します。
サーバ側ではXML文字列をJAXBにより変換します。 変換可能なオブジェクトはservice-configのWebApiJAXBServiceに設定されたクラスとなります。 設定については、 WebApiJAXBService を参照してください。 変換されたオブジェクトは、RequestContextから 例
parameter nameにvalueXを指定し、SomeTypeがWebApiJAXBServiceに設定される場合、 SomeType valueX = (SomeType) request.getAttribute("valueX")で取得可能です。 | restXml @RestXml | ||
Response Type | 許可するレスポンスのタイプを指定します。 | responseType |
| 項目 | 内容 |
|---|---|
Parameter Name | パラメータマッピング機能における、パラメータ名を指定します。 |
Map From | パラメータマッピング機能における、マッピング元を指定します。 |
Condition | パラメータマッピング機能における、マッピング処理を行う条件を指定します。 |
| 項目 | 内容 | アノテーション |
|---|---|---|
Command Name | WebApi呼び出し時に実行されるCommandです。 | command @CommandConfig |
Init Script | Commandのインスタンスの初期化ロジックが設定されているか否かを表示します。 |
| 項目 | 内容 | アノテーション |
|---|---|---|
Attribute Name | レスポンスとして返すアトリビュート名を設定します。 返却可能な型は以下となります。 * プリミティブ型(やそれに近しいクラス群、String、Date等)とその配列 * Entity(GenericEntity)とその配列 * Entityのプロパティで定義される型とその配列 * 設定ファイルに定義された、JAXBでシリアライズ/デシリアライズ可能なアプリ側で定義したクラス レスポンスとして返却するデータ構造をカスタマイズすることが可能です。 | results |
2.2. パラメータマッピング
リクエストに含まれるパラメータを別名にマッピングしたり、URLのパスの一部をパラメータにマッピングすることが可能です。
Parameter Nameに指定したパラメータ名に、Map Fromで指定されたパス、もしくは別パラメータをマッピングします。 Map Fromには、リクエストURLのパスの一部を表すパターン文字列、もしくは別パラメータ名を指定することが可能です。
パスのマッピング
パスをマッピングする場合、特別なパターン文字列を利用します。
- ${n}
${n}形式でパス階層の一部をマッピング可能です。
nはWebApi名以降のパスの階層数を示します。
${0}とした場合WebApi名より1階層下層のパスの値が、${1}とした場合WebApi名より2階層下層のパスの値がマップされます。- ${paths}
${paths}とした場合、WebApi名以降のサブパスがマップされます。
WebApi名が sample/webApi1 の場合、
sample/webApi1/path1/path2/path3?paramX=fuga を呼び出した場合、Map Fromに設定した値によって、 それぞれ次の値がパラメータにマップされます。
${0} → path1
${1} → path2
${paths} → path1/path2/path3
マッピング条件の指定
Conditionを指定することにより、パラメータマッピングを実行する条件を指定することが可能です。 Conditionはgroovy Scriptで記述可能です。
次の変数がバインドされており条件判断に利用可能です。
| 変数名 | 説明 |
|---|---|
subPath | webApi名より下層のサブパスを/で分割したString配列 |
fullPath | webApi名含めたフルパスを/で分割したString配列 |
paramMap | リクエストパラメータのMap |
たとえば、次のようなパラメータマッピング定義がある場合、
| Name | Map From | Condition |
|---|---|---|
defName | ${0} | subPath.length==1 |
viewName | ${0} | subPath.length==2 |
defName | ${1} | subPath.length==2 |
webApi1に対するリクエストパスが、
- webApi1/hogeだった場合
defName=hoge
- webApi1/hoge/fugaだった場合
viewName=hoge, defName=fuga
となります。
2.3. Commandの設定
APIが呼ばれた際に実行するCommandとその処理方法を設定します。
| 項目 | 内容 | ||
|---|---|---|---|
Execute Command | APIを呼び出された際に実行するCommandです。 | ||
Transaction Propagation | このCommand実行時のトランザクション制御方法を指定します。 次のいずれかを指定します。デフォルト値はREQUIREDです。
| ||
Rollback when exception | Command実行時に例外がスローされた場合、 自動的にトランザクションをロールバックするか否かを指定します。 | ||
Throw Exception if setRollbackOnly | トランザクションが本Command処理用に新規作成された際、
且つCommand処理中にsetRoobackOnlyされた場合、かつ明示的に例外がスローされなかった場合、iPLAss側で例外扱い( | ||
Init Script | Commandのインスタンスの初期化Script(Groovy Script)を指定可能です。 対象となるCommandのインスタンスは
|
複合Commandの設定
1つのAPIに対して複数のCommandを紐付けすることが可能です。
複数のCommandが紐付けされた場合、デフォルトでは次のような動作になります。
定義された順番にCommandを実行
最後に定義されたCommandの実行結果ステータスを全体の実行結果ステータスとする
条件により、処理順を変更するなど複雑な制御が必要な場合、Composite Command Configにて制御Scriptを記述可能です。
Composite Command Configの設定
| 項目 | 内容 | ||
|---|---|---|---|
Transaction Propagation | この複合Command実行時のトランザクション制御方法を指定します。 指定可能な値は、単一のCommand設定のTransaction Propagationの値と同様です。 デフォルト値はREQUIREDです。 | ||
Rollback when exception | この複合Command実行時に例外がスローされた場合、 自動的にトランザクションをロールバックするか否かを指定します。 | ||
Throw Exception if setRollbackOnly | トランザクションが本複合Command処理用に新規作成された際、
且つCommand処理中にsetRoobackOnlyされた場合、かつ明示的に例外がスローされなかった場合、iPLAss側で例外扱い( | ||
Initilize Script | 複数のCommandの初期化処理のスクリプトを設定可能です。
あらかじめ変数の 設定例
上記の場合、一覧の1番目(配列のindex=0)のCommandのプロパティpropAに10、 2番目(配列のindex=1)のコマンドのプロパティpropBにhogeといった値が設定されます。
| ||
Execute Rule Script | Commandが複数定義された場合に、Commandの実行順やステータスによる処理分岐などの制御を
GroovyScriptで記述することが可能です。 あらかじめ変数の 記述例
|
2.4. 返却値について
以下の内容をレスポンスタイプの各形式にて返却します。
| 項目 | 内容 |
|---|---|
status | Commandで実装した戻り値がセットされます。 |
exceptionType | エラーが発生した場合に、発生したExceptionのクラス名がセットされます。 |
exceptionMessage | エラーが発生した場合に、発生したExceptionに設定されているメッセージがセットされます。 |
これ以外に、Resultsで設定したnameに一致するデータをRequestContextから取得し、返します。
Results設定
test1 , test2 を設定
Command
request.setAttribute("test1", 1000); request.setAttribute("test2", "string1"); request.setAttribute("test3", "string2"); //これは無視される return "SUCCESS";結果
{ "status": "SUCCESS", "test1": 1000, "test2": "string1" }
レスポンスのカスタマイズ
以下の条件に一致する場合は、レスポンス内容を自由にカスタマイズすることが可能です。
返却値が1つである
上記の返却値に設定されたオブジェクトが、以下のいずれかであること
javax.ws.rs.core.StreamingOutput
javax.ws.rs.core.Response.ResponseBuilder
| ResponseBuilderにおいては、HTTPステータスやContentTypeもカスタマイズすることが可能です。 |
ソース
import java.io.BufferedWriter; import java.io.IOException; import java.io.OutputStream; import java.io.OutputStreamWriter; import javax.ws.rs.WebApplicationException; import javax.ws.rs.core.StreamingOutput; ... request.setAttribute("result1", new StreamingOutput() { @Override public void write(OutputStream out) throws IOException, WebApplicationException { try (OutputStreamWriter osw = new OutputStreamWriter(out, "UTF-8"); BufferedWriter writer = new BufferedWriter(osw); ){ writer.write("test1"); } } }); return "SUCCESS";結果
test1
ソース
import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; import javax.ws.rs.core.Response.ResponseBuilder; import javax.ws.rs.core.Response.Status; ... ResponseBuilder builder = Response.ok("test1"); //ResponseBuilder builder = Response.status(Status.SERVICE_UNAVAILABLE).entity("UNAVAILABLE").type(MediaType.APPLICATION_JSON); //ResponseBuilder builder = Response.status(500).entity("test1").type(MediaType.APPLICATION_XML); request.setAttribute("result1", builder); return "SUCCESS";結果
test1
3. Entity CRUD API
Entityデータに対する操作(Load, Query, Insert, Update, Delete、CSV Upload)を提供します。REST形式にのみ対応しています。
基本となるURLは以下です。
http(s)://[server]/[tenantContextPath]/api/mtp/entityMETHODやパスによって実行される処理が判定されます。
| METHOD + パス | 処理 |
|---|---|
GET api/mtp/entity/[Entity定義名]/[oid] | oid指定でロード |
GET api/mtp/entity/[Entity定義名]/[oid]/[version] | oid,version指定でロード |
GET api/mtp/entity/[Entity定義名]?filter=[where条件] | where句指定して検索。csv形式も可能 |
GET api/mtp/entity?query=[EQL] | EQL文を指定して検索。csv形式も可能 |
POST api/mtp/entity/[Entity定義名] | Insert |
PUT api/mtp/entity/[Entity定義名]/[oid] | Update |
PUT api/mtp/entity/[Entity定義名]/[oid]/[version] | バージョン指定でUpdate |
DELETE api/mtp/entity/[Entity定義名]/[oid] | Delete |
POST api/mtp/entity/[Entity定義名] | CSVによる一括更新 (multipart/form-data形式) |
3.1. 権限設定
操作対象Entityに対してどの操作を許可するかといった権限の設定が必要になります。
権限の設定は「Entity」を右クリックして、「EntityWebApiを開く」を選択してください。

登録済のEntity一覧が表示され、それぞれにINSERT、SELECT(Load)、SELECT(Query)、UPDATE、DELETEのチェックボックスが存在します。 操作対象Entityの許可したい処理をチェックして保存してください。
上記の例の場合、test.webapi.Test001、test.webapi.Test002、test.webapi.Test003に対して全ての処理が許可されている状態になっています。
3.2. 検索処理
Entityに対する検索処理はGETを利用します。
Load
Entityデータをロードする場合は以下のAPIを利用します。
| METHOD + パス | 処理 |
|---|---|
GET api/mtp/entity/[Entity定義名]/[oid] | oid指定でロード |
GET api/mtp/entity/[Entity定義名]/[oid]/[version] | oid,version指定でロード |
パラメータ
パラメータはありません。返却値
項目 内容 entity
ロードされたEntityデータがセットされます
この他に共通の返却値があります。
Query(searchEntity)
Entityデータに対するQuery検索は2種類あります。 Entityを指定して検索する方法とEQLを指定する方法です。
| METHOD + パス | 処理 |
|---|---|
GET api/mtp/entity/[Entity定義名]?filter=[where条件] | where句指定して検索 |
GET api/mtp/entity?query=[EQL] | EQL文を指定して検索 |
パラメータ
Entity名指定
パラメータ名 内容 filter
パスで指定したEntityに対するwhere句を指定します
Entity未指定
パラメータ名 内容 query
EQLを指定します
共通
パラメータ名 内容 tabular
trueが設定されている場合、表形式で検索します。
SearchOption#setReturnStructuredEntity(false)で検索します。countTotal
trueが設定されている場合、
SearchOption#setCountTotal(true)で検索します。
返却値
リクエストヘッダのAcceptが
text/csvの場合
CSV形式の結果が返ります。上記以外の場合
項目 内容 list
検索結果がセットされます
count
countTotal=trueで検索した場合に、件数がセットされますこの他に共通の返却値があります。
3.3. 更新処理
Entityデータを更新する場合は、以下のAPIを利用します。
| METHOD + パス | 処理 |
|---|---|
POST api/mtp/entity/[Entity定義名] | Insertを実行 |
PUT api/mtp/entity/[Entity定義名]/[oid] | Updateを実行 |
PUT api/mtp/entity/[Entity定義名]/[oid]/[version] | バージョン指定でUpdateを実行 |
DELETE api/mtp/entity/[Entity定義名]/[oid] | Deleteを実行 |
POST api/mtp/entity/[Entity定義名] | 複数件の一括更新(csv形式で) |
Insert
Entityデータを登録する場合は以下のAPIを利用します。
| METHOD + パス | 処理 |
|---|---|
POST api/mtp/entity/[Entity定義名] | Insertを実行 |
パラメータ
パラメータ名 内容 entity
登録するEntityデータをセットします
返却値
項目 内容 oid
登録したEntityの
oidがセットされますこの他に共通の返却値があります。
Update
Entityデータを更新する場合は以下のAPIを利用します。
| METHOD + パス | 処理 |
|---|---|
PUT api/mtp/entity/[Entity定義名]/[oid] | Updateを実行 |
PUT api/mtp/entity/[Entity定義名]/[oid]/[version] | バージョン指定でUpdateを実行 |
パラメータ
パラメータ名 内容 entity
更新するEntityデータをセットします
返却値
項目 内容 oid
更新したEntityの
oidがセットされますversion
Version管理している場合、更新したEntityの
versionがセットされますこの他に共通の返却値があります。
Delete
Entityデータを削除する場合は以下のAPIを利用します。
| METHOD + パス | 処理 |
|---|---|
DELETE api/mtp/entity/[Entity定義名]/[oid] | Deleteを実行 |
パラメータ
パラメータ名 内容 timestamp
削除対象Entityの更新日時が設定されている場合、
DeleteOption#setCheckTimestamp(true)で削除します。返却値
共通の返却値のみ返ります。
CSVアップロード
CSV形式でEntityデータを一括で更新する場合は以下のAPIを利用します。
| METHOD + パス | 処理 |
|---|---|
POST api/mtp/entity/[Entity定義名] | CSVによる一括更新 (multipart/form-data形式) |
Entityプロパティ値の指定
REST FORM、REST JSON、REST XMLのそれぞれの形式にてパラメータを設定して下さい。
| プロパティ型 | 備考 |
|---|---|
AutoNumber | 設定可能ですが、基本的には自動採番する項目の為セットしない事を推奨します。 |
Binary | lobIdを指定して下さい。 |
Boolean | true, falseを設定して下さい。 |
Date |
|
DateTime |
|
Decimal | |
Expression | 設定不可項目です。仮に設定しても対象外として処理されます。 |
Integer | |
LongText | |
Reference | 参照先のOidを設定して下さい。JSON, XMLの場合はDefinitionNameが必須となります。 |
Select | SelectValueの値を設定して下さい。 |
String | |
Time |
|
4. メタデータ CRUD API
メタデータに対する操作(Load, Create, Update, Delete)を提供します。REST形式にのみ対応しています。
基本となるURLは以下です。
http(s)://[server]/[tenantContextPath]/api/mtp/definitionMETHODによって実行される処理が判定されます。
| METHOD + パス | 処理 |
|---|---|
GET api/mtp/definition/[メタデータ定義パス] | 指定されたメタデータ定義をLoad |
POST api/mtp/definition/[メタデータ定義パス] | 指定されたメタデータ定義をCreate |
PUT api/mtp/definition/[メタデータ定義パス] | 指定されたメタデータ定義をUpdate |
DELETE api/mtp/definition/[メタデータ定義パス] | 指定されたメタデータ定義をDelete |
| メタデータ定義パスについては、 AdminConsoleのMetaDataExplorerのPathを参照してください。 |
4.1. 利用設定
メタデータの更新用APIを利用するには、WebApiServiceの enableDefinitionApi 設定が必要になります。
詳細については、 WebApiServiceを参照してください。
4.2. Load
メタデータをロードする場合はGETを利用します。
| METHOD + パス | 処理 |
|---|---|
GET api/mtp/definition/[メタデータ定義パス] | 指定されたメタデータ定義をLoad |
パラメータ
項目 内容 recursive
trueが設定されている場合、指定されているパス配下を再帰的にすべて検索します。
返却値
パスの最後が
/の場合項目 内容 list
パス配下の検索結果がセットされます
上記以外の場合
項目 内容 definition
指定パスの検索結果がセットされます
共通
この他に共通の返却値があります。
4.3. Create
メタデータを登録する場合はPOSTを利用します。
| METHOD + パス | 処理 |
|---|---|
POST api/mtp/definition/[メタデータ定義パス] | 指定されたメタデータ定義をCreate |
パラメータ
項目 内容 definition
登録するメタデータ定義を設定します
返却値
共通の返却値のみ返ります。
4.4. Update
メタデータを更新する場合はPUTを利用します。
| METHOD + パス | 処理 |
|---|---|
PUT api/mtp/definition/[メタデータ定義パス] | 指定されたメタデータ定義をUpdate |
パラメータ
項目 内容 definition
登録するメタデータ定義を設定します
返却値
共通の返却値のみ返ります。
4.5. Delete
メタデータを削除する場合はDELETEを利用します。
| METHOD + パス | 処理 |
|---|---|
DELETE api/mtp/definition/[メタデータ定義パス] | 指定されたメタデータ定義をDelete |
パラメータ
パラメータはありません。返却値
共通の返却値のみ返ります。
5. バイナリ 操作 API
バイナリデータのアップロード、ダウロードを提供します。REST形式と SOAP形式 の2種類に対応しています。
| 本APIでバイナリデータをアップロード後、別APIでアップロードしたバイナリデータを扱う場合は、 セッションを維持し、同一セッションで扱う必要があります。 |
基本となるURLは以下です。
REST形式
http(s)://[server]/[tenantContextPath]/api/mtp/binSOAP形式
http(s)://[server]/[servletContextPath]/soap/bin?wsdl
REST形式の場合、METHODによって実行される処理が判定されます。
| METHOD + パス | 処理 |
|---|---|
GET api/mtp/bin/[lobId] | lobId指定でダウンロード |
POST api/mtp/bin | uploadFileというキー名でファイルアップロード (multipart/form-data形式) |
5.1. 利用設定
バイナリの操作用APIを利用するには、WebApiServiceの enableBinaryApi 設定が必要になります。
詳細については、 WebApiServiceを参照してください。
5.2. REST ダウンロード
ファイルをダウンロードする場合はGETを利用します。
| METHOD + パス | 処理 |
|---|---|
GET api/mtp/bin/[lobId] | lobId指定でダウンロード |
パラメータ
パラメータはありません。
返却値
バイナリファイルを返します。
5.3. REST アップロード
ファイルをアップロードする場合はPOSTを利用します。
| METHOD + パス | 処理 |
|---|---|
POST api/mtp/bin | uploadFileというキー名でファイルアップロード (multipart/form-data形式) |
パラメータ
パラメータ名 内容 uploadFile
アップロードするファイルをセットします
返却値
項目 内容 lobId
登録したBinaryReferenceのLobIdがセットされます
この他に共通の返却値があります。
5.4. SOAP ダウンロード
WSDLに記載されている通り、 BinaryWebService.fileDownload を実行します。
パラメータ
引数No. 型 内容 第1引数
String
lobId
返却値
バイナリデータが返却されます。
ファイルがない場合は404エラーが、その他エラーの場合は500エラーが返却されます。
5.5. SOAP アップロード
WSDLに記載されている通り、 BinaryWebService.upload を実行します。
パラメータ
引数No. 型 内容 第1引数
String
ファイル名
第2引数
DataHandler
アップロードしたいバイナリデータをDataHandler形式で渡します。
DataHandlerへは下記の要領で変換して下さい。(D:\USER\Data\sample.jpgをリクエストに添付したい場合)
FileDataSource fdSource = new FileDataSource("D:\\USER\\Data\\sample.jpg"); DataHandler dhandler = new DataHandler(fdSource);返却値
WebApiResponseとして結果が戻ります。org.iplass.mtp.impl.webapi.WebApiResponse
項目 内容 status
処理成功時には
SUCCESSが、失敗時にはFAILUREがセットされますexceptionType
文字列として例外のクラス名がセットされます
exceptionMessage
文字列としてのエラーメッセージです
lobId
登録したBinaryReferenceのLobIdがセットされます
6. 共通設定
6.1. リクエストヘッダ
Web APIを利用する際に必要なリクエストヘッダの項目について説明します。 大きく分けてREST形式の場合とSOAP形式の2種類があります。
REST形式
以下の項目を必要に応じてHTTPリクエストヘッダに設定します。
| 項目名 | name | value | ||||||
|---|---|---|---|---|---|---|---|---|
ユーザーID | X-Auth-Id | 認証用のユーザIDを指定するカスタムヘッダです。
| ||||||
パスワード | X-Auth-Password | 認証用のユーザのパスワードを指定するカスタムヘッダです。X-Auth-Idと同時に設定します。 | ||||||
認可要求 | Authorization | 認証・認可要求をする際に指定可能です。 iPLAssは以下の認可要求タイプをサポートします。
| ||||||
クッキー(セッションIDなど) | Cookie | ステートフルなWeb APIを呼び出す際にはセッションIDなどが設定されているCookieを有効化する必要があります。 | ||||||
アクセプト | Accept | 返却値のメディアタイプ形式を設定する項目です。 | ||||||
コンテントタイプ | Content-Type | リクエスト送信時にどのタイプで送信するかを設定する項目です。 Web API定義で許可しているコンテントタイプを設定して下さい。 次のいずれかを設定します。
| ||||||
Token | X-Transaction-Token | トランザクションToken(もしくはCSRF(XSRF)対策用Token)を設定する項目です。 また、
Web APIのヘッダにユーザID/パスワードを設定してログインした場合、且つWeb APIがステートフルの場合、そのAPI呼び出しのレスポンス
(HTTPヘッダ:ヘッダ名 |
SOAP形式
以下の項目を必要に応じてリクエストのSOAPヘッダ/HTTPヘッダに設定する必要があります。
| 項目名 | namespace | name | value | ||
|---|---|---|---|---|---|
ユーザーID | http://iplass.org/webapi/credential | id | 認証用のユーザIDを指定する項目です。
| ||
パスワード | http://iplass.org/webapi/credential | password | 認証用のユーザのパスワードを指定します。 |
| 項目名 | name | value |
|---|---|---|
クッキー(セッションIDなど) | Cookie | ステートフルなWeb APIを呼び出す際にはセッションIDなどが設定されているCookieを有効化する必要があります。 |
Token | X-Transaction-Token | トランザクションToken(もしくはCSRF(XSRF)対策用Token)を設定する項目です。 SOAPヘッダにユーザID/パスワードを設定してログインした場合、且つWeb APIがステートフルの場合、そのAPI呼び出しの返却値
(HTTPヘッダ:ヘッダ名 |
6.2. Session
Web API定義にてステートフル、ステートレスの指定が可能です。 ステートフルの場合は、Cookieを利用しセッションが維持されます。 同一ユーザにて複数回連続でWeb APIを呼び出す場合、セッションを利用すると、認証状態が維持され2回目以降のアクセスの際に認証処理が不要となります。 認証は比較的重い処理の為、前記のような場合はセッションの利用を推奨しています。
また、バイナリデータアップロードからエンティティデータの登録までは同一セッションである必要があります。 この処理を例にセッション維持の例について解説します。
バイナリデータアップロードAPIを利用した場合、バイナリデータはテンポラリ状態として保存され、汎用画面から利用可能な状態ではありません。
ファイルアップロードの返却値にあるlobIdを利用し、エンティティデータとして使える形式に変換後、エンティティデータとして登録する必要があります。
バイナリデータアップロード~ダウンロードまで

REST形式
下記は「HTTP Client」を利用した場合の例を記載しています。
// 1.セッション情報を保存する為の下準備
CookieStore cookieStore = new BasicCookieStore();
HttpContext httpContext = new BasicHttpContext();
// 2.セッションを保存する為にコンテキストを作成
httpContext.setAttribute(ClientContext.COOKIE_STORE, cookieStore);
// 3.バイナリデータアップロードAPI呼び出し時に上記作成したコンテキストをセット
HttpResponse response = httpClient.execute(httpPost, httpContext);
// 4.下記コマンドでセッションを切ります
httpClient.getConnectionManager().shutdown();
// 5.コンテキストを利用して再接続
HttpResponse response = httpClient.execute(httpPost, httpContext);上記ソースの1~3を実施しないと4でセッションが切断され、5で接続した際には別セッションとなります。
SOAP形式
下記では「JAX-WS(Metoro)」を利用した場合の例を記載しています。
// 1.BindingProviderの作成
WSBindingProvider bp = (WSBindingProvider) port;
// 2.セッション利用の設定
((BindingProvider) port).getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);
// 3.バイナリデータアップロード処理の呼び出し
WebApiResponse result = port.upload("uploadFile", "sample.jpg", dhandler);
// 4.呼び出し後にセッション情報を取得
com.sun.xml.ws.transport.Headers headers = (com.sun.xml.ws.transport.Headers)
bp.getResponseContext().get(MessageContext.HTTP_RESPONSE_HEADERS);
Object cookie = headers.get("Set-Cookie");
// 5.新規BindingProviderの作成
WSBindingProvider commandbp = (WSBindingProvider) commandPort;
// 6.セッション情報をセット
Map<String, List<String>> customHeaders = new HashMap<String, List<String>>();
customHeaders.put("Cookie", Arrays.asList(cookie.toString()));
((BindingProvider) commandp).getRequestContext()
.put(MessageContext.HTTP_REQUEST_HEADERS, customHeaders);上記ソースの1~5を実施しないと3完了後にセッションが切断され、6で接続した際には別セッションとなります。
6.3. Tokenチェック
Token(CSRF対策、トランザクション重複起動対策)のチェックを行う場合は、Tokenの値をリクエストパラメータで送信する必要があります。 またTokenの値をあらかじめ取得しておく必要があります。
以下のいずれか方法でWeb API呼び出し時に設定します。
HTTPヘッダ(SOAPの場合はSOAPヘッダでも可)に
X-Transaction-Tokenのヘッダ名にて設定Web API呼び出し時のパラメータとして
_tのパラメータ名にて設定
次のいずれかの方法を利用して下さい。
Web APIを呼び出す直前の画面にサーバ側の処理(JSP、GroovyTemplate)でHTML内に直接埋め込み
Tokenを伴ったWeb API呼び出しの返却値として新たなTokenを発行
(CSRF対策として利用可能な固定Tokenの場合)ログイン処理のレスポンスとしてクライアントへTokenを返却し、 Cookie保存などの方法によりクライアント内にセキュアに保持し、それを利用する
TemplateにてTokenの値を埋め込むためのユーティリティを提供しています。
詳細はJSPカスタムタグ・EL関数 、
GroovyTemplateを参照してください。
6.4. SOAPエンドポイント
SOAP/WSDLを利用する場合、iPLAssはMetro(JAX-WS RI)を基盤として利用します。 SOAPエンドポイントを有効化するためには、web.xmlにてMetroをWeb Applicaitonに組み込みます。
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1">
:
<listener>
<listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class>
</listener>
<servlet>
<description>JAX-WS endpoint</description>
<display-name>JAX-WS Endpoint</display-name>
<servlet-name>webserviceEndpoint</servlet-name>
<servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>webserviceEndpoint</servlet-name>
<url-pattern>/soap/*</url-pattern>
</servlet-mapping>
:
</web-app>また、合わせて以下の内容のsun-jaxws.xmlをWEB-INFへ格納します。
<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime' version='2.0'>
<endpoint implementation="org.iplass.mtp.impl.webapi.soap.CommandInvokerWebService" name="CommandInvoker" url-pattern="/soap/command" />
<endpoint implementation="org.iplass.mtp.impl.webapi.soap.BinaryWebService" name="BinaryService" url-pattern="/soap/bin" enable-mtom="true" />
</endpoints>