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" と呼びます。
パラメータをFORM形式(Key, Value)で扱います。

REST JSON

クライアントから送信されるMIMEメディアタイプがapplication/jsonに対応するREST通信を "REST JSON" と呼びます。
パラメータをJSON形式で扱います。

REST XML

クライアントから送信されるMIMEメディアタイプがapplication/xmlに対応するREST通信を "REST XML" と呼びます。
パラメータを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/GETmtp/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 が実行される
固有設定
AllowMethod
項目 内容 アノテーション

Allow Method

アクセス可能なHTTPメソッド(GET, POST, PUT, DELETE)を指定します。
全てチェックされていない場合は全メソッドでのアクセスが可能です。 デフォルトでは全てチェックされていない状態となります。
ひとつでもチェックされている場合は、チェックされているメソッドでのみアクセスが可能となります。

methods

Access Policy
項目 内容 アノテーション

privilege execute

WebApi内の処理において、権限の制約を一切受けずに(特権として)実行する事ができます。

privilaged

public webapi

未ログインユーザでもアクセス可能になります。
通常、未ログインユーザでも実行可能にするにはWebApi権限の定義が必要ですが、 これをチェックすることでWebApi権限のチェックを省略することができます。

public webapi と privilege execute の違い
public webapiは、WebApiを誰でも呼び出せるようにするだけです。Entity検索などの際には、Entity権限が適用されます。
一方、privilege executeは、WebApi実行中は、権限チェックを全く行いません。Entity操作なども特権で実行されます。

publicWebApi

check X-Requested-With header

X-Requested-With ヘッダを確認します。

X-Requested-With ヘッダに設定されている値がservice-configのWebApiServiceに設定されている値に一致する場合のみ アクセスを許可します。標準では、 XMLHttpRequest が設定されています。
設定については、WebApiServiceを参照してください。

checkXRequestedWithHeader

synchroize on session

同一Sessionのリクエストを同期します。
このフラグがONにされた場合、Session単位に単一のロック用Objectにてsynchronizeされた上で、WebApiの処理が実行されます。

可能であればCommand内にて必要な箇所で明示的に同期することを推奨します。

synchronizeOnSession

state type

STATEFUL

セッション情報は保存されます。

STATELESS

セッション情報は保存されません。
ただし、当該WebApi呼び出し前にStatefulなセッションが確立されている場合は、セッション情報の参照、保存は可能です。

state

Access-Control-Allow-Origin

アクセスを許可するドメイン名、または「*(アスタリスク)」を設定します。
「\*(アスタリスク)」が設定されていた場合は、すべてのドメイン名からの接続を許可します。
複数のドメイン名を登録する場合は、半角スペースで区切ってください。

リクエスト情報のヘッダに Origin がある場合、 Origin に設定されたドメイン名と iPLAss上で設定されたドメイン名をチェックします。

accessControlAllowOrign

Access-Controll-Allow-Credentials

Access-Control-Allow-Originが有効な場合に、 WebApiのレスポンス情報をリクエスト元に返却します。
OFFの場合はブラウザによってはレスポンス情報が無視され、リクエスト側に返却されません。

accessControlAllowCredentials

support bearer token

RFC6750規格に基づいたBearer Tokenによる認証を許可します。

supportBearerToken

Token Check
項目 内容 アノテーション

token check

CSRF(XSRF)対策用Tokenのチェックを行うか否かを設定します。
また設定により、このTokenを重複サブミット(トランザクションの重複起動)対策として利用することも可能です。

No Check

Tokenのチェックを行いません。

Check

呼び出し元で指定した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を消費します。
消費されたTokenは再利用できません(同一Tokenでリクエストが来た場合、エラーになります)。
重複リクエスト(トランザクションの重複起動)を防ぐためには、このフラグをONにします。

tokenCheck
  @WebApiTokenCheck
    consume

rollback on exception

Exception発生時にTokenを消費しません。

tokenCheck
  @WebApiTokenCheck
    exceptionRollback

個別設定
項目 内容 アノテーション

request type

許可するリクエストの種類を選択します。
REST FORM、REST JSON、REST XML、SOAP WSDL の4種類が選択可能です。

