5.4.5.3. 参考:より高度なREST APIの呼び出し¶
この章では、ユーザ定義(REST)を利用したREST APIの呼び出しについて、より高度な設定値、および、設定方法の説明を行います。
5.4.5.3.1. エンドポイントやヘッダへのEL式を介した動的指定¶
「入力値/出力値」では、ユーザ定義(REST)の入力値と、リクエストパラメータの値とを紐付け、動的な変更が可能な定義方法を説明しました。
IM-LogicDesignerでは、リクエストパラメータにかぎらず、リクエスト情報の全ての項目に関してEL式を利用することで動的な変更を定義可能です。
5.4.5.3.1.1. 動的指定の例:その1¶
リクエストパラメータと同様に、エンドポイントやヘッダに指定する値を入力値から動的に定義することが可能です。
入力値「user_agent」として定義された値が、User-Agentヘッダの値として設定されます。
- 動的指定は部分的な適応も可能です。入力値「target_id」を元に、URLの特定の部分(PathVariable)を動的に設定しています。
5.4.5.3.1.2. 動的指定の例:その2¶
EL式を利用し、演算結果を最終的な設定値として定義することが可能です。
- 入力値「target_user_name」として定義された値の、6文字目以降を最終的な値として設定しています。
- 入力値「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をそのままリクエストボディに含めて送信を行います。
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
}
]
}
}
「REST定義編集」画面を表示します。
レスポンス情報の項目を以下のとおりに設定します。
返却値が自動で更新され、bodyパラメータの型がobjectになっていることを確認し、body<object>パラメータをクリックして選択状態にします。
返却値の上部にある「JSON入力」をクリックします。
「サンプルJSONの入力」画面が表示されます。
画面項目を以下のとおりに設定します。
画面下部の決定をクリックします。
返却値のbody<object>配下に、レスポンスのJSON構造が自動生成されたことを確認してください。