Web API

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形式にのみ対応しています。
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形式での通信と同義です。

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. カスタム 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 と２つ定義した場合、以下のリクエストが対象になります。

name の最後に許可するMETHODを付与する方式で定義されたWebAPIにおいてCORSの設定を行いたい場合、その定義方法は特殊になります。例えば、Web API名として mtp/entity/GET 、mtp/entity/PUT と２つ定義した場合、末尾のメソッド名を抜いた mtp/entity という名前の空のWebApi定義を作成し、当該WebAPI定義にてCORSの設定を行ってください（WebFrontendServiceのrequestRestrictionでCORSの設定を行うことも可能です）。

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）を指定します。全てチェックされていない場合は全メソッドでのアクセスが可能です。デフォルトでは全てチェックされていない状態となります。ひとつでもチェックされている場合は、チェックされているメソッドでのみアクセスが可能となります。

項目内容

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: クライアントへ当該レスポンスのキャッシュを許可します。具体的には Cache-Control ヘッダに private を指定します。
Cache Public: 共有キャッシュへ当該レスポンスのキャッシュを許可します。具体的には Cache-Control ヘッダに public を指定します。

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

Not Cache: クライアントへ当該レスポンスをキャッシュしないように指示します。具体的には Cache-Control ヘッダに private, no-store, no-cache, must-revalidate を指定します。
Default: service-config内の WebFrontendService の defaultCacheControlType の設定が適用されます。

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

Max Age

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

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

項目内容

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) の設定です。アクセスを許可するドメイン名、または `` （アスタリスク）を設定します。 `` （アスタリスク）が設定されていた場合は、すべてのドメイン名からの接続を許可します。複数のドメイン名を登録する場合は、半角スペースで区切ってください。また、 `*.dentsusoken.com` のように、ワイルドカードを指定することもできます。
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でシリアライズ/デシリアライズ可能なアプリ側で定義したクラスレスポンスとして返却するデータ構造をカスタマイズすることが可能です。カスタマイズについては返却値についてを参照ください。

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

変数名

説明

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

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です。

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.4. 返却値について

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

共通項目
項目	内容
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"
}

レスポンスのカスタマイズ

以下の条件に一致する場合は、レスポンス内容を自由にカスタマイズすることが可能です。

返却値が１つである
上記の返却値に設定されたオブジェクトが、以下のいずれかであること
- jakarta.ws.rs.core.StreamingOutput
- jakarta.ws.rs.core.Response.ResponseBuilder

ResponseBuilderにおいては、HTTPステータスやContentTypeもカスタマイズすることが可能です。

例 : jakarta.ws.rs.core.StreamingOutput

ソース

import java.io.BufferedWriter;
import java.io.IOException;
import java.io.OutputStream;
import java.io.OutputStreamWriter;

import jakarta.ws.rs.WebApplicationException;
import jakarta.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
```

例 : jakarta.ws.rs.core.Response.ResponseBuilder

ソース

import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.Response.ResponseBuilder;
import jakarta.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
```

2.5. WebApi定義（アノテーション）

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";
        }
    }
}

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

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指定でロード

METHOD + パス

処理

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

oid指定でロード

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

oid,version指定でロード

パラメータ

パラメータ名内容

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

withMappedByReference

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

返却値

項目内容

entity

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

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

項目	内容
entity	ロードされたEntityデータがセットされます

Query(searchEntity)

Entityデータに対するQuery検索は２種類あります。 Entityを指定して検索する方法とEQLを指定する方法です。

METHOD + パス	処理
GET api/mtp/entity/[Entity定義名]?filter=[where条件]	where句指定して検索
GET api/mtp/entity?query=[EQL]	EQL文を指定して検索

METHOD + パス

処理

GET api/mtp/entity/[Entity定義名]?filter=[where条件]

where句指定して検索

GET api/mtp/entity?query=[EQL]

EQL文を指定して検索

パラメータ

Entity名指定

パラメータ名内容

パラメータ名	内容
filter	パスで指定したEntityに対するwhere句を指定します
withMappedByReference	参照プロパティのうち、被参照プロパティを取得するか否かを指定します。未指定時のデフォルトは `false` です。デフォルト値は EntityWebApiService で設定可能です。

