intra-mart Accel Platform IM-LogicDesigner チュートリアルガイド 第7版 2018-04-01

5.4.5.3. 参考:より高度なREST APIの呼び出し

この章では、ユーザ定義(REST)を利用したREST APIの呼び出しについて、より高度な設定値、および、設定方法の説明を行います。

5.4.5.3.1. エンドポイントやヘッダへのEL式を介した動的指定

入力値/出力値」では、ユーザ定義(REST)の入力値と、リクエストパラメータの値とを紐付け、動的な変更が可能な定義方法を説明しました。
IM-LogicDesignerでは、リクエストパラメータにかぎらず、リクエスト情報の全ての項目に関してEL式を利用することで動的な変更を定義可能です。

コラム

EL式について

EL式の詳細については、「IM-LogicDesigner仕様書」 - 「付録」 - 「EL式」を参照してください。

5.4.5.3.1.1. 動的指定の例:その1

リクエストパラメータと同様に、エンドポイントやヘッダに指定する値を入力値から動的に定義することが可能です。
../../../../_images/advanced_el_setting1.png

図:動的変更可能なパラメータ(EL式)の定義その1

  1. 入力値「user_agent」として定義された値が、User-Agentヘッダの値として設定されます。

  2. 動的指定は部分的な適応も可能です。
    入力値「target_id」を元に、URLの特定の部分(PathVariable)を動的に設定しています。

5.4.5.3.1.2. 動的指定の例:その2

EL式を利用し、演算結果を最終的な設定値として定義することが可能です。
../../../../_images/advanced_el_setting2.png

図:動的変更可能なパラメータ(EL式)の定義その2

  1. 入力値「target_user_name」として定義された値の、6文字目以降を最終的な値として設定しています。
  2. 入力値「value_a」、および、「value_b」の比較結果(真偽値)を最終的な値として設定しています。
注意点として、全ての演算結果は文字列(ないしは、文字列として取り扱い可能)である必要があります。

5.4.5.3.2. リクエストおよびレスポンスの種別とその詳細

リクエスト情報、および、レスポンス情報で設定可能な以下の項目について詳細を説明します。
  • リクエスト種別
  • レスポンス種別

5.4.5.3.2.1. リクエスト種別

リクエスト種別で設定可能な値は以下の通りです。
リクエスト種別 詳細
x-www-form-urlencoded
リクエストをx-www-form-urlencoded形式で送信します。
パラメータはkey=value形式で送信されます。
リクエストのパラメータは自動的にURLエンコードされるため、明示的にエンコードを行う必要はありません。
application/json
リクエストをjson形式で送信します。
application/jsonリクエスト種別を利用する場合は、必ず入力値にbodyを定義する必要があります。
IM-LogicDesignerは入力値に定義されたbodyをJSONに変換し、リクエストボディに含めて送信を行います。
form-data
リクエストをmultipart/form-data形式で送信します。
パラメータはkey=value形式で送信されます。
リクエストのパラメータは自動的にURLエンコードされるため、明示的にエンコードを行う必要はありません。

なお、form-dataリクエスト種別を利用する場合、パラメータにバイナリ形式の値を指定可能です。
主にファイルのアップロード等の処理が含まれるREST APIに対して有用です。
raw
上記以外の形式で送信したい場合に選択してください。
rawリクエスト種別を利用する場合は、必ず入力値にbodyを定義する必要があります。
IM-LogicDesignerは入力値に定義されたbodyをそのままリクエストボディに含めて送信を行います。
また、raw リクエスト種別を利用する場合は、「リクエストヘッダ」に明示的なContent-Typeの指定を行ってください。

5.4.5.3.2.2. レスポンス種別

