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形式にのみ対応しています。

  • OData形式のデータ連携(参照のみ)
    OData準拠のサービスエンドポイント、ODataで連携するEntityデータの公開設定を登録/管理する為の機能を提供しています。

  • メタデータに対する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形式と記載します。

カスタマイズで作成したCommandをWeb API経由で実行可能にするには、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 が実行される
AllowMethod
項目内容

Allow Method

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

Access Policy
項目内容

privilege execute

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

public webapi

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

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

check X-Requested-With header

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

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

synchroize on session

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

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

State Type

STATEFUL

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

STATELESS

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

Token Check
項目内容

Token Check

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

No Check

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

Check

呼び出し元で指定したTokenを利用し不正な遷移や重複サブミットを検出します。

Tokenのチェックを行う場合は、Tokenの値を送信元画面に埋め込み、リクエストパラメータで送信する必要があります。 詳しくはTokenチェックを参照してください。

use fixed Token

Tokenチェックに、セッション単位に固定に払いだされる固定Tokenを利用します。 CSRF(XSRF)対策のみ必要な場合は固定Tokenを利用可能です。

固定Tokenを利用する場合、送信元画面には固定Tokenの値を埋め込む必要があります。

consume a Token

このWebApi実行時にチェックしたTokenを消費します。
消費されたTokenは再利用できません(同一Tokenでリクエストが来た場合、エラーになります)。
重複リクエスト(トランザクションの重複起動)を防ぐためには、このフラグをONにします。

rollback on exception

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

Cache Control
項目内容

Cache Control

レスポンスのキャッシュ設定を指定します。

Cache

クライアントへ当該レスポンスのキャッシュを許可します。具体的には Cache-Control ヘッダに private を指定します。

Cache Public

共有キャッシュへ当該レスポンスのキャッシュを許可します。具体的には Cache-Control ヘッダに public を指定します。

Cache Publicを設定する場合、プロキシサーバやCDNがキャッシュする可能性があり、キャッシュのコントロールが難しくなる、
不特定多数のユーザに対して同一のキャッシュが返却されるので、注意が必要です。
例えば、ログイン後のユーザの個人情報が表示されるページをCache Publicしてしまった場合、そのユーザ以外の人が同一URLにアクセスした場合、本来参照できないはずの別ユーザの個人情報が参照できてしまいます。
Not Cache

クライアントへ当該レスポンスをキャッシュしないように指示します。具体的には Cache-Control ヘッダに no-store,no-cache を指定します。

Default

デフォルトは Cache-Control ヘッダを指定しません。

Max Ageの値を指定しない場合、ブラウザにより挙動が異なりますのでご注意ください。

Max Age

クライアントへ当該コンテンツのキャッシュ有効期間(秒)を通知します。
0未満の値は未設定とみなされます。

レスポンスのキャッシュが許可された場合( Cache-Control が private の場合 )、Cache-Control ヘッダに max-age 属性を追加します。

Restriction of Request
項目内容

Allow Request Content Types

許可するcontentTypeを指定します。未指定の場合は全て許可します。
複数のcontentTypeを指定する場合は、半角スペースで区切ってください。

WebApiは、applicaiton/json applicaiton/xml application/x-www-form-urlencoded multipart/form-data にのみ対応しているため、この範囲内での指定になります。

Max Request Body Size

リクエストボディの最大サイズ(Byte)を指定します。
contentTypeが application/x-www-form-urlencoded の場合は適用されません。

Max File Size

リクエストされるファイルの最大サイズ(Byte)を指定します。

CORS
項目内容

Access-Control-Allow-Origin

CORS (Cross-Origin Resource Sharing) の設定です。
アクセスを許可するドメイン名、または * (アスタリスク)を設定します。
* (アスタリスク)が設定されていた場合は、すべてのドメイン名からの接続を許可します。
複数のドメイン名を登録する場合は、半角スペースで区切ってください。
また、 *.isid.co.jp のように、ワイルドカードを指定することもできます。

Access-Controll-Allow-Credentials

