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