レスポンス種別で設定可能な値は以下の通りです。
レスポンス種別 詳細
json
REST APIのレスポンスをJSONとして受け取ります。
IM-LogicDesignerは、レスポンスのbody部をobjectとして取り出し、JSONとして解釈します。
取り出し結果は文字コードが加味されます。
text
REST APIのレスポンスをTextとして受け取ります。
IM-LogicDesignerは、レスポンスのbody部をstringとして取り出し、HTMLとして解釈します。
取り出し結果は文字コードが加味されます。
raw
REST APIのレスポンスをRaw-Dataとして受け取ります。
IM-LogicDesignerは、レスポンスのbody部をバイナリとして取り出します。
主にダウンロード等の処理が含まれるREST APIに対して有用です。

5.4.5.3.3. ステータスコードのチェック

レスポンス情報の「ステータスコードの確認」を利用することで、「2xx Success」に準ずるステータスコード以外のレスポンスが返却された場合の動作を制御することが出来ます。
具体的には、「ステータスコードの確認」を設定(チェックを付ける)した場合、200番代以外のステータスコードが返って来た場合、タスクの実行エラーとして例外をスローします。
設定をしなかった場合、200番代以外のステータスコードが返ってきた場合(例として400番台(処理の失敗)、500番台(サーバエラー))でも正常に処理が行われたと判断し、次のタスクへ処理をすすめます。

5.4.5.3.4. JSONによる複雑なレスポンスを受け取る

ユーザ定義(REST)においてレスポンスをJSONで受け取る際に、取得するJSONの構造が複雑な場合があります(特に外部サービスなどを利用する場合)。
複雑な構造のJSONを正しく受け取るためには、返却値のbody<object>配下に取得対象のJSONの構造を正確に定義する必要があります。
しかしながら取得するJSONの複雑さが増すほど、定義ミスによって正しくレスポンスが受け取れない事態が起こりやすくなります。
そして何より、そうした複雑なJSONの構造を一つ一つ定義していく作業はとても煩雑です。
そこでIM-LogicDesignerでは、レスポンスの定義にJSONを直接利用する手段を提供しています。
ここでは以下の様なJSONをレスポンスを返すサービスを想定します。
{
    "resultCd" : "56afc9a9-2988-4d13-ace5-1af3e21782f8",
    "basic" : {
        "id" : "BS-000001",
        "name" : "Basic Result Pattern",
        "error" : false,
        "sortKey" : 101,
        "parameter" : ["BS-1", "BS-2", "BS-3"]
    },
    "advanced" : {
        "id" : "ADV-10000101",
        "name" : "Advanced Result Pattern",
        "error" : false,
        "sortKey" : 1001,
        "dependency" : [
            {
                "dependId" : "DP-100",
                "dependName" : "DP-ADV-300",
                "dependVersion" : "1.0.0",
                "enable" : true
            },
            {
                "dependId" : "DP-200",
                "dependName" : "DP-ADV-500",
                "dependVersion" : "2.1.0",
                "enable" : false
            }
        ]
    }
}
  1. 「REST定義編集」画面を表示します。

  2. レスポンス情報の項目を以下のとおりに設定します。

    • レスポンス種別 - json
    ../../../../_images/direct_json_input1.png

    図:JSONレスポンスの設定

  3. 返却値が自動で更新され、bodyパラメータの型がobjectになっていることを確認し、body<object>パラメータをクリックして選択状態にします。

    ../../../../_images/direct_json_input2.png

    図:自動設定の確認、および、選択

  4. 返却値の上部にある「JSON入力」をクリックします。

  5. 「サンプルJSONの入力」画面が表示されます。

    ../../../../_images/direct_json_input3.png

    図:「サンプルJSONの入力」画面

  6. 画面項目を以下のとおりに設定します。

    • 追加方法 - 選択項目の配下に追加する
    • null値の型 - object
    • JSON - 上記で定義した想定するJSONレスポンス
    ../../../../_images/direct_json_input4.png

    図:「サンプルJSONの入力」の設定

  7. 画面下部の決定をクリックします。

  8. 返却値のbody<object>配下に、レスポンスのJSON構造が自動生成されたことを確認してください。

    ../../../../_images/direct_json_input5.png

    図:JSON構造の自動生成