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). Standardmäßig wird HTTP verwendet. Sie können HTTPS mit dem Parameter sslEnabled in der INI-Datei der Automation Engine (ucsrv.ini) aktivieren. Wenn Sie TLS/SSL aktivieren, stellen Sie sicher, dass die erforderlichen Zertifikate vorhanden sind. In diesem Fall verwenden Sie dasselbe Zertifikat, das Sie für den Java-Kommunikationsprozess (JCP) verwendet haben. Sie müssen sicherstellen, dass es korrekt konfiguriert ist, sodass die REST API den REST-Prozess erreichen kann.

Mehr Informationen:

Weitere Informationen über die verschiedenen Zertifikattypen und Beispiele, wie sie erstellt und verwendet werden können, finden Sie unter Welche Art von Zertifikaten sollte ich für Automic Automation v21 verwenden?

Wichtig! Beachten Sie, dass dies nur Beispiele sind, keine Anforderung für Automic Automation darstellen und nicht dafür gedacht sind, die Produktdokumentation zu ersetzen.

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:

Alle Zeitstempelwerte werden als in der Datenbank gespeicherte Werte zurückgegeben und nicht von der Automation Engine konvertiert. Der REST-Mandant ist für die Konvertierung verantwortlich.
Die Automation Engine prüft nicht, ob bei der Ausführung eines Objekts ein Zeitzonenobjekt vorhanden ist. Auch die AE-REST-API überprüft dies nicht.
Wenn Sie die AE-Authentifizierung verwenden und ein Benutzerobjekt importieren, ist der Benutzer gesperrt. Er muss im Mandanten 0 entsperrt werden und ein neues Passwort erhalten. Dieses Verhalten gilt nicht bei Verwendung der LDAP-Authentifizierung. Weitere Informationen finden Sie unter Login-Daten über LDAP und/oder LDAP Sync authentifizieren.

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 unter 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 Installation des REST-Prozesses ist relevant für die AE REST-API sowie für die erweiterte Objektsuche. Sie können einen einzelnen REST-Prozess installieren. In diesem Fall werden alle REST-Anfragen an diese einzelne AE REST-API-Instanz gesendet, und es steht keine REST-API zur Verfügung, wenn der REST-Prozess nicht läuft. Weitere Informationen finden Sie unter Installieren des REST-Prozesses.

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

Wichtig! Bei Verwendung mehrerer REST-Prozesse ist es zwingend erforderlich, dass jeder seine eigene Automation Engine-Konfigurationsdatei ucsrv.ini verwendet. Wenn nur eine INI-Datei für mehr als einen REST-Prozessverwendet 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 REST-Prozesses wird eine Fehlermeldung mit Angabe der Ursache für den Abbruch geschrieben.

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

Um diese Konfiguration nutzen zu können, muss auf jedem Knoten ein REST-Prozess installiert sein. Port1 und Port2 können die gleiche Portnummer haben (z. B. 8088, den Standardwert in der Konfigurationsdatei), weil die REST-Knoten 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 REST-Prozesse über die gleiche IP-Adresse erreicht werden, was bedeutet, dass die Endpunkte die gleiche Basis-URI haben: http(s)://{Host}:{Port}/ae/api/v1/{Mandant}/....

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

In einer aktiv/aktiv-Einstellung für hohe Verfügbarkeit sollen beide verfügbar sein.
In einer aktiv/passiv-Einstellung für hohe Verfügbarkeit soll nur einer verfügbar sein.

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 REST-Knoten.

Bei einer aktiv/aktiv-Einstellung für hohe Verfügbarkeit sendet er sie an einen der beiden verfügbaren. Welcher davon verwendet wird, hängt von der Auswahlstrategie des Proxys ab (z. B. niedrigste Last oder Verbindungen).
Bei einer aktiv/passiv-Einstellung für hohe Verfügbarkeit sendet er sie normalerweise an den verfügbaren.

Statusprüfungsanfragen

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

eine schnelle /ping-Anfrage, die von HTTP/HTTPS-Proxys verwendet werden soll, um sicherzustellen, dass der REST-Knoten verfügbar ist. Diese Statusprüfung liefert keine Details zu den benötigten Backend-Komponenten:

../ping
eine Systeminformationszustandsprüfung, die Details zum REST-Knoten liefert. Diese Statusprüfung liefert auch Details zu den benötigten Backend-Komponenten:

../{client}/system/health

Weitere Informationen finden Sie unter AE REST API – Integritätsprüfung

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 die Passwortverschleierung unter Verwendung von UCYBCRYP.EXE, das standardmäßig in Ihrer Installation bereitgestellt wird. Es wird empfohlen, HTTPS zu verwenden, um die Übertragung dieser Informationen zu sichern. Weitere Informationen finden Sie unter Passwörter verschleiern.

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.

Um Variablen, Kommentare und Reports einer Ausführung (GET) abzurufen, benötigen Sie die Berechtigung S - Ausführungen.
Um einer Ausführung (POST) Kommentare hinzuzufügen, benötigen Sie die Berechtigung M - Modifizieren zur Laufzeit.

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

Tracing

Alle REST-Aktivitäten können zu Analysezwecken verfolgt werden. Wählen Sie dazu einen REST-Prozess 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:

0: Tracing deaktiviert
1: Verfolgt REST-Header und -Inhalte
2: Verfolgt auch Login-Informationen

Webserver-Konfiguration

Der Automation Engine-REST-Knoten 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:

Cross-Origin Resource Sharing / Same Origin Policy (CORS/SOP)
- corsSupportEnabled
- corsAccessControlAllowOrigin
GZIP-Komprimierung
- gzipSupportEnable
ThreadPool
- minPoolSize
- maxPoolSize
- idleTimeout

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.

Beispiel

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 Port des AE-REST-Knotens) 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:

corsSupportEnabled=1
corsAccessControlAllowOrigin=http://host1:80

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-Knoten 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 den REST-Knoten 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 REST-Prozess freizugeben.

Siehe auch: