AE-REST-API - Allgemeine Informationen

Als Entwickler oder Systemadministrator können Sie über die REST-API mit dem Automation Engine-System über eine hochmoderne, technologieunabhängige Schnittstelle kommunizieren.

Diese Seite beinhaltet Folgendes:

Übersicht

Die AE-REST-API bietet eine Schnittstelle für Anwendungen von Drittanbietern, um mit der Automation Engine zu interagieren. Die AE-REST-API ermöglicht es dem Benutzer, Automation Engine nicht nur mit Java, sondern auch mit anderen Programmiersprachen anzusprechen.

Die REST-Anfragen und -Antworten enthalten JSON-strukturierte Daten:

Optionale Eigenschaften mit dem Wert Null werden in der Antwort-Payload unter Umständen weggelassen.

Die AE-REST-API unterstützt sowohl HTTP als auch HTTPS (empfohlen). HTTPS kann mit dem Parameter sslEnabled in der Konfigurationsdatei ucsrv.ini der Automation Engine eingestellt werden. Weitere Informationen finden Sie in der Beschreibung der HTTPS/SSL-Einrichtung für das AE REST-API in Installation des JCP.

Die aktuelle Version der AE-REST-API ist v1. Diese Informationen spiegeln sich in der URI wider und sind daher für den Zugriff auf Ihre AE-REST-API-Schnittstelle relevant.

Die AE-REST-API kann mehrfach installiert werden. Die Installation kann entweder mit unterschiedlichen Portnummern auf einem Knoten oder auf verschiedenen Knoten mit derselben Portnummer erfolgen.

Hinweise:

AE-REST-API und ILM

Beim täglichen Betrieb eines Automation Engine-Systems sammeln sich große Mengen an Report-, statistischen und Verlaufsdaten an. Eine Partitionierung der Datenbank mit ILM ist eine effiziente Methode, um mit diesen Mengen umzugehen und die Objektversion ebenso zu erhalten wie die gelöschten Objektdaten. ILM-Aktionen erfordern das Ausschalten von Teilen der Automation Engine-Datenbanktabellen; daher sollten während der Arbeit mit ILM keine Datenbankaktionen stattfinden. Weitere Informationen finden Sie hier: ILM - Information Lifecycle Management.

Wichtig! Der AEREST-Webservice erkennt automatisch, ob es laufende ILM-Aktionen gibt und blockiert in diesem Fall bestimmte REST-Anfragen. In diesem Fall wird eine Fehlermeldung zurückgegeben, die anzeigt, dass die REST-API aufgrund von ILM-Aktionen vorübergehend nicht verfügbar ist.

Lokalisierung

REST-API-Meldungen sind standardmäßig auf Englisch. Die AE-REST-API unterstützt keine andere Sprache.

Mehrere REST-API-Prozesse einrichten

Die JCP-Installation ist sowohl für die AE-REST-API als auch für die erweiterte Objektsuche relevant. Sie können einen einzelnen JCP installieren. In diesem Fall werden alle REST-Anfragen an diese einzelne AE-REST-API-Instanz gesendet, und es ist keine REST-API verfügbar, wenn das JCP ausgefallen ist. Weitere Informationen finden Sie unter Installation des JCP

Sie können auch ein System mit mehreren JCPs einrichten. In diesem Fall werden zwei JCPs in einem Cluster verwendet, aber nur einer von beiden ist dann verfügbar.

Wichtig! Bei der Verwendung mehrerer JCPs ist es zwingend erforderlich, dass jeder JCP seine eigene Automation Engine-Konfigurationsdatei ucsrv.ini verwendet. Wenn nur eine INI-Datei für mehr als einen JCP verwendet wird, verbindet sich der erste erfolgreich, während die anderen beim Versuch, den gleichen REST-Port zu registrieren, abgebrochen werden, wenn beide auf demselben Knoten laufen. In die Logdatei des JCP wird eine Fehlermeldung unter Angabe des Grunds für den Abbruch geschrieben.

