Web API

Commandメタデータとして定義したカスタムロジックをWeb APIメタデータを利用して、 外部からRESTful形式(以下、REST)、 SOAP WSDL形式 で呼び出すことが可能です。

またEntityに対するCRUD操作やメタデータ定義に対するCRUD操作、 バイナリファイルのアップロード、ダウンロードを行うApiを提供します。

Web APIには以下の機能・特徴があります。

  • カスタマイズコマンドの実行
    カスタマイズで作成したCommandをWeb API経由で呼び出し実行可能です。
    本機能はREST形式、 SOAP WSDL形式 に対応しています。

  • Entityに対するCRUD操作の実行
    Entityデータに対して、CRUD操作を実行するApiを提供しています。
    本機能はREST形式にのみ対応しています。

  • メタデータに対するCRUD操作の実行
    メタデータ定義に対するCRUD操作を実行するApiを提供しています。
    本機能はREST形式にのみ対応しています。

  • バイナリデータのアップロード、ダウンロード
    マルチパートを利用し、バイナリデータのアップロード、ダウンロードが可能です。
    本機能はREST形式、 SOAP WSDL形式 に対応しています。

尚、iPLAssではアクセス方法について以下の通り定義し、今後の説明では以下の呼称で記載します。

iPLAssでの名称概要

REST FORM

クライアントから送信されるMIMEメディアタイプがapplication/x-www-form-urlencoded、multipart/form-dataに対応するREST通信を "REST FORM" と呼びます。
パラメータを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)を指定します。
全てチェックされていない場合は全メソッドでのアクセスが可能です。 デフォルトでは全てチェックされていない状態となります。
ひとつでもチェックされている場合は、チェックされているメソッドでのみアクセスが可能となります。

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

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

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の値を指定しない場合、ブラウザにより挙動が異なりますのでご注意ください。

cacheControlType

Max Age

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

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

cacheControlMaxAge

Restriction of Request
項目内容アノテーション

Allow Request Content Types

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

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

allowRequestContentTypes

Max Request Body Size

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

maxRequestBodySize

Max File Size

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

maxFileSize

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

Access-Control-Allow-Origin

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

accessControlAllowOrign

Access-Controll-Allow-Credentials

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

accessControlAllowCredentials

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

support Bearer Token

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

supportBearerToken

Scopes

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

scopeA scopeB
scopeC

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

oauthScopes

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

Request Type

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

accepts

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内の値を取得することが可能です。

restJson
  @RestJson

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

で取得可能です。

restXml
  @RestXml

Response Type

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

responseType

Parameter Mappings
項目内容

Parameter Name

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

Map From

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

Condition

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

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

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

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

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

  • 返却値

    項目内容

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

    • Entity未指定

      パラメータ名内容

      query

      EQLを指定します

    • 共通

      パラメータ名内容

      tabular

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

      countTotal

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

  • 返却値

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

    • 上記以外の場合

      項目内容

      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

メタデータに対する操作(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_3_1.xsd"
  version="3.1">

    :

    <listener>
        <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class>
    </listener>

    <servlet>
        <description>JAX-WS endpoint</description>
        <display-name>JAX-WS Endpoint</display-name>
        <servlet-name>webserviceEndpoint</servlet-name>
        <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>webserviceEndpoint</servlet-name>
        <url-pattern>/soap/*</url-pattern>
    </servlet-mapping>

    :

</web-app>

また、合わせて以下の内容のsun-jaxws.xmlをWEB-INFへ格納します。

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime' version='2.0'>
    <endpoint implementation="org.iplass.mtp.impl.webapi.soap.CommandInvokerWebService" name="CommandInvoker" url-pattern="/soap/command" />
    <endpoint implementation="org.iplass.mtp.impl.webapi.soap.BinaryWebService" name="BinaryService" url-pattern="/soap/bin" enable-mtom="true" />
</endpoints>