Moin Moin zusammen,
ich bin in der Changelog zur Version 6.1 BETA, über diesen Satz gestolpert
Advanced REST server with scripting support (background script functions OnRESTRequest, OnRawRESTRequest). Some slight changes in the JSON output for some endpoints.Da wir gerade sehr viel mit dem REST Interface spielen. (https://www.mairlist.com/forum/index.php/topic,9535.0.html) Habe ich bei Torben nachgefragt, was sich dahinter genau verbirgt und wie man diese Funktion benutzt und habe folgende Info erhalten, die ich in Absprache mit Torben, hier veröffentliche.
[quote=“Torben”]Damit kann man eigene REST-Endpoints in Scripts implementieren
Dazu gibt es zwei Funktionen:
[code]// Called when a request is made to the REST server
procedure OnRESTRequestRaw(Request: TRawRESTRequest; var Response: TRawRESTResponse);
begin
end;
// Called when a JSON request is made to the REST server
procedure OnRESTRequest(Request: TRESTRequest; var Response: IPersistentStorage);
begin
end;
[/code]
Die mit “Raw” ist “low-level”, also sowohl der Request als auch deine Antwort werden als Text übermittelt:
[code] TRawRESTRequest = record
Method: string;
Document: string;
Parameters: IStrings;
end;
TRawRESTResponse = record
ResponseNo: integer;
ContentType: string;
CharSet: string;
Data: string;
Handled: boolean;
end; [/code]
Method ist “GET”, “POST” usw.
Document ist die URL ohne Host, also z.B. /meineendpoints/test1
Parameters sind die GET- oder POST-Parameter als fertige Stringliste
In der Response setzt du die ResponseNo auf 200 und die anderen Felder wie gewünscht. Data ist das, was als Ergebnis rausregereicht wird. Wichtig: Unbedingt Handled := true setzen! So weiß der REST-Server, dass du die Anfrage abgearbeitet hast und keine weiteren Scripts/Endpoints mehr abgefragt werden müssen.
Minimalbeispiel:
procedure OnRESTRequestRaw(Request: TRawRESTRequest; var Response: TRawRESTResponse);
begin
if (Request.Method = 'GET') and (Request.Document = '/test1') then begin
Response.ResponseNo := 200;
Response.ContentType := 'text/plain';
Response.Data := 'hallihallo';
Response.Handled := true;
end;
end;
Um Fehlermeldungen zu generieren kannst du folgende Funktion nutzen:
procedure RESTError(iCode: integer; iErrorMessage, iContent: string);Die zweite Script-Prozedur ohne “Raw” ist eine high-level-Variante, bei der direkt mit JSON-Dokumenten (intern repräsentiert durch die IPersistent*-Objekte) hantiert wird.
TRESTRequest = record
Method: string;
Document: string;
Parameters: IStrings;
UploadDocument: IPersistentStorage;
AuthUserID: integer;
AuthUserName: string;
AuthUserPermissions: string;
end;
In diesem Fall gibst du einfach als Response ein IPersistent*-Objekt zurück, wenn du auf die Anfrage antworten möchtest. Sonst unangetastet lassen.
// Called when a JSON request is made to the REST server
procedure OnRESTRequest(Request: TRESTRequest; var Response: IPersistentStorage);
begin
if (Request.Method = 'GET') and (Request.Document = '/test2') then
Response := Factory.CreatePersistentString('hallihallo')
else if (Request.Method = 'GET') and (Request.Document = '/test3') then
Response := Factory.CreatePersistentObject.SetString('Vorname', 'Klaus').SetString('Nachname', 'Irgendwer');
end;
Umwandlung in korrektes JSON übernimmt dann der REST-Server für dich.
Eingeführt habe ich die Sachen wegen eines Kundenprojektes, bei denen wir Playlist-Inhalte zwischen zwei Instanzen synchroniseren mussten. Es gibt daher auch entsprechend einen neuen REST-Client für die Scripts:
begin
IRESTClient = interface ['{3FFF7E90-3B1F-4F7A-9E0A-58CE24307451}']
function Get(iDocument: string; iParameters: IStrings): IPersistentStorage;
function Delete(iDocument: string; iParameters: IStrings): IPersistentStorage;
function Post(iDocument: string; iParameters: IStrings): IPersistentStorage;
function PostJSON(iDocument: string; iUploadDocument: IPersistentStorage): IPersistentStorage;
function Put(iDocument: string; iParameters: IStrings): IPersistentStorage;
function PutJSON(iDocument: string; iUploadDocument: IPersistentStorage): IPersistentStorage;
end;
Wird erzeugt mit einer der beiden Funktionen:
function CreateRESTClientWithCredentials(iURL, iUser, iPassword: string): IRESTClient;
function CreateRESTClientWithToken(iURL, iToken: string): IRESTClient;
Wenn man die Funktionen mit “JSON” dran benutzt, kann man sehr leicht und ohne viel Konvertierung mit der Gegenstelle (Funktionen ohne “Raw”) sprechen.[/quote]
dafür begeistern kann.