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¶
GET /<resource_path> HTTP/1.1 Host: localhost Authorization: Bearer <access_token>
4.3.5. セッション管理¶
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 形式で表現します。 入力データのパラメータ名をリクエストパラメータ名、パラメータの値を、リクエストパラメータ値として表現します。
型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. テキストとして返却¶
output <object> ┗ body <string> or <storage>
4.3.9.3. HTMLとして返却¶
output <object> ┗ body <string> or <storage>
4.3.9.4. XMLとして返却¶
output <object> ┗ body <string> or <storage>
4.3.9.5. JSONとして返却¶
output <object> ┗ body <string> or <storage>
4.3.9.6. 任意のContent-Typeで返却¶
output <object> ┠ body <string> or <storage> ┗ Content-Type <string>
4.3.9.7. ファイルダウンロード¶
output <object> ┠ body <storage> ┗ Content-Type <string>
4.3.9.8. ファイルをインラインで返却¶
output <object> ┠ body <storage> ┗ Content-Type <string>
4.3.9.9. ファイルをバイナリで返却¶
output <object> ┠ body <storage> ┗ Content-Type <string>
4.3.10. 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形式での表現に対応していません。
コラム
「ロジックフロー定義編集」画面で選択不可能な型も含まれています。