filter

パスで指定したEntityに対するwhere句を指定します

withMappedByReference

Entity未指定

パラメータ名内容

query

EQLを指定します

パラメータ名	内容
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 の場合に有効なフラグです。

footer

trueが設定されている場合、あらかじめ設定ファイルで定義された固定のフッター文字列を、 CSVファイルの最終行に出力するようにします。未指定時のデフォルトは false です。

フッター文字列は EntityWebApiService で設定可能です。

Acceptが text/csv の場合に有効なフラグです。

返却値

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

上記以外の場合

項目内容

項目	内容
list	検索結果がセットされます
listHeader	`tabular=true` が設定された場合、listで返却される表の各カラム名がセットされます
count	`countTotal=true` で検索した場合に、件数がセットされます

list

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

listHeader

tabular=true が設定された場合、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形式で）

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を実行

METHOD + パス

処理

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

Insertを実行

パラメータ

パラメータ名内容

パラメータ名	内容
entity	登録するEntityデータをセットします
withValidation	Entity登録時のオプション、バリデーションを行うかを `true/false` で指定します。デフォルトは `true` です。
notifyListeners	Entity登録時のオプション、EntityEventListenerに通知するかを `true/false` で指定します。デフォルトは `true` です。
enableAuditPropertySpecification	Entity登録時のオプション、createBy,createDate,updateBy,updateDateの値を指定してその値のまま登録するかを `true/false` で指定します。デフォルトは `false` です。
regenerateOid	Entity登録時のオプション、常に（oidがEntityに指定してあった場合でも）oidを新規生成するかを `true/false` で指定します。デフォルトは `true` です。
regenerateAutoNumber	Entity登録時のオプション、常に（autoNumber項目がセットされていた場合でも）autoNumber項目を新規生成するかを `true/false` で指定します。デフォルトは `false` です。
versionSpecified	Entity登録時のオプション、バージョン管理されているEntityを登録する際に、指定したバージョン番号のデータとして登録するかを `true/false` で指定します。デフォルトは `false` です。
localized	Entity登録時のオプション、localized項目を更新対象とするかを `true/false` で指定します。デフォルトは `false` です。

entity

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

withValidation

Entity登録時のオプション、バリデーションを行うかを true/false で指定します。デフォルトは true です。

notifyListeners

Entity登録時のオプション、EntityEventListenerに通知するかを true/false で指定します。デフォルトは true です。

enableAuditPropertySpecification

Entity登録時のオプション、createBy,createDate,updateBy,updateDateの値を指定してその値のまま登録するかを true/false で指定します。デフォルトは false です。

regenerateOid

Entity登録時のオプション、常に（oidがEntityに指定してあった場合でも）oidを新規生成するかを true/false で指定します。デフォルトは true です。

regenerateAutoNumber

Entity登録時のオプション、常に（autoNumber項目がセットされていた場合でも）autoNumber項目を新規生成するかを true/false で指定します。デフォルトは false です。

versionSpecified

Entity登録時のオプション、バージョン管理されているEntityを登録する際に、指定したバージョン番号のデータとして登録するかを true/false で指定します。デフォルトは false です。

localized

Entity登録時のオプション、localized項目を更新対象とするかを true/false で指定します。デフォルトは false です。

Entity登録時のオプションについては、EntityWebApiService の permitEntityCrudApiOptionsRoles で指定したロールのユーザか、Adminユーザーの場合に有効になります。

返却値

項目内容

oid

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

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

項目	内容
oid	登録したEntityの `oid` がセットされます

Update

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

METHOD + パス	処理
PUT api/mtp/entity/[Entity定義名]/[oid]	Updateを実行
PUT api/mtp/entity/[Entity定義名]/[oid]/[version]	バージョン指定でUpdateを実行

METHOD + パス

処理

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

Updateを実行

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

バージョン指定でUpdateを実行

パラメータ

パラメータ名内容

