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"
           }
      }
   }

フィードバック