CORS (Cross-Origin Resource Sharing) の設定です。
当該WebApi呼び出し時に認証情報(Cookie、Authorizationヘッダー等)を必要とする場合は、有効化します。 

OAuth
項目内容

support Bearer Token

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

Scopes

OAuth2.0 のScopeを定義します。AccessTokenベースでのアクセスの際、当該Scopeを保持するClientのみアクセス可能となります。 adminConsoleで指定する場合、scopeをスペースで区切った場合、ANDを意味し、改行で区切った場合ORを意味します。

scopeA scopeB
scopeC

上記の定義をした場合、 このWebApiにアクセスするためには、 scopeA 且つ scopeB を保持しているか、もしくは scopeC を保持している必要があります。

個別設定
項目内容

Request Type

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

REST JSON parameter

Request Type で REST JSON を選択した場合のみ設定可能です。

リクエストに含まれるJSON文字列をオブジェクトに変換する処理の設定です。 WebApiのクライアントからは、JSONは次の形で指定します。

GET, DELETEの場合

parameter name に指定した名前でクエリストリングに指定します

POST, PUTの場合

リクエストボディにJSON文字列を指定します

サーバ側では、JSON文字列を、 parameter type で指定したクラスに変換します。 parameter type 未指定の場合は java.util.Map として変換されます。

変換されたオブジェクトは、RequestContextから parameter name で指定したキー名でattributeから取得可能です。

例

parameter nameにvalueXを指定し、parameter typeにSomeTypeを指定した場合、

SomeType valueX = (SomeType) request#getAttribute("valueX")

で取得可能です。

parameter name の設定値が param 且つ parameter type が java.util.Map (もしくは未指定)の場合、
request.getParam("keyX") でMap内の値を取得することが可能です。

REST XML Parameter

Request Type で REST XML を選択した場合のみ設定可能です。

リクエストに含まれるXML文字列をオブジェクトに変換する処理の設定です。 WebApiのクライアントからは、XMLは次の形で指定します。

GET, DELETEの場合

parameter name に指定した名前でクエリストリングに指定します

POST, PUTの場合

リクエストボディにXML文字列を指定します

サーバ側ではXML文字列をJAXBにより変換します。 変換可能なオブジェクトはservice-configのWebApiJAXBServiceに設定されたクラスとなります。 設定については、 WebApiJAXBService を参照してください。

変換されたオブジェクトは、RequestContextから parameter name で指定したキー名でattributeから取得可能です。

例

parameter nameにvalueXを指定し、SomeTypeがWebApiJAXBServiceに設定される場合、

SomeType valueX = (SomeType) request.getAttribute("valueX")

で取得可能です。

Response Type

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

Parameter Mappings
項目内容

Parameter Name

パラメータマッピング機能における、パラメータ名を指定します。
パラメータマッピング を参照ください。

Map From

パラメータマッピング機能における、マッピング元を指定します。

Condition

パラメータマッピング機能における、マッピング処理を行う条件を指定します。

Execute Commands
項目内容

Command Name

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

Init Script

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

Results
項目内容

Attribute Name

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

返却可能な型は以下となります。

  • プリミティブ型(やそれに近しいクラス群、String、Date等)とその配列

  • Entity(GenericEntity)とその配列

  • Entityのプロパティで定義される型とその配列

  • 設定ファイルに定義された、JAXBでシリアライズ/デシリアライズ可能なアプリ側で定義したクラス

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

リクエストに含まれるパラメータを別名にマッピングしたり、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

たとえば、次のようなパラメータマッピング定義がある場合、

NameMap FromCondition

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

となります。

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 設定を有効化している場合、リクエストの都度、初期化処理が実行されます。

1つのAPIに対して複数のCommandを紐付けすることが可能です。

複数のCommandが紐付けされた場合、デフォルトでは次のような動作になります。

  • 定義された順番にCommandを実行

  • 最後に定義されたCommandの実行結果ステータスを全体の実行結果ステータスとする

条件により、処理順を変更するなど複雑な制御が必要な場合、Composite Command Configにて制御Scriptを記述可能です。

項目内容

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)
}

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