パラメータ名	内容
entity	更新するEntityデータをセットします
withValidation	Entity更新時のオプション、バリデーションを行うかを `true/false` で指定します。デフォルトは `true` です。
notifyListeners	Entity更新時のオプション、EntityEventListenerに通知するかを `true/false` で指定します。デフォルトは `true` です。
localized	Entity更新時のオプション、localized項目を更新対象とするかを `true/false` で指定します。デフォルトは `false` です。
forceUpdate	Entity更新時のオプション、変更項目が一つもなくとも、強制的に更新処理をする（結果、タイムスタンプ、更新者が更新される）かを `true/false` で指定します。デフォルトは `false` です。
updateProperties	Entity更新時のオプション、更新対象のプロパティを設定します。複数の項目がある場合はカンマ区切りで指定します。
checkTimestamp	Entity更新時のオプション、更新時にタイムスタンプチェックを行うかを `true/false` で指定します。デフォルトは `true` です。
targetVersion	Entity更新時のオプション、バージョン管理時、更新対象のバージョン（ `CURRENT_VALID/SPECIFIC/NEW` ）を指定します。デフォルトは `CURRENT_VALID` です。
purgeCompositionedEntity	Entity更新時のオプション、参照関係がCOMPOSITIONと定義されている参照先Entityが、参照から削除された場合に物理削除するかを `true/false` で指定します。デフォルトは `true` です。
checkLockedByUser	Entity更新時のオプション、ユーザーによってロックされている場合、更新エラー(EntityLockedByUserException)とするかを `true/false` で指定します。デフォルトは `true` です。

entity

更新するEntityデータをセットします

withValidation

Entity更新時のオプション、バリデーションを行うかを true/false で指定します。デフォルトは true です。

notifyListeners

Entity更新時のオプション、EntityEventListenerに通知するかを true/false で指定します。デフォルトは true です。

localized

Entity更新時のオプション、localized項目を更新対象とするかを true/false で指定します。デフォルトは false です。

forceUpdate

Entity更新時のオプション、変更項目が一つもなくとも、強制的に更新処理をする（結果、タイムスタンプ、更新者が更新される）かを true/false で指定します。デフォルトは false です。

updateProperties

Entity更新時のオプション、更新対象のプロパティを設定します。複数の項目がある場合はカンマ区切りで指定します。

checkTimestamp

Entity更新時のオプション、更新時にタイムスタンプチェックを行うかを true/false で指定します。デフォルトは true です。

targetVersion

Entity更新時のオプション、バージョン管理時、更新対象のバージョン（ CURRENT_VALID/SPECIFIC/NEW ）を指定します。デフォルトは CURRENT_VALID です。

purgeCompositionedEntity

Entity更新時のオプション、参照関係がCOMPOSITIONと定義されている参照先Entityが、参照から削除された場合に物理削除するかを true/false で指定します。デフォルトは true です。

checkLockedByUser

Entity更新時のオプション、ユーザーによってロックされている場合、更新エラー(EntityLockedByUserException)とするかを true/false で指定します。デフォルトは true です。

Entity更新時のオプションについては、EntityWebApiService の permitEntityCrudApiOptionsRoles で指定したロールのユーザか、Adminユーザーの場合に有効になります。

返却値

項目内容

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が設定されている場合、非同期で実行します

truncate

CSVアップロードのオプション、既存データをすべて削除するかを true/false で指定します。デフォルトは false です。

bulkUpdate

CSVアップロードのオプション、BulkUpdateで更新するかを true/false で指定します。デフォルトは false です。

errorSkip

CSVアップロードのオプション、エラーデータはSkipし処理を続行するかを true/false で指定します。デフォルトは false です。

ignoreNotExistsProperty

CSVアップロードのオプション、存在しないプロパティは無視してデータを取込むかを true/false で指定します。デフォルトは true です。

withValidation

CSVアップロードのオプション、バリデーションを行うかを true/false で指定します。デフォルトは true です。

notifyListeners

CSVアップロードのオプション、EntityEventListenerに通知するかを true/false で指定します。デフォルトは true です。

updateDisupdatableProperty

CSVアップロードのオプション、更新不可項目を更新対象にするかを true/false で指定します。デフォルトは false です。