Die Einrichtung eines Systems mit mehreren JCPs kann für den Abgleich und die Bereitstellung von Ausfallsicherungen sinnvoll sein, da die REST-Anfragen gesendet und nur an verfügbare JCPs verteilt werden.

Diagramm der Proxy-Konfiguration von geclusterten JCPs.

Um diese Konfiguration nutzen zu können, muss auf jedem Knoten ein JCP installiert sein. Port1 und Port2 können die gleiche Portnummer haben (z. B. 8088, den Standardwert in der Konfigurationsdatei), da JCPs/REST-Webdienste auf verschiedenen Hosts (Host1 und Host2) laufen. Host3:port3 muss als einziger Kontaktpunkt für alle AE-REST-API-Anfragen öffentlich zugänglich sein. Host1:port1 und Host2:Port2 dürfen nur dem HTTP/HTTPS-Proxy bekannt sein.

Wenn eine virtuelle IP verwendet wird, können beide JCPs über die gleiche IP-Adresse erreicht werden, was bedeutet, dass die Endpunkte die gleiche Basis-URI haben: http(s)://{host}:{port}/ae/api/v1/{client}/....

Der REST-Client oder ein HTTP/HTTPS-Proxy senden periodisch eine /ping-Anfrage, um die Verfügbarkeit der JCPs zu überprüfen. Abhängig vom Ergebnis weiß der HTTP/HTTPS-Proxy, welche JCPs derzeit verfügbar sind.

Der REST-Mandant oder HTTP/HTTPS entscheiden dann, wohin die REST-Anfragen gesendet werden, abhängig von der Auswahlstrategie des Proxys. Wenn der REST-Mandant Anfragen an den HTTP/HTTPS-Proxy (Host3:Port3) sendet, sendet der Proxy diese automatisch an einen JCP/REST-Webdienst.

Statusprüfungsanfragen

Die AE-REST-API bietet zwei verschiedene Statusprüfungen:

Authentifizierung

Die AE-REST-API unterstützt die Standardauthentifizierung. Die Mandanten-, Benutzer-, Abteilungs- und Passwortinformationen sind Teil des HTTP(S)-Headers und der URI und werden daher für die Standardauthentifizierung verwendet. Die Automation Engine entscheidet, ob eine REST-Anfrage im Benutzerkontext erlaubt ist oder nicht und antwortet entsprechend.

Die Anfrage wird verarbeitet, wenn die in den Authentifizierungsinformationen eingegebene Mandantennummer mit derjenigen in der URI übereinstimmt. Wenn die Mandantennummern unterschiedlich sind, wird ein Fehler zurückgegeben.

Die AE-REST-API unterstützt keine Passwortverschlüsselung für das Passwort, das in der REST-Anfrage angegeben ist. Es wird empfohlen, HTTPS zu verwenden, um die Übertragung dieser Informationen zu sichern. Weitere Informationen finden Sie unter Passwörter verschlüsseln.

Berechtigungen

Ein effizientes und sicheres System zum Schutz des Datenzugriffs ist ein wesentlicher Bestandteil unseres Sicherheitskonzepts. Die Sicherheit auf Datenebene kann so umfassend sein wie der Administratorzugriff auf eine Rolle oder so hochdetailliert wie "Lesezugriff auf nur einen Job in einem bestimmten Ordner". Weitere Informationen finden Sie unter Zugriff

Die AE-REST-API erfordert auch bestimmte Berechtigungen, um verschiedene Operationen durchzuführen, und prüft, ob sie bei der Ausführung vorhanden sind.

Weitere Informationen finden Sie unter Automation Engine-Berechtigungen gewähren.

Zur Laufzeit generieren

Um Timeouts bei Anfragen zu vermeiden, müssen die auszuführenden Objekte das Attribut Aufgabe generieren zur: Laufzeit haben. Beim Ausführen eines Objekts prüft das System, ob dieses Attribut entsprechend gesetzt wurde. Wenn es nicht gesetzt ist, wird die Ausführung nicht gestartet. Weitere Informationen finden Sie auf der Seite Seite "Attribute".

Durch das Setzen dieses Attributs wird die RunID sofort zurückgegeben, sodass die REST-Antwort sofort der Anfrage folgt.