accepts

response type

許可するレスポンスのタイプを指定します。
複数ある場合はカンマで区切ってください。 未指定の場合、 application/jsonapplication/xml を許可します。

responseType

REST JSON parameter

request typeREST JSON を選択した場合のみ設定可能です。

リクエストパラメータを、 parameter type で指定したクラスに変換して、 Commandの引数であるRequestContextから parameter name で指定した値をKEYとして取得することができます。
parameter type が未指定の場合は、 java.util.Map として設定します。

parameter typejava.util.Map 型で、かつ parameter nameparam という値の場合、

RequestContext#getParam(xxxx)

として、Mapに格納された値を取得できます。
これ以外の場合は、

RequestContext#getAttribute(parameter name)

として適切な型に変換して値を取得してください。

restJson
  @RestJson

REST XML Parameter

request typeREST XML を選択した場合のみ設定可能です。

リクエストパラメータを、JAXBにより変換して、 Commandの引数であるRequestContextから parameter name で指定した値をKEYとして取得することができます。
変換可能なオブジェクトはservice-configのWebApiJAXBServiceに設定されたクラスとなります。 設定については、WebApiJAXBServiceを参照してください。

param として指定した場合、XMLとして設定した値に対するgetParamでの取得可否はJsonと同じです。

restXml
  @RestXml

Execute Commands
項目 内容 アノテーション

Command Name

WebApi呼び出し時に実行されるCommandです。
Commandの設定を参照ください。

command
  @CommandConfig

Init Script

Commandのインスタンスの初期化ロジックが設定されているか否かを表示します。

Results
項目 内容 アノテーション

attribute name

レスポンスとして返すアトリビュート名を設定します。
Command内で RequestContext#setAttribute(attribute name) で値を設定してください。

返却可能な型は以下となります。 * プリミティブ型(やそれに近しいクラス群、String、Date等)とその配列 * Entity(GenericEntity)とその配列 * Entityのプロパティで定義される型とその配列 * 設定ファイルに定義された、JAXBでシリアライズ/デシリアライズ可能なアプリ側で定義したクラス

レスポンスとして返却するデータ構造をカスタマイズすることが可能です。
カスタマイズについては返却値についてを参照ください。

results

2.2. Commandの設定

APIが呼ばれた際に実行するCommandとその処理方法を設定します。

項目 内容

Execute Command

APIを呼び出された際に実行するCommandです。

Transaction Propagation

このCommand実行時のトランザクション制御方法を指定します。 次のいずれかを指定します。デフォルト値はREQUIREDです。

REQUIRED

トランザクションが開始されていなかったら、開始(およびコミット/ロールバック)します。 すでにトランザクションが開始されている場合は、そのトランザクションのコンテキストで実行されます。

REQUIRES_NEW

新規にトランザクションを開始(およびコミット/ロールバック)します。 既存のトランザクションが存在した場合は、一旦サスペンドされ当該処理完了後、レジュームされます。

NOT_SUPPORTED

トランザクション制御をしません。既存のトランザクションが開始されている場合は、 一旦そのトランザクションがサスペンドされ当該処理完了後、レジュームされます。

SUPPORTS

トランザクションが開始されていない場合は、トランザクション制御しません。 既にトランザクションが開始されている場合は、そのトランザクションのコンテキストで実行されます。

Rollback when exception

Command実行時に例外がスローされた場合、 自動的にトランザクションをロールバックするか否かを指定します。

Throw Exception if setRollbackOnly

トランザクションが本Command処理用に新規作成された際、 且つCommand処理中にsetRoobackOnlyされた場合、かつ明示的に例外がスローされなかった場合、iPLAss側で例外扱い( org.iplass.mtp.transaction.RollbackException をスロー)にするか否かの設定です。

Init Script

Commandのインスタンスの初期化Script(Groovy Script)を指定可能です。

対象となるCommandのインスタンスは cmd としてバインドされています。
初期化Scriptの例を示します。

