EGL-REST-RPC-Nachrichtenstruktur

In diesem Thema wird mithilfe von EGL-Konstrukten erläutert, wie der Zugriff auf einen EGL-REST-RPC-Service über eine andere Programmiersprache als EGL erfolgt.

EGL-REST-RPC-Services verwenden HTTP 1.1- und JSON-codierte Daten.

Anforderungsnachricht

Die HTTP-Anforderungsnachricht weist die folgenden Merkmale auf:
  • Der Header enthält das Element key:Content-Type mit dem folgenden Wert: application/json. Die Methode ist POST.
  • Der Hauptteil der Nachricht enthält im Wesentlichen die folgende EGL-Datensatzdefinition im JSON-Format:
    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

Antwortnachricht nach Erfolg

Wird die EGL-Servicefunktion erfolgreich zurückgegeben, weist die HTTP-Antwortnachricht die folgenden Merkmale auf:
  • Der Statuscode im Header ist auf 200 gesetzt.
  • Der Hauptteil der Nachricht enthält im Wesentlichen eine der folgenden beiden EGL-Datensatzdefinitionen im JSON-Format:
    // 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
Zu den Antwortparametern gehören mit dem Änderungswert OUT oder INOUT definierte Serviceparameter sowie ein von der Servicefunktion zurückgegebener Wert. Die folgenden Varianten sind möglich:
  • Sind keine Antwortparameter vorhanden (egal ob OUT, INOUT oder Rückgabewert), empfängt der Anforderer ein leeres JSON-Objekt.
  • Bei Verwendung nur eines Antwortparameters empfängt der Anforderer ein JSON-Objekt vom Typ 'EGLRESTRPCSingleReturnParamResponse'.
  • Bei Verwendung mehrerer Antwortparameter empfängt der Anforderer ein JSON-Objekt vom Typ 'EGLRESTRPCMultipleReturnParamResponse'. In der oben aufgeführten Feldgruppe result sind die Antwortparameter in der Reihenfolge der Parameterliste und dann der von der Servicefunktion zurückgegebene Wert aufgeführt.

Antwortnachricht nach Fehlschlag

Wird die EGL-Servicefunktion mit einem Fehler zurückgegeben, weist die HTTP-Antwortnachricht die folgenden Merkmale auf:
  • Der Statuscode im Header ist auf 500 gesetzt.
  • Der Hauptteil der Nachricht enthält im Wesentlichen die folgende Struktur im JSON-Format:
    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
Die Felder im Datensatz 'JSONRPCError' lauten wie folgt:
name
Der Wert 'JSONRPCError'.
Code
Die ID der Ausnahmebedingungsnachricht.
message
Die Ausnahmebedingungsnachricht.
error
Eine im Datensatz 'EglRpcException' dargestellte Reihe von Feldern. Das erste Feld ist das Feld name, das den vollständig qualifizierten Namen eines Ausnahmedatensatzes enthält (in den meisten Fällen 'egl.core.ServiceInvocationException'). Die anderen Felder stammen aus der EGL-Ausnahmebedingung (siehe 'EGL-Ausnahmedatensätze').

Beispiele

Betrachten wir einen EGL-REST-RPC-Service, der wie folgt strukturiert ist:
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

Beispiele für Inhalte, die im Falle einer erfolgreichen Anforderung übergeben werden:

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

Das folgende Beispiel zeigt eine abgekürzte Fehlernachricht sowie die Inhalte, die übergeben werden, wenn ein Service eine Ausnahmebedingung auslöst:

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

Feedback