Wenn diese Eigenschaft auf Generiere Aufgabe zur Aktivierungszeit gesetzt ist, kann eine lange Verarbeitung die sofortige REST-Antwort verhindern, was zu einem Timeout führen kann.

Hinweis: Beim Neustart einer Ausführung ist das Attribut Aufgabe generieren zur Laufzeit nicht gesetzt.

AE REST-API-Polling

Sie können den Server abfragen, um den Status einer REST-Anfrage/Antwort-Sequenz zu überprüfen, falls das gewünschte Ergebnis noch nicht verfügbar ist. Beispielsweise können Sie den Server abfragen, nachdem Sie ein Objekt ausgeführt und die RunID erhalten haben, um zu überprüfen, ob die Ausführung beendet ist.

Das folgende Beispiel zeigt, wie die Abfrage des Ausführungsstatus über die AE-REST-API erfolgen kann:

Eingabe über PromptSet

PromptSet-Variablen können bei der Ausführung durch die AE-REST-API-Anforderung übergeben werden, da den auszuführenden Objekten mindestens ein PromptSet zugeordnet ist.

Beispiel für den Inhalt einer REST-Anfrage:

Hinweise:

Filter für Ausführungsliste

Die Anfrage GET ../v1/{client}/executions liefert eine Liste aller Ausführungen. Sie können Abfrageparameter als Teil der URI hinzufügen, um sie zu filtern.

Hinweis: Die Automic Web Interface hat verschiedene Einstellungen für Listenansichten, die für die Anwendung von Filtern relevant sind. Die hierarchische Ansicht, die bei Verwendung von Filtern nur Parent-Aufgaben betrifft, und die Listenansicht, die sowohl Parent- als auch Child-Aufgaben betrifft. Die AE-REST-API unterstützt nur die Listenansicht.

Sie können Filter für die folgenden Ausführungsparameter anwenden:

Wichtig! Parameter, die es Ihnen ermöglichen, bestimmte Eigenschaften auszuschließen, sind nur in Kombination mit ihren Gegenstücken wirksam.

Beispiel

name und name_exclude

Sie können die Abfrageparameter beliebig kombinieren, um einfache oder komplexe Filter zu erstellen. Zum Beispiel können Sie:

Paginierung für Child-Aufgabenausführungen und Ausführungslisten

Eine Paginierung kann nützlich sein, wenn eine Anfrage an die AE-REST-API zahlreiche Ergebnisse liefert, da die Ergebnismenge, die sich schnell und oft ändern kann, pro Anfrage/Antwort in Blöcke (Seiten) unterteilt wird. Wenn Sie beispielsweise eine Anfrage senden, um alle Child-Aufgabenausführungen einer bestimmten Ausführung zu erhalten, werden möglicherweise Tausende von Datensätzen abgerufen. In der AE-REST-API können Sie die Nummerierung verwenden, um die Ergebnisse einfach zu handhaben.

Grenzparameter

Die AE REST-API ermöglicht es Ihnen, die folgenden Grenzparameter einzustellen:

URI-Struktur mit Paginierungsparametern

Die URI einschließlich der Paginierungsparameter besteht aus den folgenden Elementen:

http://{host}:{port}/ae/api/v1/{client}/executions/{runid}/children?max_results={number}&start_at_run_id={runid}

Beispiel

http://192.168.40.116:8088/ae/api/v1/100/executions/1003003/children?max_results=10&start_at_run_id=100301

In diesem Beispiel hat die angeforderte Parent-Ausführung 1003003 25 angeforderte Child-Aufgaben-Ausführungen. Die paginierte Antwort ist wie folgt verteilt:

Hinweise:

Paginierung für Reports

Die Paginierung ist auch nützlich, wenn ein Report relativ groß ist und sein Inhalt in Reportseiten aufgeteilt ist. Die AE-REST-API blendet diese Reportseiten ein.

Grenzparameter

