EGL REST-RPC メッセージ構造
このトピックでは、EGL 構造を使用して、EGL 以外のプログラミング言語から EGL REST-RPC サービスにアクセスする方法を指定します。
EGL REST-RPC サービスでは、HTTP 1.1 と JSON エンコードのデータを使用します。
要求メッセージ
HTTPRequest メッセージには、次の特性があります。
- ヘッダーには key:Content-Type が組み込まれます。その値は application/json です。メソッドは POST です。
- 基本的に、メッセージの本体には、JSON フォーマットの以下の EGL レコード定義が組み込まれます。
Record EGL_REST_RPC_Request //name of the function to be invoked method string; //IN and INOUT parameters in the service parameter-list order params any[]; end
成功後の応答メッセージ
EGL サービス機能が成功して戻った場合の HTTPResponse メッセージには、以下の特性があります。
- ヘッダーの状況コードは 200 に設定されます。
- 基本的に、メッセージの本体には、JSON フォーマットの以下の 2 つの EGL レコード定義のいずれかが組み込まれます。
// For a response with one value Record EGLRESTRPCSingleReturnParamResponse result any?; error EGLRESTRPCResponseError?; end // For a response with multiple values, as described later Record EGLRESTRPCMultipleReturnParamResponse result any[]; error EGLRESTRPCResponseError?; end
応答パラメーターには、OUT または INOUT で変更されるサービス・パラメーターと、サービス機能から返される値が組み込まれます。
その変形版の動作を以下にまとめます。
- OUT、INOUT、戻りのどの場合でも、応答パラメーターがなければ、リクエスターは空の JSON オブジェクトを受け取ります。
- 1 つの応答パラメーターだけを使用する場合、リクエスターは、EGLRESTRPCSingleReturnParamResponse タイプの JSON オブジェクトを受け取ります。
- 複数の応答パラメーターを使用する場合、リクエスターは、EGLRESTRPCMultipleReturnParamResponse タイプの JSON オブジェクトを受け取ります。前述の result 配列には、パラメーター・リストの順序で応答パラメーターが組み込まれ、さらにサービス機能から返された値が組み込まれます。
失敗後の応答メッセージ
EGL サービス機能がエラーで戻った場合の HTTPResponse メッセージには、以下の特性があります。
- ヘッダーの状況コードは 500 に設定されます。
- 基本的に、メッセージの本体には、JSON フォーマットの以下の構造が組み込まれます。
Record EGLRESTRPCResponseError error JSONRPCError; end Record JSONRPCError name string; code string; message string; error EglRpcException end; Record EglRpcException name string; messageID string; message string; // the next fields are present // if the type is egl.core.ServiceInvocationException source? int; detail1? string; detail2? string; detail3? string; end
JSONRPCError レコードの各フィールドを以下にまとめます。
- name
- 「JSONRPCError」という値。
- code
- 例外メッセージ ID。
- message
- 例外メッセージ。
- エラー
- EglRpcException レコードで記述されている一連のフィールド。最初のフィールドは name フィールドです。このフィールドには、例外レコードの完全修飾名が組み込まれます (ほとんどの場合は、「egl.core.ServiceInvocationException」です)。 その他のフィールドは、その EGL 例外に由来します (『EGL 例外レコード』を参照してください)。
例
以下のような構造になっている EGL REST-RPC サービスがあるとします。
Service HelloWorld
function emptyParams()
;
end
function singleReturnParam( p1 string in)returns(string)
;
end
function multipleReturnParams( p1 string? )returns(Wrapper?)
;
end
function throwsException()
;
end
end
Record Wrapper
text string;
length int;
end
要求の成功時に渡されるコンテンツの例を以下に示します。
No parameters:
Request body:{"method" : "emptyParams", "params" : []}
Response body:{}
One return parameter:
Request body:{"method" : "singleReturnParam", "params" : ["Joe"]}
Response body:{"result" : "Hello Joe"}
Multiple return parameters:
Request body:{"method" : "multipleReturnParams", "params" : ["Joe"]}
Response body:{"result" : ["Hello Joe", {"text" : "Hello Joe", "length" : 9}]}
サービスから例外がスローされた場合に渡されるコンテンツの例を以下に示します (ただし、エラー・メッセージについては、内容を省略しています)。
Request body:{"method" : "throwsException", "params" : []}
Response body:
{"error" :
{ "name" : "JSONRPCError", "code" : "EGL1539E",
"message" : "EGL1539E An exception occurred...",
"error" :
{"messageID" : "EGL1539E", "message" : "EGL1539E An exception occurred...",
"source" : 4, "detail1" : "500", "detail2" : "FAILED",
"detail3" : "java.net.ConnectException:Connection refused",
"name" : "egl.core.ServiceInvocationException"
}
}
}