共通項目
項目内容

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

JavaにてCommandを実装する場合、クラス自体にアノテーションでWebApi定義を設定することが可能です。 単一のCommandに複数のWebApiをアノテーションすることも可能です。

アノテーションで定義されたWebApi定義はすべてのテナントで有効化されます。

WebApi定義を行うためのアノテーションは @WebApi です。設定可能な要素はadminConsoleでの設定項目に準じます。 詳細はjavadocを参照ください。

Commandクラス以外のクラス、インタフェースに対して@WebApi定義することも可能です。ただし、この場合command属性にてcommandClassを明示的に指定する必要があります。
アノテーションによる定義のサンプル
import org.iplass.mtp.command.annotation.webapi.WebApi;
:

@WebApi(name="tutorial",
    displayName="チュートリアルWebApi",
    accepts={RequestType.REST_FORM},
    methods={MethodType.GET, MethodType.POST},
    results={"resultValue", "anotherValue"}
)
@CommandClass(name="tutorial")
public class TutorialCommand implements Command {
    @Override
    public String execute(RequestContext request) {

        // 処理

        request.setAttribute("resultValue", someValue);
        request.setAttribute("anotherValue", anotherResultValue);

        if ( ... ) {
            return "NG";
        } else {
            return "OK";
        }
    }
}

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形式)

操作対象Entityに対してどの操作を許可するかといった権限の設定が必要になります。

権限の設定は「Entity」を右クリックして、「EntityWebApiを開く」を選択してください。

WebAPI Entity AuthSetting

登録済のEntity一覧が表示され、それぞれにINSERT、SELECT(Load)、SELECT(Query)、UPDATE、DELETEのチェックボックスが存在します。 操作対象Entityの許可したい処理をチェックして保存してください。

上記の例の場合、test.webapi.Test001、test.webapi.Test002、test.webapi.Test003に対して全ての処理が許可されている状態になっています。

Entityに対する検索処理はGETを利用します。

Entityデータをロードする場合は以下のAPIを利用します。

METHOD + パス処理

GET api/mtp/entity/[Entity定義名]/[oid]

oid指定でロード

GET api/mtp/entity/[Entity定義名]/[oid]/[version]

oid,version指定でロード

  • パラメータ

    パラメータ名内容

    withMappedByReference

    参照プロパティのうち、被参照プロパティを取得するか否かを指定します。 未指定時のデフォルトはfalseです。 デフォルト値は EntityWebApiService で設定可能です。

  • 返却値

    項目内容

    entity

    ロードされたEntityデータがセットされます

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

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句を指定します

      withMappedByReference

      参照プロパティのうち、被参照プロパティを取得するか否かを指定します。 未指定時のデフォルトはfalseです。 デフォルト値は EntityWebApiService で設定可能です。

    • Entity未指定

      パラメータ名内容

      query

      EQLを指定します

    • 共通

      パラメータ名内容

      tabular

      trueが設定されている場合、表形式で検索します。 SearchOption#setReturnStructuredEntity(false) で検索します。

      tabular=false もしくは未指定の場合、検索件数には制限があります。 最大件数、また、最大件数に達した場合の挙動(エラーとするか否か)は EntityWebApiService に定義されます。

      Acceptが application/json もしくは application/xml の場合に有効なフラグです。

      countTotal

      trueが設定されている場合、 SearchOption#setCountTotal(true) で検索します。

      Acceptが application/json もしくは application/xml の場合に有効なフラグです。
  • 返却値

    • リクエストヘッダのAcceptが text/csv の場合
      CSV形式の結果が返ります。

    • 上記以外の場合

      項目内容

      list

      検索結果がセットされます

      listHeader

      tabular=true が設定された場合、listで返却される表の各カラム名ががセットされます

      count

      countTotal=true で検索した場合に、件数がセットされます

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

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形式で)

Entityデータを登録する場合は以下のAPIを利用します。

METHOD + パス処理

POST api/mtp/entity/[Entity定義名]