insertEnableAuditPropertySpecification

CSVアップロードのオプション、InsertするEntityにcreateBy,createDate,updateBy,updateDateの値を指定するかを true/false で指定します。デフォルトは false です。

prefixOid

CSVアップロードのオプション、Import時にOIDに付与するPrefixを指定します。

commitLimit

CSVアップロードのオプション、Commit単位(件数)を指定します。

fourceUpdate

CSVアップロードのオプション、変更項目が一つもなくとも、強制的に更新処理をする（結果、タイムスタンプ、更新者が更新される）かを true/false で指定します。デフォルトは false です。

locale

CSVアップロードのオプション、ファイル出力時のロケールを指定します。

timezone

CSVアップロードのオプション、ファイル出力時のタイムゾーンを指定します。

CSVアップロードのオプションについては、EntityWebApiService の permitEntityCrudApiOptionsRoles で指定したロールのユーザか、Adminユーザーの場合に有効になります。

返却値

同期実行の場合

項目

内容

insert

Insert件数がセットされます

update

Update件数がセットされます

delete

Delete件数がセットされます

error

Error件数がセットされます（CSVアップロードのオプションが有効な場合のみ）

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

非同期実行の場合

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

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

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

4.1. OData定義

OData定義の作成

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

ODataサービス

作成された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/

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

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

PrimaryKey

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

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

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

Published Property

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

Navigation Property

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

Published Property

設定項目説明

Publish

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

Property

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

Publishing Name

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

Navigation 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

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

設定項目設定内容

CubeName

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

PrimaryKeyName

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

ItemList

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

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の実行結果を公開対象とするタイプ。
設定可能な項目は以下の通りです。

設定項目設定内容

EQL TEMPLATE

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

PrimaryKeyName

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

PropertyGrid

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

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データを返却する

4.2. Queryオプション

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

コマンド説明

$filter

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

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

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

$top

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

$skip

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

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

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

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

$select

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

$search

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

$filter

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

パラメータ

論理演算子

add

sub

mul

div

mod演算子は未対応です。

4.3. 利用例

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

Entity

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

ENTITY

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

OData定義

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

動作確認

以下の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

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

Entity（参照元）

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

OData定義（参照元）

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

動作確認

以下の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

CUBE

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

Cube定義

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

OData定義

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

動作確認

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

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

EQL

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

OData定義

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

動作確認

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

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

5. メタデータ 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を参照してください。

5.1. 利用設定

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

5.2. Load

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

METHOD + パス

処理

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

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

パラメータ

項目内容

recursive

trueが設定されている場合、指定されているパス配下を再帰的にすべて検索します。
返却値
- パスの最後が / の場合
  
  項目内容
  
  list
  
  パス配下の検索結果がセットされます
- 上記以外の場合
  
  項目内容
  
  definition
  
  指定パスの検索結果がセットされます
- 共通
  
  この他に共通の返却値があります。

5.3. Create

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

METHOD + パス

処理

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

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

パラメータ

項目内容

definition

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

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

5.4. Update

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

METHOD + パス

処理

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

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

パラメータ

項目内容

definition

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

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

5.5. Delete

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

METHOD + パス

処理

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

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

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

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

6. バイナリ操作 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形式)

6.1. 利用設定

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

6.2. REST ダウンロード

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

METHOD + パス

処理

GET api/mtp/bin/[lobId]

lobId指定でダウンロード

パラメータ

パラメータはありません。
返却値
バイナリファイルを返します。

6.3. REST アップロード

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

METHOD + パス

処理

POST api/mtp/bin

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

パラメータ

パラメータ名内容

uploadFile

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

項目内容

lobId

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

この他に共通の返却値があります。
Service-Config WebApiService 関連設定

項目内容

acceptMimeTypesPatternInBinaryApi

アップロードファイル種類を限定することが可能です。

6.4. SOAP ダウンロード

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

パラメータ

引数No. 型内容

第1引数

String

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

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

7. 共通設定

7.1. リクエストヘッダ

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

REST形式

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

項目名 name value

ユーザー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など）

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

