1. Web APIについて
Commandメタデータとして定義したカスタムロジックをWebApiメタデータを利用して、 外部からRESTful形式(以下、REST)、 SOAP WSLD形式 で呼び出すことが可能です。
またEntityに対するCRUD操作やメタデータ定義に対するCRUD操作、 バイナリファイルのアップロード、ダウンロードを行うApiを提供します。
Web APIには以下の機能・特徴があります。
-
カスタマイズコマンドの実行
カスタマイズで作成したCommandをWebApi経由で呼び出し実行可能です。
本機能は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. Command実行(WebApi)
カスタマイズで作成したCommandをWebApi経由で実行可能にするには、WebApiメタデータを定義します。
2.1. WebApi定義(AdminConsole)
WebApi定義の作成
WebApiアイコンを右クリックして「WebApiを作成する」を選択してください。
WebApiの設定項目
共通設定
name
はAPIを呼び出す際のURLのパスとなります。
呼び出し時のパスは以下となります。
http(s)://[server]/[tenantContextPath]/api/[nameで指定したパス]
また、 name
の最後に許可するMETHODを付けることも可能です。
例えば、WebApi名として 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 |
||
Access-Control-Allow-Origin |
アクセスを許可するドメイン名、または「*(アスタリスク)」を設定します。 リクエスト情報のヘッダに |
accessControlAllowOrign |
||
Access-Controll-Allow-Credentials |
Access-Control-Allow-Originが有効な場合に、
WebApiのレスポンス情報をリクエスト元に返却します。 |
accessControlAllowCredentials |
||
support bearer token |
RFC6750規格に基づいたBearer Tokenによる認証を許可します。 |
supportBearerToken |
項目 | 内容 | アノテーション |
---|---|---|
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 |
項目 | 内容 | アノテーション |
---|---|---|
request type |
許可するリクエストの種類を選択します。 |
accepts |
response type |
許可するレスポンスのタイプを指定します。 |
responseType |
REST JSON parameter |
リクエストパラメータを、
RequestContext#getParam(xxxx) として、Mapに格納された値を取得できます。 RequestContext#getAttribute(parameter name) として適切な型に変換して値を取得してください。 |
restJson @RestJson |
REST XML Parameter |
リクエストパラメータを、JAXBにより変換して、 Commandの引数であるRequestContextから
|
restXml @RestXml |
項目 | 内容 | アノテーション |
---|---|---|
Command Name |
WebApi呼び出し時に実行されるCommandです。 |
command @CommandConfig |
Init Script |
Commandのインスタンスの初期化ロジックが設定されているか否かを表示します。 |
項目 | 内容 | アノテーション |
---|---|---|
attribute name |
レスポンスとして返すアトリビュート名を設定します。 返却可能な型は以下となります。 * プリミティブ型(やそれに近しいクラス群、String、Date等)とその配列 * Entity(GenericEntity)とその配列 * Entityのプロパティで定義される型とその配列 * 設定ファイルに定義された、JAXBでシリアライズ/デシリアライズ可能なアプリ側で定義したクラス レスポンスとして返却するデータ構造をカスタマイズすることが可能です。 |
results |
2.2. 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.3. 返却値について
以下の内容をレスポンスタイプの各形式にて返却します。
項目 | 内容 |
---|---|
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/entity
METHODやパスによって実行される処理が判定されます。
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(true)
で検索します。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/definition
METHODによって実行される処理が判定されます。
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/bin
-
SOAP形式
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. リクエストヘッダ
WebApiを利用する際に必要なリクエストヘッダの項目について説明します。
大きく分けてREST形式の場合とSOAP形式の2種類があります。 基本的には「REST形式の場合の設定項目」に示す通りですが、機能特有の制限があります。
REST形式
以下の項目をリクエストヘッダに設定する必要があります。
項目名 | key | value |
---|---|---|
ユーザーID |
x-auth-id |
iPLAssのテナントに登録してあるユーザーアカウントを設定する項目です。 リクエストと同時に認証する場合のみ設定して下さい。 |
パスワード |
x-auth-password |
iPLAssのテナントに登録してあるユーザーアカウントのパスワードを設定する項目です。 リクエストと同時に認証する場合のみ設定して下さい。 |
アクセプト |
Accept |
返却値の形式を設定する項目です。XMLかJSONかを選択できます。
|
コンテントタイプ |
Content-Type |
リクエスト送信時にどのタイプで送信するかを設定する項目です。 WebApiで許可しているコンテントタイプを設定して下さい。独自に作成したWebApiであればAdminConsoleから確認して下さい。
|
Token |
x-transaction-token または _t |
Tokenを設定する項目です。 但し、呼び出し時にuserId/passwordをヘッダーにて指定している場合はTokenは不要です。 WebApiのヘッダーにユーザID/パスワードを設定してログインした場合、そのAPI呼び出しの返却値
(HTTPヘッダー:ヘッダー名 |
ユーザID、パスワードが設定されている場合は必ず認証処理を実施します。未設定の場合はセッションにより認証を実施します。 その為、セッションで認証を実施する場合はユーザーID、パスワードを設定しないで下さい。 |
SOAP形式
以下の項目をリクエストヘッダに設定する必要があります。
項目名 | namespace | key | value |
---|---|---|---|
ユーザーID |
id |
iPLAssのテナントうに登録してあるユーザーアカウントを設定する項目です。 リクエストと同時に認証する場合のみ設定して下さい。 |
|
パスワード |
password |
iPLAssのテナントうに登録してあるユーザーアカウントのパスワードを設定する項目です。 リクエストと同時に認証する場合のみ設定して下さい。 |
|
Token |
x-transaction-token または _t |
Tokenを設定する項目です。 但し、呼び出し時にuserId/passwordをヘッダーにて指定している場合はTokenは不要です。 WebApiのヘッダーにユーザーID/パスワードを設定してログインした場合、そのAPI呼び出しの返却値
(HTTPヘッダー:ヘッダー名 |
ユーザID、パスワードが設定されている場合は必ず認証処理を実施します。 未設定の場合はセッションにより認証を実施します。 その為、セッションで認証を実施する場合はユーザーID、パスワードを設定しないで下さい。 |
6.2. Session
セッションを利用すると、認証状態が維持され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のチェックを行う場合は、Tokenの値をリクエストパラメータで送信する必要があります。 またTokenの値をあらかじめ取得しておく必要があります。
API呼び出しと同時にuserId/passwordをヘッダーにて指定している場合はTokenがなくとも操作の実行が可能です。 |
以下のいずれか方法でWebApi呼び出し時に設定します。
-
HTTPヘッダー(SOAPの場合はSOAPヘッダーでも可)に
x-transaction-token
のヘッダー名にて設定 -
WebApi呼び出し時のパラメータとして
_t
のパラメータ名にて設定
セキュリティを考慮し、Token生成専用の汎用のWebApiは作らず、次のいずれかの方法を利用して下さい。
-
WebApiを呼び出す直前の画面にサーバ側の処理(JSP、GroovyTemplate)でHTML内に直接埋め込み
-
Tokenを伴ったWebApi呼び出しの返却値として新たなTokenを発行
-
固定Tokenの場合、ログイン処理のレスポンスとしてクライアントへ固定Tokenを返却し、 Cokkie保存などの方法によりクライアント内にセキュアに保持し、それを利用する
TemplateにてTokenの値を埋め込むためのユーティリティを提供しています。
詳細はJSPカスタムタグ・EL関数 、
GroovyTemplateを参照してください。
Tokenの消費についての例を示します。
入力画面→確認画面→完了画面
といった画面遷移がある場合に、ワンタイムTokenを利用して
入力画面:ワンタイムToken発行
確認画面:ワンタイムToken確認(ただし消費しない)→ consumeチェックなし
完了画面:ワンタイムToken消費 → consumeチェックあり
といった事が可能になります。
確認画面で消費してしまうと、ブラウザバックして、再度確認画面に遷移した際、画面遷移エラーになってしまいます。 その為に確認画面では「消費しない」設定としておきます。 |
6.4. SOAPエンドポイント
SOAP WSDL利用時のエンドポイント設定は、sun-jaxws.xml に以下のように設定しています。
<?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>