Insertを実行

  • パラメータ

    パラメータ名内容

    entity

    登録するEntityデータをセットします

  • 返却値

    項目内容

    oid

    登録したEntityの oid がセットされます

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

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 がセットされます

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

Entityデータを削除する場合は以下のAPIを利用します。

METHOD + パス処理

DELETE api/mtp/entity/[Entity定義名]/[oid]

Deleteを実行

  • パラメータ

    パラメータ名内容

    timestamp

    削除対象Entityの更新日時が設定されている場合、 DeleteOption#setCheckTimestamp(true) で削除します。

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

CSV形式でEntityデータを一括で更新する場合は以下のAPIを利用します。

METHOD + パス処理

POST api/mtp/entity/[Entity定義名]

CSVによる一括更新 (multipart/form-data形式)

  • パラメータ

    パラメータ名内容

    uploadFile

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

    uniqueKey

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

    asyncUpload

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

  • 返却値

    • 同期実行の場合

      項目内容

      insert

      Insert件数がセットされます

      update

      Update件数がセットされます

      delete

      Delete件数がセットされます

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

    • 非同期実行の場合

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

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

Entityデータの参照が可能なODataサービスエンドポイントおよび、ODataで連携するEntityデータの公開設定を登録/管理する為の機能を提供します。

ODataアイコンを右クリックして「ODataを作成する」を選択してください。
作成時にODataで連携するEntityデータの公開タイプ(ODataType)を選択してください。

作成されたOData定義は、ODataサービス(OData準拠のRESTエンドポイント)のリソース(エンティティ セット)として公開されます。

OData定義の Name が、ODataのリソースパスになります。 / 区切りで階層化可能です。
例えば、Nameを path1/testResource と定義した場合、ODataのリソースパスは以下の様になります。

http(s)://[server]/[tenantContextPath]/api/mtp/odata/path1/testResource

また、ODataサービスは、OData定義の階層パス毎に定義されます。各ODataサービスのサービスルートURLは以下の通りです。

http(s)://[server]/[tenantContextPath]/api/mtp/odata/[OData定義の階層パス]/
(例)

下図のOData定義を例にした場合、path1階層 のサービスルートURLは、以下の通りです。

http(s)://[server]/[tenantContextPath]/api/mtp/odata/path1/
OData Definition Description

上記URLのODataサービスでは、path1階層 に存在するOData定義のみ(TestCube1、TestEntity1、TestEQL1)がリソースとして公開され、その他の階層に存在するOData定義(TestCube、TestEntity2等)は公開されません。

各ODataサービスのサービスドキュメントを以下のエンドポイントから取得可能です。

URL説明

GET /api/mtp/odata/[OData定義の階層パス]/

指定した階層パスのODataサービスにおいて、取得可能な全てのエンティティ セットを示すサービスドキュメントを返却します。

GET /api/mtp/odata/[OData定義の階層パス]/$metadata

指定した階層パスのODataサービスにおいて、取得可能な全てのエンティティ セットのデータ構造および操作を示すメタデータドキュメントを返却します。

設定可能な項目は以下の通りです。

設定項目設定内容

ODataType

Entityデータの公開タイプを ENTITY, CUBE, EQL から選択します。
OData定義作成時のダイアログでのみ選択可能です。

ENTITY

Entity定義を指定し、公開対象とする。

CUBE

Cubeの集計対象データを公開対象とする。

EQL

指定したEQLの実行結果を公開対象とする。

Entity定義を指定し、公開対象とするタイプ。
設定可能な項目は以下の通りです。

設定項目設定内容

Entity

公開対象とするEntity定義を選択してください。

PrimaryKey

エンティティ タイプ(OData)のキーとなるプロパティを選択してください。

  • 基本となるキープロパティは oid ですが、それ以外のプロパティも選択可能です。

oid 以外のプロパティを選択する場合、必須項目かつ値が対象のEntity内で一意となるプロパティを選択してください。

Published Property

選択したEntity定義の各プロパティに対する公開設定です。詳しい設定内容は Published Property を参照してください。

Navigation Property

選択したEntity定義のReference型プロパティをODataの Navigation Property として公開する為の設定です。詳しい設定内容は Navigation Property を参照してください。