Wichtig! Die AE-REST-API kann nur den Inhalt von Reports anfordern, die in der AE-Datenbank verfügbar sind. Ein Job-Report wird nur dann in der Datenbank gespeichert, wenn die Option "Speichere in: Datenbank" im Bereich "Job-Report" der Seite "Jobdefinition" ausgewählt wurde. Diese Option ist standardmäßig aktiviert.

Tracing

Alle REST-Aktivitäten können zu Analysezwecken verfolgt werden. Wählen Sie dazu einen JCP aus und klicken Sie mit der rechten Maustaste darauf, um Erweiterte Optionen auszuwählen. Daraufhin erscheint ein Dialog, in dem Sie Trace-Flags spezifizieren können.

Das Trace Flag kann auch in der Automation Engine-Konfigurationsdatei (INI) gesetzt werden. Setzen Sie dazu den JCL-Schlüssel im Abschnitt TRACE der INI-Datei. Die relevanten Werte für RA Web Service REST Agent sind:

Webserver-Konfiguration

Der Automation Engine-REST-Webdienst verwendet einen Webserver, der weitgehend eine vordefinierte Konfiguration verwendet. Als Systemadministrator können Sie die Parameter anpassen, die hier im Abschnitt [REST] der Konfigurationsdatei ucsrv.ini der Automation Engine aufgeführt sind:

CORS/SOP

Die Same Origin Policy (SOP) verhindert, dass Webclients Cross-Origin-Anfragen ausführen. Sie können diese Richtlinie mit Cross-Origin Resource Sharing (CORS) umgehen, um Ursprünge (Origins) explizit zu erlauben.

Zum Beispiel:

Diagramm der Webserver-Konfiguration.

Host 3 fordert ein Webdokument von Origin 1 (Host 1, Webserver) unter http://host1:80 (standardmäßiger http-Port) an. Host 3 fordert dann Informationen von Origin 2 (Host 2, AE) unter http://host2:8080 (standardmäßiger AE-REST-Webdienst-Port) an. Die gängigsten Webbrowser prüfen, ob domänenübergreifende Anfragen erlaubt sind oder nicht. Andernfalls ist die Anfrage an den zweiten Origin http://host2:8080 nicht zulässig.

Um solche Cross-Origin-Anfragen zuzulassen, muss der AE-REST-Webdienst dem Webbrowser explizit mitteilen, dass er die Anfrage zulassen soll. Sie können dies mit den folgenden CORS-Parametern im Abschnitt [REST] der Konfigurationsdatei (ucsrv.ini) der Automation Engine definieren:

Wenn der Webserver auf demselben lokalen Host läuft wie der Browser oder Webclient (Host1 = Host3), müssen Sie einen einfachen webbasierten REST-Client implementieren, indem Sie den Parameter corsAccessControlAllowOrigin auf http://localhost:80 setzen.

Komprimierung

Ein REST-Client kann in einer Anfrage angeben, dass die Antwort-Payload komprimiert werden soll, um die Performance zu verbessern. Wenn der REST-Webdienst die Kompression unterstützt, sendet er die Payload im gzip-Format zurück.

Die Kompressionsunterstützung ist standardmäßig deaktiviert. Sie können sie mit dem Parameter gzipSupportEnabled im [REST]-Abschnitt der Konfigurationsdatei ucsrv.ini der Automation Engine aktivieren.

Thread-Pooling

Der Webserver, der vom JCP/REST-Webdienst verwendet wird, verarbeitet Anfragen mit Hilfe von Threads. Je mehr Threads verwendet werden, desto mehr REST-Anfragen können parallel verarbeitet werden.

Ein Thread-Pool hält mehrere Threads bereit, um REST-Anfragen zu verarbeiten. Je mehr Anfragen eingehen, desto mehr Threads stellt der Webserver automatisch innerhalb des Bereichs zur Verfügung, der in minPoolSize >= N <= maxPoolSize definiert ist. Wenn einige der N Threads für einen längeren Zeitraum als den im Parameter idleTimeout definierten Timeout-Zeitraum ungenutzt bleiben, werden sie beendet, um Ressourcen auf dem JCP-Prozess freizugeben.

Siehe auch: