Erstellen von API-Anfragen

Alle Orchestrator API-Aufrufe erfolgen mithilfe von HTTP-Methoden an die Orchestrator-URL. Die Orchestrator-URL hat die folgende Syntax: https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_ . Es wird empfohlen, die Daten, die Sie über API-Aufrufe senden, mit dem HTTPS-Protokoll zu verschlüsseln.

Wichtig:

Für den Zugriff auf Ressourcen in einem Ordner muss jede Anforderung entweder FolderId, FolderPathoder FolderKey in einem HTTP-Header enthalten. Dieser Header kann codiert (mit Base64 UTF-16LE-Codierung) oder als Nur-Text sein.

Zum Beispiel:

• X-UIPATH-OrganizationUnitId "FolderId",
• X-UIPATH-FolderPath-Encoded "{Encoded FolderPath value}",
• X-UIPATH-FolderPath "PlainText FolderPath value", oder
• X-UIPATH-FolderKey "FolderKey".

Die FolderId kann abgerufen werden, indem eine GET-Anforderung an den /odata/Folders-Endpunkt ausgeführt und der Wert „Id“ kopiert wird, oder über die Orchestrator-URL – https://your-domain-server.com/? fid=2032 &tid=8. FolderId ist vom Typ Int 64.

Die FolderKey kann durch Ausführen einer GET-Anforderung an den Endpunkt /odata/Folders und Kopieren des Werts „Key“ abgerufen werden. FolderKey ist vom Typ Eindeutige ID/Zeichenfolge.

Wenn Sie den Lizenzierungsplan für Ihr Orchestrator-Konto ändern (z. B. von Enterprise Trial zu Enterprise), ändert sich auch der Wert FolderId , während der Wert von FolderKey gleich bleibt.

Wenn Sie ein Upgrade durchgeführt haben und Organisationseinheiten in Ihrer vorherigen Orchestrator-Instanz aktiviert waren, wird jede OU als neuer klassischer Ordner migriert.

Relative Ordnerpfade werden in einem X-UIPATH-FolderPath-Encoded-Header wie folgt unterstützt:

• Pfad, der mit / beginnt – Beginnt im root-Ordner der Struktur, zu welcher der Umgebungsordner gehört.
• Pfad, der mit . beginnt – Beginnt im Umgebungsordner.
• Pfad, der mit .. beginnt – Beginnt eine Ebene höher in der Hierarchie des Umgebungsordners für jedes .. im Pfad (z. B. ../ für eine Ebene höher, ../../ für zwei Ebenen höher in der Hierarchie).

Beachten Sie, dass nachgestellte Schrägstriche nicht akzeptiert werden.

Wichtig: Wenn Sie die Orchestrator-API in Verbindung mit MSXML verwenden, kann die Antwort 204 Kein Inhalt zu einem 1223-Statuscode führen und Fehler verursachen.

GET-Abfragen (GET Requests)

GET-Abfragen sind normalerweise die einfachsten, die es gibt. Mit ihnen können Sie Daten abrufen und generische OData-Klauseln verwenden:

• $top
• $filter
• $erweitern
• $select
• $bestellen nach
• $skip

$top

Diese Klausel hilft Ihnen, die Menge der abgerufenen Daten zu begrenzen. Sie hat einen Höchstwert, der von dem Endpunkt bestimmt wird, an den Sie Abfragen richten, und der Anzahl dieser Ressourcen, die in Ihren Orchestrator-Instanzen vorhanden sind.

Beispiel: Diese Abfrage https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$top=10 ergibt die ersten 10 in der Community Edition von Orchestrator verfügbaren Umgebungen. Wenn jedoch nur 5 Umgebungen vorhanden sind, werden nur diese abgefragt.

$filter

Diese OData-Klausel wird verwendet, um eine bestimmte Ressource nach ihren Eigenschaften zu filtern.

Zum Beisiel kann man filtern nach:

• numerischen Eigenschaften:
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=Id%20eq%2015 - fragt nach einer bestimmte Umgebung basierend auf deren ID
• Texteigenschaften:
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=contains(Name,'N')&$top=10 - ergibt die ersten 10 Umgebungen, deren Name den Buchstaben „N“ enthält.
• Boolesche Eigenschaften:
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Processes?$filter=Title%20eq%20'test'%20%26%20IsLatestVersion%20eq%20true - ergibt alle Prozesse, die das Wort „Test“ enthalten und die neueste Version darstellen
• aufzählbare Eigenschaften:
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/QueueItems?$filter=Priority%20eq%20'High' - ergibt alle Warteschlangenobjekte, die eine hohe Priorität haben
• Die Eigenschaft einer Eigenschaft:
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation' - ergibt die ersten 10 Jobs, die von einem Roboter auf dem „Dokumentations“-Computer ausgeführt wurden.

Filterparameter können mit den logischen Operatoren „und“, „oder“ und/oder „nicht“ verknüpft und mit Klammern „( )“ angeordnet werden, wie die folgende Anfrage:

• https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Jobs?$top=10&$filter=Robot/MachineName eq 'LAVINIA-PC' and (not(Source eq 'Manual') or StartTime gt 2017-10-28T12:13:00.07Z) - zeigt die ersten 10 Jobs an, die manuell oder nach „2017-10-28T12:13:00.07Z“ von einem auf dem „LAVINIA-PC“ Computer installierten Roboter ausgeführt werden.

Bekanntes Problem

OData-$filter-Abfragen, die einen Ausdruck enthalten, der ein verschachteltes komplexes Objekt mit null vergleicht, funktionieren nicht. Beispielsweise gibt die Verwendung des Ausdrucks Release ne null einen Fehler zurück, da Release ein komplexes Objekt ist, das seine eigenen geschachtelten Eigenschaften enthält.

In solchen Fällen empfehlen wir, das komplexe Objekt durch ein einfaches Objekt zu ersetzen.

Beispiele:

• Sie können Release ne null durch ReleaseName ne null ersetzen, da ReleaseName ein vorhandenes einfaches Objekt ist.
  Hinweis: Sie können Machine ne null nicht durch MachineName ne null ersetzen, da MachineName nicht vorhanden ist.
• Sie können eine verschachtelte Eigenschaft für das komplexe Objekt zum Vergleichen verwenden. Zum Beispiel kann Release ne null durch Release/Name ne null und Machine ne null durch Machine/Name ne null ersetzt werden.

$erweitern

Diese Klausel wird verwendet, um Navigationseigenschaften der angeforderten Ressource vollständig zu laden.

$select

Mit dieser OData-Klausel können Sie eine Untergruppe von Ressourceneigenschaften angeben, die Sie zurückgegeben haben möchten. Wenn Sie mehrere Ressourcen extrahieren möchten, können Sie diese durch Komma trennen.

$bestellen nach

Die Klausel $orderby ermöglicht Ihnen das Sortieren abgerufener Ressourcen. Wie bei der Klausel $select sind die Ressourcen, die Sie ordnen möchten, durch Komma getrennt und können in aufsteigender (asc) oder absteigender (desc) Reihenfolge sortiert werden. Ist keiner dieser Operatoren angegeben, werden die Ressourcen automatisch in aufsteigender Reihenfolge sortiert.

$skip

Mit dieser Klausel können Sie die ersten n Elemente in einem angegebenen Filter überspringen.

POST-Abfragen

Mit dem Verb POST HTTP können Sie neue Objekte erstellen, die anderen Ressourcen untergeordnet sind. Beim Erstellen einer neuen Ressource POST für die übergeordnete ordnet Orchestrator die neue Ressource der übergeordneten zu und weist ihr eine ID sowie andere erforderliche Informationen zu. Die Daten werden im Hauptteil der Anfrage hinzugefügt und die Antwort ist das gesamte erstellte Objekt.

Sie können einer Warteschlange neue Objekte hinzufügen, neue Assets, Umgebungen oder Prozesse erstellen, einer oder mehreren fehlgeschlagenen Transaktionen einen Prüfer zuweisen, und so weiter.

Hinweis: Bei Sonderzeichen ist im Hauptteil der POST-Abfrage kein Escaping möglich. Um Sonderzeichen zu verwenden, müssen Sie zunächst den Parameter, in dem Sie diese als Zeichenfolge verwenden, im folgenden Format "[e-mail]": "#String" deklarieren. Um dies besser zu verstehen, schauen Sie sich an, wie der Parameter Specific Content im Beispiel unten ausgefüllt wurde.

PUT-Abfragen

PUT ist normalerweise erforderlich, wenn Sie den Inhalt einer Ressource aktualisieren möchten. Im Allgemeinen werden Anforderungen an eine bestimmte Entität gestellt, indem deren Id in der URL hinzugefügt wird. Beachten Sie, dass ein PUT-Aufruf die vorhandene Entität durch den Inhalt der Anforderung ersetzt oder, wenn keine am angegebenen Speicherort vorhanden ist, versucht, sie zu erstellen.

Es besteht die Möglichkeit, Warteschlangen, Umgebungen, Organisationseinheiten, Kommentare zu Transaktionen, Prozesse und andere Details von Ressourcen zu aktualisieren.

PATCH-Anforderungen

PATCH wird verwendet, um den Inhalt einer vorhandenen Entität zu aktualisieren, wobei die gewünschte Entität durch Hinzufügen ihres Id in der URL angegeben wird. Der Text der Anforderung enthält nur die Inhalte, die Sie ändern möchten. Dies unterscheidet sich von einem PUT-Aufruf, der die aktuelle Entität durch den Inhalt der nachfolgenden Anforderung ersetzt .

Es ist möglich, eine PATCH-Anforderung zu verwenden, um Maschinen, Prozesse, Roboter, Mandanten, Benutzer (außer Organisationseinheit und Rollen) und Webhooks-Entitäten zu aktualisieren.

DELETE-Abfragen

Mit diesem HTTP-Verb können Sie ein angegebenes Objekt in der Datenbank als gelöscht markieren. Die Ressource wird normalerweise mit Hilfe ihrer ID in der URL, an welche Sie die Abfrage richten, angegeben. Eine Antwort 204 informiert Sie, dass Ihre Abfrage erfolgreich war.

Es besteht die Möglichkeit, Assets, Warteschlangenobjektkommentare, Prozesse, Rollen, Mandanten, Benutzer und viele andere zu löschen.