設定項目説明

Publish

プロパティを公開するか否かを設定します。チェックを入れたプロパティが公開対象となります。デフォルトでは、いずれのプロパティにもチェックが入っていません。

Property

プロパティ名が表示されます。 編集不可 。

Publishing Name

エンティティ タイプ(OData)のプロパティ名を設定します。設定しない場合、 Property の値が使用されます。

設定項目説明

Property

プロパティ名が表示されます。 編集不可 。

Display Name

ODataのNavigation Property名を設定します。設定しない場合、 Property の値が使用されます。

OData Reference

参照先Entityの公開設定を行ったOData定義を選択してください。指定しない場合は、該当のReference型プロパティはNavigation Propertyとして公開されません。

  • 以下のエンドポイントが利用可能です。

URI

説明

GET /api/mtp/odata/[OData定義名]

OData定義で指定したEntity定義の全てのEntityデータを返却する

GET /api/mtp/odata/[OData定義名]('[キー値]')

キー指定で特定のEntityデータをロード

GET /api/mtp/odata/[OData定義名]('[キー値]')/[Navigation Property名]

キー指定で特定のEntityデータのNavigation Property(参照先のEntityデータ)をロード

Cubeの集計対象データをソースとして、公開対象とするタイプ。
設定可能な項目は以下の通りです。

設定項目設定内容

CubeName

対象とするCube定義を選択してください。

PrimaryKeyName

Cubeのキーとなるプロパティ名を指定します。

ItemList

選択したCube定義の Cube Item に関する公開設定です。詳しい設定内容は ItemList を参照してください。

設定項目説明

Publish

Cube Itemを公開するか否かを設定します。チェックを入れたCube Itemが公開対象となります。 デフォルトでは、いずれのCube Itemにもチェックが入っていません。

Nullable

Cube Itemがnullableな場合にチェックを入れます。

Multiple

Cube Itemの多重度が複数の場合にチェックを入れます。

Item

Cube Item名が表示されます。 編集不可 。

Publishing Name

エンティティ タイプ(OData)のプロパティ名を設定します。設定しない場合、Item の値が使用されます。

対象のCube定義でHashKeyに指定したアイテムの欄は、必ず Publish にチェックを入れてください。また、 Nullable にはチェックを入れないでください。
  • 以下のエンドポイントが利用可能です。

URI

説明

GET /api/mtp/odata/[OData定義名]

指定したCubeの集計対象データをソースとして、設定内容に基づきEntityデータを返却する

指定したEQLの実行結果を公開対象とするタイプ。
設定可能な項目は以下の通りです。

設定項目設定内容

EQL TEMPLATE

実行するEQLをGroovyTemplate書式を利用して指定します。

PrimaryKeyName

ODataエンティティ タイプのキーとなるプロパティ名を指定します。

PropertyGrid

ODataエンティティ タイプのプロパティとEQLの実行結果の紐づけ設定です。 Add Property 、 Delete Property を押下して、必要に応じて項目を追加、削除してください。編集したい列をクリックすると編集ができます。詳しい設定内容は PropertyGrid を参照してください。

設定項目設定内容

Nullable

プロパティがnullableな場合に設定します。

Multiple

プロパティの多重度が複数の場合に設定します。

Name

ODataプロパティに紐づけるプロパティ名(EQLのSELECT句に指定したカラム名または、Entityのプロパティ名)を指定してください。

Publishing Name

エンティティ タイプ(OData)のプロパティ名を設定します。設定しない場合、 Name の値が使用されます。

Type

ODataプロパティのデータ型を選択します。

PrimaryKeyName に設定したプロパティは、必ず PropertyGrid で公開する様に設定してください。また、 Nullable にチェックを入れないでください。
  • 以下のODataエンドポイントを利用可能です。

URI

説明

GET /api/mtp/odata/[OData定義名]

指定したEQLの実行結果に基づくEntityデータを返却する

iPLAssで対応しているODataの Query Options は以下の通りです。

コマンド説明

$filter