アクセプト

返却値のメディアタイプ形式を設定する項目です。 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形式

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

SOAPヘッダ

項目名

namespace

name

value

ユーザーID

http://iplass.org/webapi/credential

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

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

パスワード

http://iplass.org/webapi/credential

password

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

HTTPヘッダ
項目名	name	value
クッキー（セッションIDなど）	Cookie	ステートフルなWeb APIを呼び出す際にはセッションIDなどが設定されているCookieを有効化する必要があります。
Token	X-Transaction-Token	トランザクションToken（もしくはCSRF(XSRF)対策用Token）を設定する項目です。 SOAPヘッダにユーザーID/パスワードを設定してログインした場合、且つWeb APIがステートフルの場合、そのAPI呼び出しの返却値（HTTPヘッダ：ヘッダ名 `X-Transaction-Token` )として、そのログインセッション内で有効な固定Tokenを返却します。

7.2. Session

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

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

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

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

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

REST形式

下記は「HTTP Client」を利用した場合の例を記載しています。

// １．セッション情報を保存する為の下準備
CookieStore cookieStore = new BasicCookieStore();
HttpContext httpContext = new BasicHttpContext();

// ２．セッションを保存する為にコンテキストを作成
httpContext.setAttribute(ClientContext.COOKIE_STORE, cookieStore);

// ３．バイナリデータアップロードAPI呼び出し時に上記作成したコンテキストをセット
HttpResponse response = httpClient.execute(httpPost, httpContext);

// ４．下記コマンドでセッションを切ります
httpClient.getConnectionManager().shutdown();

// ５．コンテキストを利用して再接続
HttpResponse response = httpClient.execute(httpPost, httpContext);

上記ソースの１～３を実施しないと４でセッションが切断され、５で接続した際には別セッションとなります。

SOAP形式

下記では「JAX-WS（Metoro）」を利用した場合の例を記載しています。

// １．BindingProviderの作成
WSBindingProvider bp = (WSBindingProvider) port;

// ２．セッション利用の設定
((BindingProvider) port).getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);

// ３．バイナリデータアップロード処理の呼び出し
WebApiResponse result = port.upload("uploadFile", "sample.jpg", dhandler);

// ４．呼び出し後にセッション情報を取得
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");

// ５．新規BindingProviderの作成
WSBindingProvider commandbp = (WSBindingProvider) commandPort;

// ６．セッション情報をセット
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);

上記ソースの１～５を実施しないと３完了後にセッションが切断され、６で接続した際には別セッションとなります。

7.3. Tokenチェック

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を参照してください。

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

Web API

1. Web APIについて

2. カスタム WebApi

2.1. WebApi定義（AdminConsole）

WebApi定義の作成

WebApiの設定項目

共通設定

固有設定

2.2. パラメータマッピング

パスのマッピング

マッピング条件の指定

2.3. Commandの設定

複合Commandの設定

Composite Command Configの設定

2.4. 返却値について

レスポンスのカスタマイズ

2.5. WebApi定義（アノテーション）

3. Entity CRUD API

3.1. 権限設定

3.2. 検索処理

Load

Query(searchEntity)

3.3. 更新処理

Insert

Update

Delete

CSVアップロード

Entityプロパティ値の指定

4. OData

4.1. OData定義

OData定義の作成

ODataサービス

設定

共通項目

ENTITY

Published Property

Navigation Property

CUBE

ItemList

EQL

PropertyGrid

4.2. Queryオプション

$filter

4.3. 利用例

ENTITY

Navigation Property

CUBE

EQL

5. メタデータ CRUD API

5.1. 利用設定

5.2. Load

5.3. Create

5.4. Update

5.5. Delete

6. バイナリ 操作 API

6.1. 利用設定

6.2. REST ダウンロード

6.3. REST アップロード

6.4. SOAP ダウンロード

6.5. SOAP アップロード

7. 共通設定

7.1. リクエストヘッダ

REST形式

SOAP形式

7.2. Session

REST形式

SOAP形式

7.3. Tokenチェック

7.4. SOAPエンドポイント

6. バイナリ操作 API