cmd.propA = 1000;
cmd.propB = true;
通常はインスタンスが複数のリクエストで共有されるため、この初期化処理は一度のみ実行されます。
ただしCommand定義にて、instantiated for each request 設定を有効化している場合、リクエストの都度、初期化処理が実行されます。

複合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側で例外扱い( org.iplass.mtp.transaction.RollbackException をスロー)にするか否かの設定です。

Initilize Script

複数のCommandの初期化処理のスクリプトを設定可能です。 あらかじめ変数の cmd にCommandのインスタンスが配列でバインドされています。

設定例
cmd[0].propA = 10
cmd[1].propB = 'hoge'

上記の場合、一覧の1番目(配列のindex=0)のCommandのプロパティpropAに10、 2番目(配列のindex=1)のコマンドのプロパティpropBにhogeといった値が設定されます。

複合Commandを構成しているCommand定義にて、instantiated for each request 設定を 有効化しているものがひとつでも存在する場合、リクエストの都度、初期化処理が実行されます。

Execute Rule Script

Commandが複数定義された場合に、Commandの実行順やステータスによる処理分岐などの制御を GroovyScriptで記述することが可能です。
実行スクリプトが未指定の場合は定義されたCommandの順番に実行され、 実行結果ステータスは最後のCommandの戻り値が利用されます。

あらかじめ変数の cmd にCommandのインスタンスが配列でバインドされています。 また、request の変数名でRequestContextのインスタンスがバインドされています。

記述例
if (cmd[0].execute(request) == 'OK') {
    return cmd[1].execute(request)
} else {
    return cmd[2].execute(request)
}

2.3. 返却値について

以下の内容をレスポンスタイプの各形式にて返却します。

共通項目
項目 内容

status

Commandで実装した戻り値がセットされます。
エラーが発生した場合は、 FAILURE がセットされます。

exceptionType

エラーが発生した場合に、発生したExceptionのクラス名がセットされます。
エラーがApplicationExceptionの場合はそのまま設定され、それ以外の場合は WebApiRuntimeException をセットします。

exceptionMessage

エラーが発生した場合に、発生したExceptionに設定されているメッセージがセットされます。
エラーがApplicationExceptionの場合はそのまま設定され、それ以外の場合は固定メッセージがセットされます。

これ以外に、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もカスタマイズすることが可能です。
例 : javax.ws.rs.core.StreamingOutput
  • ソース

    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
例 : javax.ws.rs.core.Response.ResponseBuilder
  • ソース

    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を開く」を選択してください。

WebAPI Entity AuthSetting

登録済の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形式)

  • パラメータ

    パラメータ名 内容

    uploadFile

    アップロードするファイルをセットします

    uniqueKey

    UniqueKeyとして利用するプロパティ名をセットします

    asyncUpload

    trueが設定されている場合、非同期で実行します

  • 返却値

    • 同期実行の場合

      項目 内容

      insert

      Insert件数がセットされます

      update

      Update件数がセットされます

      delete

      Delete件数がセットされます

      この他に共通の返却値があります。

    • 非同期実行の場合

      共通の返却値のみ返ります。

Entityプロパティ値の指定

REST FORM、REST JSON、REST XMLのそれぞれの形式にてパラメータを設定して下さい。

プロパティ型 備考

AutoNumber

設定可能ですが、基本的には自動採番する項目の為セットしない事を推奨します。

Binary

lobIdを指定して下さい。

Boolean

true, falseを設定して下さい。

Date

FORM

yyyyMMdd

JSON

yyyy-MM-dd

XML

yyyy-MM-dd+09:00

DateTime

FORM

yyyyMMddHHmmss

JSON

getTime()したlong値

XML

yyyy-MM-ddTHH:mm:ss.000000000+09:00

Decimal

Expression

設定不可項目です。仮に設定しても対象外として処理されます。

Integer

LongText

Reference

参照先のOidを設定して下さい。JSON, XMLの場合はDefinitionNameが必須となります。

Select

SelectValueの値を設定して下さい。

String

Time

FORM

HH:mm:ss

JSON

HH:mm:ss

XML

HH:mm:ss+09:00

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かを選択できます。

Json

application/json

Xml

application/xml

コンテントタイプ

Content-Type

リクエスト送信時にどのタイプで送信するかを設定する項目です。 WebApiで許可しているコンテントタイプを設定して下さい。独自に作成したWebApiであればAdminConsoleから確認して下さい。

Form

application/x-www-form-urlencoded

Json

application/json

Xml

application/xml

Multipart

multipart/form-data

Token

x-transaction-token または _t

Tokenを設定する項目です。 但し、呼び出し時にuserId/passwordをヘッダーにて指定している場合はTokenは不要です。

WebApiのヘッダーにユーザID/パスワードを設定してログインした場合、そのAPI呼び出しの返却値 (HTTPヘッダー:ヘッダー名 x-transaction-token )として、そのログインセッション内で有効な固定Tokenを返却します。

ユーザID、パスワードが設定されている場合は必ず認証処理を実施します。未設定の場合はセッションにより認証を実施します。 その為、セッションで認証を実施する場合はユーザーID、パスワードを設定しないで下さい。

SOAP形式

以下の項目をリクエストヘッダに設定する必要があります。

項目名 namespace key value

ユーザーID

http://iplass.org/webapi/credential

id

iPLAssのテナントうに登録してあるユーザーアカウントを設定する項目です。 リクエストと同時に認証する場合のみ設定して下さい。

パスワード

http://iplass.org/webapi/credential

password

iPLAssのテナントうに登録してあるユーザーアカウントのパスワードを設定する項目です。 リクエストと同時に認証する場合のみ設定して下さい。

Token

x-transaction-token または _t

Tokenを設定する項目です。 但し、呼び出し時にuserId/passwordをヘッダーにて指定している場合はTokenは不要です。

WebApiのヘッダーにユーザーID/パスワードを設定してログインした場合、そのAPI呼び出しの返却値 (HTTPヘッダー:ヘッダー名 x-transaction-token )として、そのログインセッション内で有効な固定Tokenを返却します。

ユーザID、パスワードが設定されている場合は必ず認証処理を実施します。 未設定の場合はセッションにより認証を実施します。 その為、セッションで認証を実施する場合はユーザーID、パスワードを設定しないで下さい。

6.2. Session

セッションを利用すると、認証状態が維持され2回目以降のアクセスの際、認証処理が不要となります。 認証は比較的重い処理の為、特に理由がない限りはアクセスの都度認証処理を実施するのではなく、セッションの利用を推奨しています。

また、バイナリデータアップロードからエンティティデータの登録までは同一セッションである必要があります。 この処理を例にセッション維持の例について解説します。

バイナリデータをエンティティデータとして登録するには

バイナリデータアップロードAPIを利用した場合、バイナリデータはテンポラリ状態として保存され、汎用画面から利用可能な状態ではありません。 ファイルアップロードの返却値にあるlobIdを利用し、エンティティデータとして使える形式に変換後、エンティティデータとして登録する必要があります。

  • バイナリデータアップロード~ダウンロードまで

    WebAPI Session

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呼び出し時のTokenの設定方法

以下のいずれか方法でWebApi呼び出し時に設定します。

  • HTTPヘッダー(SOAPの場合はSOAPヘッダーでも可)に x-transaction-token のヘッダー名にて設定

  • WebApi呼び出し時のパラメータとして _t のパラメータ名にて設定

クライアントへのTokenの受け渡し方法

セキュリティを考慮し、Token生成専用の汎用のWebApiは作らず、次のいずれかの方法を利用して下さい。

  • WebApiを呼び出す直前の画面にサーバ側の処理(JSP、GroovyTemplate)でHTML内に直接埋め込み

  • Tokenを伴ったWebApi呼び出しの返却値として新たなTokenを発行

  • 固定Tokenの場合、ログイン処理のレスポンスとしてクライアントへ固定Tokenを返却し、 Cokkie保存などの方法によりクライアント内にセキュアに保持し、それを利用する

TemplateにてTokenの値を埋め込むためのユーティリティを提供しています。
詳細はJSPカスタムタグ・EL関数GroovyTemplateを参照してください。

Token Consume の例

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>
Web API