EGL REST-RPC 메시지 구조

이 주제에서는 EGL 구조를 사용하여 EGL이 아닌 프로그래밍 언어에서 EGL REST-RPC 서비스에 액세스하는 방법을 보여줍니다.

EGL REST-RPC 서비스는 HTTP 1.1 및 JSON 인코딩된 데이터를 사용합니다.

요청 메시지

HTTPRequest 메시지에는 다음 특성이 있습니다.
  • 헤더가 application/json 값이 있는 key:Content-Type을 포함합니다. 메소드는 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 형식의 다음 두 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 오브젝트를 수신합니다.
  • 하나의 응답 매개변수만 사용 중인 경우 요청자는 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 레코드의 필드는 다음과 같습니다.
이름
값 "JSONRPCError"입니다.
code
예외 메시지 ID입니다.
message
예외 메시지입니다.
error
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()
      ;
   endend
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"
           }
      }
   }