結果 (行) をフィルターします。iPLAssで対応している論理演算子については、 $filterを参照してください。

$orderby
※ CUBE は対応していません。

結果を指定した並び順でソートします。

$top

指定した個数のデータを返却します。

$skip

指定した個数のデータを結果から除外します。

$expand
※ CUBE、EQL は対応していません。

Navigation Propertyで関連づけられたエンティティセットを一緒に返却します。

Navigation Propertyで関連付けされるReferenceプロパティの多重度が複数の場合について、現時点においては対応していません。

$select

指定したプロパティのみを返却します。

$search

検索条件(フリーテキスト)の単語を指定し、条件に一致した結果を返却します。全てのODataプロパティが検索の対象です。

対応している論理演算子は以下の通りです。

パラメータ論理演算子

eq

=

ne

!=

gt

>

ge

>=

lt

<

le

<=

add

+

sub

-

mul

*

div

/

mod演算子は未対応です。

以下では、各ODataTypeの利用例を説明します。

  • Entity

    全ての利用例で共通して用いる動作確認用のEntity定義(Book)を登録します。

OData Sample Entity Book

ODataTypeに ENTITY を指定する場合の利用例です。

  • OData定義

    ODataTypeに ENTITY を指定してOData定義を作成し、Entity欄に先ほど作成したEntity定義(Book)を指定します。
    また、公開したいPropertyについては、 Published Property の Publish 欄にチェックを入れます。

OData Sample Definition Entity
  • 動作確認

    以下のURLにリクエストすると、指定したOData定義に従ってEntityデータを取得できることが確認できます。

http(s)://[server]/[tenantContextPath]/api/mtp/odata/BookEntity

  また、以下の様に Queryオプション を利用して、データを取得することも可能です。

// titleの昇順で並び替え、上位5件のデータを取得する
http(s)://[server]/[tenantContextPath]/api/mtp/odata/BookEntity?$orderby=title&$top=5
全てのODataTypeにおいて、Personal Access Tokenを利用し、ODataエンドポイントへアクセス時にBearer Tokenによる認証を行うことが可能です。
Personal Access Tokenについては Application Maintenanceを参照してください。

以下では、Navigation Propertyを用いて、参照関係にあるEntityデータを取得する例を説明します。

  • Entity(参照元)

    共通で用いるEntity定義(Book)を参照する、新たなEntity定義(Person)を作成します。

OData Sample Entity Person
  • OData定義(参照元)

    OData定義を作成し、Entity欄に先ほど作成したEntity定義(Person)を指定します。
    Navigation Property の Publishing Name 欄にNavigation Propert名を、OData Reference 欄 に参照先Entity(Book)の公開設定を行ったOData定義名を指定してください。

OData Sample Definition ReferenceEntity
  • 動作確認

    以下のURLにリクエストすると、参照関係にあるEntityデータの取得が可能です。

http://hostname:port/{コンテキスト名}/{テナント名}/api/mtp/odata/PersonEntity('キー値')/Book

  また、 Queryオプション の$expandを利用して、参照元のEntityデータとNavigation Propertyで関連づけられた参照先のEntityデータを一緒に取得することが可能です。

http://hostname:port/{コンテキスト名}/{テナント名}/api/mtp/odata/PersonEntity('キー値')?$expand=Book

ODataTypeに CUBE を指定する場合の利用例です。

  • Cube定義

    動作確認用のCube定義を作成します。

OData Sample CUBE Book
  • OData定義

    OData定義を作成し、CubeName欄に先ほど作成したCube定義(Book)を指定します。 公開したいItemについては、 ItemList の Publish 欄にチェックを入れます。必要に応じて、NullableとMultipleの設定を行います。

OData Sample Definition CUBE
  • 動作確認

    以下のURLにリクエストすると、指定したOData定義に従ってEntityデータを取得できることが確認できます。

http://hostname:port/{コンテキスト名}/{テナント名}/api/mtp/odata/BookCube

ODataTypeに EQL を指定する場合の利用例です。

  • OData定義

    OData定義を作成し、 EQL TEMPLATE に実行したいEQLを指定します。
    PrimaryKeyName にエンティティ タイプ(OData)のキーとなるプロパティ名を入力します。 PropertyGridで、EQLの実行結果とODataエンティティ タイプの紐づけ設定を行います。

OData Sample Definition EQL
  • 動作確認

    以下のURLにリクエストすると、指定したOData定義に従ってEntityデータを取得できることが確認できます。

http://hostname:port/{コンテキスト名}/{テナント名}/api/mtp/odata/BookEql

メタデータに対する操作(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を参照してください。

メタデータの更新用APIを利用するには、WebApiServiceの enableDefinitionApi 設定が必要になります。
詳細については、 WebApiServiceを参照してください。

メタデータをロードする場合はGETを利用します。

METHOD + パス処理

GET api/mtp/definition/[メタデータ定義パス]

指定されたメタデータ定義をLoad

  • パラメータ

    項目内容

    recursive

    trueが設定されている場合、指定されているパス配下を再帰的にすべて検索します。

  • 返却値

    • パスの最後が / の場合

      項目内容

      list

      パス配下の検索結果がセットされます

    • 上記以外の場合

      項目内容

      definition

      指定パスの検索結果がセットされます

    • 共通

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

メタデータを登録する場合はPOSTを利用します。

METHOD + パス処理

POST api/mtp/definition/[メタデータ定義パス]

指定されたメタデータ定義をCreate

  • パラメータ

    項目内容

    definition

    登録するメタデータ定義を設定します

  • 返却値

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

メタデータを更新する場合はPUTを利用します。

METHOD + パス処理

PUT api/mtp/definition/[メタデータ定義パス]

指定されたメタデータ定義をUpdate

  • パラメータ

    項目内容

    definition

    登録するメタデータ定義を設定します

  • 返却値

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

メタデータを削除する場合はDELETEを利用します。

METHOD + パス処理

DELETE api/mtp/definition/[メタデータ定義パス]

指定されたメタデータ定義をDelete

  • パラメータ
    パラメータはありません。

  • 返却値

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

バイナリデータのアップロード、ダウロードを提供します。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形式)

バイナリの操作用APIを利用するには、WebApiServiceの enableBinaryApi 設定が必要になります。
詳細については、 WebApiServiceを参照してください。

ファイルをダウンロードする場合はGETを利用します。

METHOD + パス処理

GET api/mtp/bin/[lobId]

lobId指定でダウンロード

  • パラメータ

    パラメータはありません。

  • 返却値
    バイナリファイルを返します。

ファイルをアップロードする場合はPOSTを利用します。

METHOD + パス処理

POST api/mtp/bin

uploadFileというキー名でファイルアップロード (multipart/form-data形式)

  • パラメータ

    パラメータ名内容

    uploadFile

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

  • 返却値

    項目内容

    lobId

    登録したBinaryReferenceのLobIdがセットされます

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

WSDLに記載されている通り、 BinaryWebService.fileDownload を実行します。

  • パラメータ

    引数No.型内容

    第1引数

    String

    lobId

  • 返却値
    バイナリデータが返却されます。
    ファイルがない場合は404エラーが、その他エラーの場合は500エラーが返却されます。

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がセットされます

Web APIを利用する際に必要なリクエストヘッダの項目について説明します。 大きく分けてREST形式の場合とSOAP形式の2種類があります。

以下の項目を必要に応じてHTTPリクエストヘッダに設定します。

項目名namevalue

ユーザーID

X-Auth-Id

認証用のユーザIDを指定するカスタムヘッダです。

セッションが有効でログイン済みの場合、デフォルトではログイン済みのセッションが優先されます。
IdPasswordAutoLoginHandler の設定を参照ください。

パスワード

X-Auth-Password

認証用のユーザのパスワードを指定するカスタムヘッダです。X-Auth-Idと同時に設定します。

認可要求

Authorization

認証・認可要求をする際に指定可能です。 iPLAssは以下の認可要求タイプをサポートします。

同時にカスタム認証ヘッダ(X-Auth-Id/X-Auth-Password)が指定される場合はそちらが優先されます
Basic

ベーシック認証方式によるユーザID/パスワードの指定が可能です。

セッションが有効でログイン済みの場合、デフォルトではログイン済みのセッションが優先されます。
また、デフォルトの設定ではBasic認証方式は有効化されていません。
IdPasswordAutoLoginHandler の設定を参照ください。
Bearer

Bearer Token(RFC6750)による認証/認可が可能です。 Bearer Tokenを利用する場合はそれぞれのWeb API定義にて有効化する必要があります。

セッションが有効でログイン済みの場合、デフォルトではログイン済みのセッションが優先されます。
BearerTokenAutoLoginHandler の設定を参照ください。

クッキー(セッションIDなど)

Cookie

ステートフルなWeb APIを呼び出す際にはセッションIDなどが設定されているCookieを有効化する必要があります。

アクセプト

Accept

返却値のメディアタイプ形式を設定する項目です。 application/json か application/xml もしくはカスタムWeb APIで定義するメディアタイプを指定します。

コンテントタイプ

Content-Type

リクエスト送信時にどのタイプで送信するかを設定する項目です。 Web API定義で許可しているコンテントタイプを設定して下さい。 次のいずれかを設定します。

application/x-www-form-urlencoded
multipart/form-data

リクエストはREST FORMとして処理されます

application/json

リクエストはREST JSONとして処理されます

application/xml

リクエストはREST XMLとして処理されます

未指定の場合

リクエストがGET/DELETE時はREST FORMとして処理されます

Token

X-Transaction-Token

トランザクションToken(もしくはCSRF(XSRF)対策用Token)を設定する項目です。

また、 Web APIのヘッダにユーザID/パスワードを設定してログインした場合、且つWeb APIがステートフルの場合、そのAPI呼び出しのレスポンス (HTTPヘッダ:ヘッダ名 X-Transaction-Token )として、そのログインセッション内で有効な固定Tokenを返却します。

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

SOAPヘッダ
項目名namespacenamevalue

ユーザーID

http://iplass.org/webapi/credential

id

認証用のユーザIDを指定する項目です。

セッションが有効でログイン済みの場合、デフォルトではログイン済みのセッションが優先されます。
IdPasswordAutoLoginHandler の設定を参照ください。

パスワード

http://iplass.org/webapi/credential

password

認証用のユーザのパスワードを指定します。

HTTPヘッダ
項目名namevalue

クッキー(セッションIDなど)

Cookie

ステートフルなWeb APIを呼び出す際にはセッションIDなどが設定されているCookieを有効化する必要があります。

Token

X-Transaction-Token

トランザクションToken(もしくはCSRF(XSRF)対策用Token)を設定する項目です。

SOAPヘッダにユーザID/パスワードを設定してログインした場合、且つWeb APIがステートフルの場合、そのAPI呼び出しの返却値 (HTTPヘッダ:ヘッダ名 X-Transaction-Token )として、そのログインセッション内で有効な固定Tokenを返却します。

Web API定義にてステートフル、ステートレスの指定が可能です。 ステートフルの場合は、Cookieを利用しセッションが維持されます。 同一ユーザにて複数回連続でWeb APIを呼び出す場合、セッションを利用すると、認証状態が維持され2回目以降のアクセスの際に認証処理が不要となります。 認証は比較的重い処理の為、前記のような場合はセッションの利用を推奨しています。

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

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

    WebAPI Session

下記は「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で接続した際には別セッションとなります。

下記では「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で接続した際には別セッションとなります。

Token(CSRF対策、トランザクション重複起動対策)のチェックを行う場合は、Tokenの値をリクエストパラメータで送信する必要があります。 またTokenの値をあらかじめ取得しておく必要があります。

Web API呼び出し時のTokenの設定方法

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

  • HTTPヘッダ(SOAPの場合はSOAPヘッダでも可)に X-Transaction-Token のヘッダ名にて設定

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

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

次のいずれかの方法を利用して下さい。

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

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

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

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

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_4_0.xsd"
  version="4.0">

    :

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