4.3. フロールーティング¶
フロールーティングの構成要素と、動作仕様について説明します。
項目
4.3.1. 概要¶
フロールーティングでは、以下の情報を保持しています。
- ルート
- HTTPメソッド
- フロー定義ID
- フローバージョン
- セキュアフラグ
- 認証方式
- 認可URI
コラム
フロールーティング情報は、紐づくフロー定義とそのバージョンが削除された場合に一緒に削除されます。
それぞれの情報の利用用途について、説明します。
フロールーティングの定義に一致するリクエストを受信した場合、以下の順序で処理を行います。
- ルート・HTTPメソッドに一致するフロールーティング情報の取得
- セキュアトークンによるCSRF攻撃チェック
- 認証方式による認証
- 認可
- ロジックフローへの入力データの構築
- ロジックフローの実行
- ロジックフローの出力データの返却
各処理でエラーが発生した場合、後続の処理は実行しません。
4.3.2. ルート・HTTPメソッドに一致するフロールーティング情報の取得¶
ロジックフローをREST APIとして利用するためのURLは、以下の通りです。
<SCHEME>://<HOST>(:<PORT>)/<CONTEXT_PATH>/logic/api/${route}
フロールーティングで持つルートは、上記の ${route} を指す値です。 また、利用できるHTTPメソッドは、 GET, POST, PUT, DELETE です。
URLが <SCHEME>://<HOST>(:<PORT>)/<CONTEXT_PATH>/logic/api/ から始めるリクエストを受信した場合、フロールーティングのルートとHTTPメソッドを元に一致するフロールーティングが存在しないか否かを検索します。
4.3.3. セキュアトークンによるCSRF攻撃チェック¶
フロールーティングのセキュアフラグが有効になっている場合、セキュアトークンによるトークンチェックを行います。 認証方式として「IMAuthentication」を選択している場合は、CSRF対策として有効とすべきです。
トークンチェックに利用するトークンは以下のいずれかの箇所に含める必要があります。
- リクエストヘッダ X-Intramart-Secure-Token
- リクエストパラメータ im_secure_token
トークンの発行は SecureTokenManager で行います。 トークンの発行とREST APIへのリクエストは同一のセッション内で行う必要があります。
4.3.4. 認証方式による認証¶
フロールーティングの認証方式により、認証処理を行います。 認証方式は以下が存在します。
4.3.4.1. IMAuthentication¶
特別な認証処理を行わず現在のCookieに紐づくセッションの認証状態のままロジックフローを実行します。
4.3.4.2. Basic¶
Basic認証による認証を行いロジックフローを実行します。
コラム
バーチャルテナントによる複数テナントを利用している環境において、リクエスト情報を利用したテナント自動解決機能を利用していない場合のみ、Basic認証のユーザ名にテナントを指定することが可能です。
上記環境におけるBasic認証のユーザ名の指定方法による挙動の違いは以下の通りです。
「ユーザコード」の指定
デフォルトテナントに対して認証を行います。
「テナントID\ユーザコード」の指定
指定したテナントに対して認証を行います。
4.3.4.3. OAuth¶
OAuth認証による認証を行いロジックフローを実行します。
この認証方式を利用したロジックフローを実行する場合はヘッダに アクセストークンを付与してリクエストを送信してください。
GET /<resource_path> HTTP/1.1 Host: localhost Authorization: Bearer <access_token>
アクセストークンの取得方法については以下のドキュメントを参照してください。
4.3.5. セッション管理¶
REST API ではリクエストヘッダ X-Intramart-Session を指定することによりセッション管理を行えます。
X-Intramart-Sessionには、keep, once, never の３つの値が利用できます。
ヘッダを省略した場合は once を指定した場合と同じです。
指定した値による挙動は Web API Maker と同様です。詳しい挙動については以下を参照してください。
4.3.6. 認可¶
IM-Authzによる認可判断を行います。
REST API実行ユーザ（認証方式により認証されているユーザ）が、フロールーティングの認可URIが指す認可リソースを実行可能である場合、ロジックフローを実行します。
認可リソースに対しての認可設定は「ロジックフロールーティング定義一覧」画面から行えます。
IM-Authzによる認可判断の詳細については「 認可仕様書 」を参照してください。
コラム
認可設定の条件として、ユーザや組織を対象としたもの以外にもIPアドレスによる条件が利用可能です。
システム間連携用のREST APIを作成する際などにご利用ください。
注意
認可URIは固有の値である必要があります。
異なるフロールーティングであっても、同一の認可URIを指定することはできません。
4.3.7. ロジックフローへの入力データの構築¶
リクエストからロジックフローへの入力データを構築します。
入力データの元となる情報の格納先は以下の通りです。
4.3.7.1. JSON¶
入力データの情報をJSONで表現します。
リクエストボディにJSONを格納します。この場合、Content-Typeは “application/json” から始まる必要があります。
入力データのJSONでの表現方法については JSON上でのデータの表現 を参照してください。
4.3.7.2. リクエストパラメータ¶
入力データの情報をクエリパラメータ、application/x-www-form-urlencoded 形式、または、multipart/form-data形式で表現します。
入力データのパラメータ名をリクエストパラメータ名、パラメータの値を、リクエストパラメータ値として表現します。
型IDが “string” である “input1” と、型IDが “integer” である “input2” を入力データに持つ場合、リクエストパラメータは以下のように表現します。
input1=string&input2=123
オブジェクト型のプロパティは、 ”.” （ドット）区切りで表現します。
型IDが “object” であるinput1があり、そのプロパティとして 型IDが “string” であるstrと、型IDが “integer” であるintを入力データに持つ場合、リクエストパラメータは以下のように表現します。
input1.str=string1&input1.int=1
配列型の表現は、同名のパラメータ名を複数指定することで行います。
型IDが “object” でかつ、配列であるinput1があり、そのプロパティとして 型IDが “string” であるstrと、型IDが “integer” であるintを入力データに持つ場合、リクエストパラメータは以下のように表現します。
input1.str=string1&input1.int=1&input1.str=string2&input1.int=2
制約として、以下の条件に一致する入力データを持つロジックフローのパラメータは構築できません。
- 型ID “object” が配列型であり、かつ、そのプロパティ（または内包するプロパティ）に配列型が存在する。
また、配列型の型ID “object” のプロパティは、null値を表現することはできません。（指し示す要素が不明となるため）
これにより、空文字のパラメータを指定する必要がありますが型ID により、空文字を指定することでエラーとなる型が存在するため注意してください。
各型IDでのリクエストパラメータの表現は以下の通りです。
型ID 説明 string 文字列をそのまま指定します。 boolean true/falseで表現します。 byte 整数形式で表現します。 character 整数形式で表現します。 short 整数形式で表現します。 integer 整数形式で表現します。 long 整数形式で表現します。 float 数値を指定します。 double 数値を指定します。 bigdecimal 数値を指定します。 biginteger 整数形式で表現します。 locale ロケールIDを指定します。 timezone タイムゾーンIDを指定します。 calendar ISO 8601の拡張形式で指定します。 date ISO 8601の拡張形式で指定します。 imdatetime ISO 8601の拡張形式で指定します。 imduration 対応していません。 sqldate ISO 8601の拡張形式で指定します。 sqltimestamp ISO 8601の拡張形式で指定します。 binary storage map 対応していません。 any 対応していません。
4.3.8. ロジックフローの実行¶
フロールーティングに指定されている、フロー定義IDとフローバージョンから実行するロジックフローを決定し、ロジックフローを実行します。
フローバージョンは、存在するバージョンまたは最新のバージョン（-1）を指定可能です。
4.3.9. ロジックフローの出力データの返却¶
実行したロジックフローの出力データは以下の形式で返却できます。
4.3.9.1. JSONに変換して返却¶
実行したロジックフローの出力データをJSON形式に変換して出力します。
出力データに伴うJSONの形式については JSON上でのデータの表現 を参照してください。
4.3.9.2. テキストとして返却¶
実行したロジックフローの出力データに含まれる body プロパティの値をテキストとして返却します。
出力データは以下の形式になっている必要があります。
output <object> ┗ body <string> or <storage>
4.3.9.3. HTMLとして返却¶
実行したロジックフローの出力データに含まれる body プロパティの値を HTML として返却します。
出力データは以下の形式になっている必要があります。
output <object> ┗ body <string> or <storage>
4.3.9.4. XMLとして返却¶
実行したロジックフローの出力データに含まれる body プロパティの値を XML として返却します。
出力データは以下の形式になっている必要があります。
output <object> ┗ body <string> or <storage>
4.3.9.5. JSONとして返却¶
実行したロジックフローの出力データに含まれる body プロパティの値を JSON として返却します。
出力データは以下の形式になっている必要があります。
output <object> ┗ body <string> or <storage>
4.3.9.6. 任意のContent-Typeで返却¶
実行したロジックフローの出力データに含まれる body プロパティの値を指定された Content-Type で返却します。
Content-Type は出力データの Content-Type プロパティかロジックフロールーティング情報のレスポンスヘッダに指定します。
（どちらにも指定されていない場合は Content-Type は application/octet-stream で返却されます。）
出力データは以下の形式になっている必要があります。
output <object> ┠ body <string> or <storage> ┗ Content-Type <string>
4.3.9.7. ファイルダウンロード¶
実行したロジックフローの出力データに含まれる body プロパティのファイルを添付ファイルとして返却します。
bodyプロパティに指定するファイルのContent-Typeは、出力データの Content-Type プロパティかロジックフロールーティング情報のレスポンスヘッダに指定します。
（どちらにも指定されていない場合は body に指定されたファイルの拡張子から自動判別を行います。）
出力データは以下の形式になっている必要があります。
output <object> ┠ body <storage> ┗ Content-Type <string>
4.3.9.8. ファイルをインラインで返却¶
実行したロジックフローの出力データに含まれる body プロパティのファイルをインライン表示を行うファイルとして返却します。
bodyプロパティに指定するファイルのContent-Typeは、出力データの Content-Type プロパティかロジックフロールーティング情報のレスポンスヘッダに指定します。
（どちらにも指定されていない場合は body に指定されたファイルの拡張子から自動判別を行います。）
出力データは以下の形式になっている必要があります。
output <object> ┠ body <storage> ┗ Content-Type <string>
4.3.9.9. ファイルをバイナリで返却¶
実行したロジックフローの出力データに含まれる body プロパティのファイルの内容をバイナリで返却します。
bodyプロパティに指定するファイルのContent-Typeは、出力データの Content-Type プロパティかロジックフロールーティング情報のレスポンスヘッダに指定します。
（どちらにも指定されていない場合は body に指定されたファイルの拡張子から自動判別を行います。）
出力データは以下の形式になっている必要があります。
output <object> ┠ body <storage> ┗ Content-Type <string>
4.3.10. REST APIのセキュリティ¶
Basic認証を行うことで、特定のユーザにてREST APIの実行を行うことが可能です。
SSL/TSLを利用しない場合、REST APIのリクエスト・レスポンスは平文で行われます。このため、SSL/TSL接続を利用してREST APIを実行することを推奨します。
4.3.11. バーチャルテナントによる複数テナントにおけるREST APIの実行¶
バーチャルテナントによる複数テナント環境に対してREST APIを実行する場合は、サーバがリクエスト情報を利用したテナント自動解決機能 を利用しているか否かで、テナントの確定方法が異なります。
対象を環境にあわせてリクエストを送信してください。
4.3.11.1. リクエスト情報を利用したテナント自動解決機能を利用している場合¶
REST APIを実行するリクエストに、リクエスト情報を利用したテナント自動解決機能が要求するテナント情報を含めてください。
例えば、URLのサブドメインを利用してテナントの自動解決を行っている場合、REST APIを実行するリクエストのURLを対象のテナントを指す値としてください。
4.3.12. エラー発生時のレスポンス¶
REST API実行に伴い何らかのエラーが発生した場合、レスポンスとして200番代以外のHTTPステータスコードがエラーレスポンスとして返ります。
エラーレスポンスは、一部のエラーを除き以下の application/json 形式で返ります。
{
"error" : true,
"errorMessage" : "message"
}
発生するステータスコードは以下の通りです。
コラム
セッション・タイムアウトによるエラーレスポンス等、 application/json 以外の形式でレスポンスが返ることがあります。
コラム
同じステータスコードでもエラーの原因が異なる場合があります。
| ステータスコード | 説明 |
|---|---|
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 500 |
|
4.3.13. Swagger出力¶
ロジックフローのREST APIの仕様をSwagger形式で出力可能です。
Swaggerについての詳細は https://github.com/swagger-api/swagger-spec を参照してください。
出力を行うためのURLは以下の通りです。
<SCHEME>://<HOST>(:<PORT>)/<CONTEXT_PATH>/all-api-docs
すべてのREST APIの仕様を出力します。<SCHEME>://<HOST>(:<PORT>)/<CONTEXT_PATH>/api-docs/${category-id}
ロジックフローに指定されているカテゴリを${category-id}に指定することでそのカテゴリを持つロジックフローのREST APIの仕様を出力します。
コラム
「ルーティング定義一覧」画面から、この機能を利用したREST APIの仕様の閲覧が可能です。
4.3.14. JSON上でのデータの表現¶
型ID Jsonでの表現 説明 string String boolean Boolean byte Number character Number short Number integer Number long Number float Number double Number bigdecimal String 数値表現で指定します。 biginteger String 整数表現で指定します。 locale String ロケールIDを指定します。 timezone String タイムゾーンIDを指定します。 calendar String ISO 8601の拡張形式で指定します。 date String ISO 8601の拡張形式で指定します。 imdatetime String ISO 8601の拡張形式で指定します。 imduration （非対応） JSON形式での表現に対応していません。 sqldate String ISO 8601の拡張形式で指定します。 sqltimestamp String ISO 8601の拡張形式で指定します。 binary （非対応） JSON形式での表現に対応していません。 storage （非対応） JSON形式での表現に対応していません。 map Object object Object any （非対応） JSON形式での表現に対応していません。
コラム
「ロジックフロー定義編集」画面で選択不可能な型も含まれています。