REST Web Services package

Verwenden Sie die actions im REST Web Services-package als Methoden (DELETE, GET, PATCH, POST oder PUT), um Anforderungen an eine API zu senden und Antworten von ihr zu erhalten.

Einstellungen

Die folgenden Einstellungen sind für die REST Web Services-actions verfügbar. Konfigurieren Sie die entsprechenden Einstellungen, um eine REST-Anforderung zu senden und eine Antwort zu erhalten. Jede Methode erfordert spezifische Parameter.

Anmerkung: Wenn Sie Automatisierungen auf der macOS-Plattform erstellen und actions wie (DELETE, GET, PATCH, POST oder PUT) verwenden, werden die folgenden Authentifizierungsmodi nicht unterstützt:
  • NTLM-Authentifizierung (AD-Nutzer)
  • Angemeldeter AD-Nutzer
URI
Geben Sie den URI für die API-Ressource ein. Wählen Sie eine der folgenden Optionen und konfigurieren Sie die Einstellungen entsprechend:
  • Den URI eingeben: Geben Sie den URI direkt ein oder wählen Sie den URI, der als Zeichenfolgenvariable gespeichert ist.
  • Anmeldeinformation als URI auswählen: Verwenden Sie diese Option, um einen URI auszuwählen, die als Anmeldeinformation im Credential Vault gespeichert ist. Verwenden Sie Anmeldeinformation > Auswählen, um die Anmeldeinformation direkt auszuwählen. Sie können auch die Option Variable verwenden, um eine Anmeldeinformation auszuwählen, die einer Anmeldeinformationsvariablen zugeordnet ist. Mit dieser Option können Sie die URIs ausblenden, die sensible Informationen wie Autorisierungscodes oder API-Schlüssel enthalten.
Proxykonfiguration
Konfigurieren Sie die Proxyeinstellungen für die REST Web Services-Aktionen. Wählen Sie eine der folgenden Optionen und konfigurieren Sie die Einstellungen entsprechend:
  • System: Wählen Sie diese Option, damit der Bot Agent den Systemproxy verwendet. Der Systemproxy ist der Proxy, den Sie auf dem bot Runner-Rechner konfigurieren, auf dem die Automatisierung ausgeführt wird.
  • Benutzerdefiniert: Wählen Sie diese Option, um benutzerdefinierte Proxy-Einstellungen für die Automatisierung zu konfigurieren. Konfigurieren Sie die folgenden Einstellungen:
    • Host: Der Hostname oder die IP-Adresse des Proxyservers.
    • Port: Die Portnummer des Proxyservers.
    • Nutzername (optional): Der Nutzername zur Authentifizierung des Proxyservers.
    • Kennwort (optional): Das Passwort zur Authentifizierung des Proxyservers.
    Anmerkung: Sie müssen den Nutzernamen und das Passwort für jeden authentifizierten Proxy-Server konfigurieren.
    Sie können eine der Optionen Anmeldeinformation, Variable oder Unsichere Zeichenfolge verwenden, um die Proxy-Einstellungen zu konfigurieren.
    • Anmeldedaten: Um einen im Credential Vault verfügbaren Wert auszuwählen.
    • Variable: Um die Anmeldeinformation-Variable auszuwählen, die einem Wert zugeordnet ist.
    • Unsichere Zeichenfolge: Um den Wert manuell einzugeben oder einen Wert auszuwählen, der einer vordefinierten Zeichenfolgenvariablen zugeordnet ist.
Authentifizierungsmodus
Konfigurieren Sie die Authentifizierungseinstellungen für die REST Web Services-Aktionen. Wählen Sie eine der folgenden Optionen und konfigurieren Sie die Einstellungen entsprechend:
  • Keine Authentifizierung: Wählen Sie diese Option, um auf die Endpunkte zuzugreifen, die keine Authentifizierung für den Zugriff auf ihre Server erfordern.
  • Nutzertoken für Control Room: Wählen Sie diese Option, um das Token zu verwenden, das beim Anmelden im Control Room generiert wird.
  • Basic: Wählen Sie diese Option, um den Nutzernamen und das Passwort einzugeben, um die REST Web Services API-Aufrufe zu authentifizieren. Diese Option fügt dem API-Call einen Header namens Authorization hinzu, der eine base64-kodierte Zeichenfolgendarstellung des Nutzernamens und Passworts enthält.
  • Angemeldeter AD-Nutzer: Wählen Sie diese Option, um die Active Directory (AD)-basierte Authentifizierung auszuwählen. Die AD-Nutzer, die berechtigt sind, auf die zugehörige API zuzugreifen, werden mithilfe von AD authentifiziert. Für die Anforderung sind keine Anmeldedaten erforderlich.
  • Authentifizierung über Windows NT LAN Manager (NTLM) (AD-Nutzer): Wählen Sie diese Option, um eine Challenge-Response-NTLM-Authentifizierung auszuwählen. Konfigurieren Sie die folgenden Einstellungen:
    • Domain: Geben Sie die Domain ein, in der der API-Call authentifiziert werden muss. Sie können auch eine Zeichenfolgenvariable auswählen, die der Domain oder dem Host zugeordnet ist.
    • Nutzername (optional): Der Nutzername zur Authentifizierung des API-Calls.
    • Kennwort (optional): Das Passwort zur Authentifizierung des API-Calls.
    Sie können eine der Optionen Anmeldeinformation, Variable oder Unsichere Zeichenfolge verwenden, um den Nutzernamen und das Passwort zu konfigurieren. Wir empfehlen, entweder die Option Anmeldeinformation zu verwenden, um eine Anmeldeinformation aus dem Credential Vault auszuwählen, oder eine Anmeldeinformationsvariable zu verwenden.
  • OAuth2 – Control Room verwaltet: Wählen Sie diese Option, um eine vom Control Room verwaltete OAuth Verbindung als Authentifizierungsoption auszuwählen. Weitere Details finden Sie unter Configure OAuth connections in Control Room.

    Das folgende Video zeigt, wie Sie die OAuth-Verbindung in REST Web Services nutzen können:

Header
Fügen Sie benutzerdefinierte Header hinzu, um zusätzliche Metadaten in die API-Anfragen einzuschließen. Nicht alle Methoden benötigen einen Header. Sie können Header wie Authorization, Accept-Charset, Content-Type, Cache-Control, User-Agent usw. hinzufügen.

Klicken Sie auf Header hinzufügen und folgen Sie den Anweisungen im Modal Benutzerdefinierte Header, um die erforderlichen Header hinzuzufügen. Sie können eine in der Credential Vault gespeicherte Anmeldeinformation oder Anmeldeinformationsvariable auswählen oder den Header direkt als unsichere Zeichenfolge eingeben.

Inhaltstyp
Der Inhaltstyp-Header definiert den Medientyp des Inhalts im Anfragetext. Die REST Web Services-actions unterstützen folgende Dateitypen:
  • application/x-www-form-urlencoded: Kodiert die Parameter im Format einer URL-Abfragezeichenfolge.
  • JSON (application/json): Geben Sie einen Text im JSON-Format für die Anforderung ein.
  • XML (application/xml): Geben Sie einen Text im XML-Format für die Anfrage ein.
  • Text (text/plain): Geben Sie einen Texttyp-Anfragetext im Klartextformat ein.
  • XML (text/xml) Geben Sie einen Texttyp-Anfragetext im XML-Format ein.
  • HTML (text/html) Geben Sie einen Texttyp-Anfragetext im HTML-Format ein.
  • multipart/form-data: Erlaubt es Ihnen, sowohl Text als auch Dateien in den Anfragetext aufzunehmen. Dieser Inhaltstyp unterstützt alle Dateiformate, die die API unterstützt. Sie können diesen Inhaltstyp verwenden, um mehrere Teile in einer einzigen Anfrage zu senden, die typischerweise Textdaten (wie Formularfelder) und möglicherweise einen Dateiupload enthalten. Dieser Inhaltstyp unterstützt auch das Streaming von Dateien.
    Ein Dateistream kann nach der Zuweisung zu einer Dateityp-Variablen gelesen werden. Sie können beispielsweise einen Dateistream lesen, der einer Variablen in einem OneDrive-Speicherort zugewiesen ist. Weitere Informationen finden Sie unter action „Datei zuweisen“.
    FileStream für REST Web Services
  • Binär: Verwenden Sie Binary, um RAW-Dateien wie Bilder, Videos und Audiodateien zu senden. Sie können die Dateien mit einer der folgenden Optionen hochladen:
    • Variable: Weisen Sie eine Dateivariable zu, um eine Datei vom Desktop oder innerhalb des Control Rooms hochzuladen. Sie können diese Option auch verwenden, um Dateien von einem Speicherort zu streamen.
    • Control Room-Datei: Laden Sie eine Datei hoch, die im Control Room-Speicher verfügbar ist.
    • Desktop-Datei: Laden Sie eine Datei direkt von Ihrem Desktop hoch.
  • Benutzerdefiniert
    Benutzerdefiniert: Fügen Sie benutzerdefinierte Inhalte hinzu, die nicht unter den Standard-Inhaltstyp fallen. Wenn Sie beispielsweise von v.11.x auf Automation 360 migrieren, fällt der folgende Wert nicht unter einen der Standard-Inhaltstypen: application/vnd.whispir.message-v1+json

Für application/x-www-form-urlencoded und multipart/form-data klicken Sie auf Parameter hinzufügen und folgen Sie den Anweisungen im Parameter-Modell, um die erforderlichen Header-Parameter hinzuzufügen.

Für andere Inhaltstypen können Sie die Option Parameter eingeben oder die Option Anmeldeinformation als Parameter auswählen verwenden, um die Parameter hinzuzufügen. Mit der Option Anmeldeinformation als Parameter auswählen können Sie sensible Daten als Anfrage-Header hinzufügen.

Ersatz hinzufügen
Die Option Ersatz hinzufügen ermöglicht die Eingabe von Variablen in den REST-Anfragestext. Diese Option ist verfügbar für JSON (application/json), XML (application/xml), Text (text/plain), XML (text/xml), HTML (text/html) und Benutzerdefinierte Inhaltstyp-Header.
Eine Variable ist eine symbolische Darstellung von Daten und ermöglicht es Ihnen, auf einen Wert zuzugreifen, ohne ihn manuell eingeben zu müssen, wo immer Sie ihn benötigen. Betrachten Sie zum Beispiel den folgenden REST-Anforderungstext:
{
   "name":"{{name}}",
   "email":"{{email}}",
   "status":"Active"
}
Im obigen Anforderungstext können Sie die in doppelten Klammern eingeschlossenen Variablen ersetzen, indem Sie auf Ersatz hinzufügen klicken und die erforderlichen Werte hinzufügen.
Erweiterte Optionen
Fehlerreaktion erfassen: Aktivieren Sie das Kontrollkästchen, um die Fehlerreaktion zu erfassen (mit Ausnahme der Antwort Erfolg/OK). Das System erfasst die Details der Fehlerantwort im Antwortkörper. Diese Option ist in Delete-, Get-, Patch-, Post- und Put-Methode-Aktionen verfügbar.
Unsichere Verbindung bei https erlauben: Aktivieren Sie das Kontrollkästchen, um eine unsichere Verbindung bei der Verwendung des https-Protokolls zu erlauben. Diese Option ist in allen Aktionen verfügbar.
Cookies akzeptieren: Aktivieren Sie das Kontrollkästchen, um Sitzungs-Cookies automatisch aus Serverantworten zu erfassen. Die folgenden Funktionen werden im Hintergrund aktiviert, wenn Sie dieses Kontrollkästchen auswählen.
  • Erfassen: Das System erfasst Sitzungscookies, die der Server in Antworten einschließt.
  • Sicherer Speicher: Das System verschlüsselt die erfassten Cookies im Prozessspeicher, sodass sie niemals dauerhaft gespeichert werden und außerhalb Ihrer Automatisierungssitzung unzugänglich sind.
  • Wiederverwenden: Das System fügt die Cookies automatisch in nachfolgende REST-Aufrufe ein, wodurch die manuelle Handhabung von Cookies entfällt und die Zuverlässigkeit der Automatisierung verbessert wird.
  • Handhabung mehrerer Cookies: Das System ermöglicht es der Automatisierung, mehrere vom Server zurückgegebene Cookies zu verarbeiten und stellt sicher, dass alle erforderlichen Authentifizierungsanmeldeinformationen enthalten sind.
  • Vernichtung: Das System vernichtet die erfassten Cookies automatisch, wenn die Automatisierungssitzung endet oder die Bot-Ausführung beendet ist, sodass Datensicherheit und Datenschutz gewährleistet sind.

Diese Option ist in Delete-, Get-, Patch-, Post- und Put-Methode-Aktionen verfügbar.

Anmerkung: Die erfassten Cookies sind spezifisch für die Domäne, aus der sie stammen, und werden nicht automatisch für nachfolgende REST-Aufrufe verwendet, die in anderen Domänen erfolgen. Das bedeutet, dass Cookies, die von domainA.com erfasst wurden, nicht für Anfragen an domainB.com verwendet werden.
Datei herunterladen: Aktivieren Sie dieses Kontrollkästchen, um die im URI verfügbare Binärdatei an einen bestimmten Speicherort herunterzuladen. Sie müssen den gewünschten Dateipfad mit Namen und Erweiterung eingeben. Beispiel: <C:/Users/Downloads/image01.jpg>

Diese Option ist nur in der Get-Methode-Aktion verfügbar. Das System zeigt eine Fehlermeldung an, wenn einer der folgenden Szenarien auftritt:

  • Ungültiger URI: Wenn der angegebene URI falsch ist.
  • Datei nicht gefunden: Wenn die API-Antwort leer ist, weil die Datei am angegebenen Ort nicht existiert.
  • Unzureichende Berechtigungen: Wenn Sie keine Schreibberechtigung für den Download-Speicherort haben.
  • Dateierweiterung stimmt nicht überein: Wenn die Dateierweiterung nicht dem erwarteten Typ entspricht.

Aktivieren Sie das Kontrollkästchen Datei überschreiben, wenn bereits vorhanden, um eine vorhandene Datei mit einer neuen Version zu überschreiben.

Auf Abschluss der Aktion warten
Sie können einen Timeout-Wert festlegen, wenn Sie eine REST-Anforderung senden und eine Antwort erhalten. Wenn Sie actions wie POST, PUT, DELETE, PATCH und GET ausführen, geben Sie die Wartezeit (in Millisekunden) im Feld Warten, bis die Aktion abgeschlossen ist an. Standardmäßig beträgt die Wartezeit 60.000 Millisekunden
SSL/TLS-Konfiguration
Verwenden Sie diese Option, um eine Zertifikatsdatei mit oder ohne Passwort hochzuladen, um während der REST API-Aufrufe eine zusätzliche Authentifizierung bereitzustellen.

Die SSL/TLS-Konfiguration verwendet das Mutual TLS (mTLS)-Protokoll, um die Kommunikation zwischen der API-URI und dem Client zu verschlüsseln, zu authentifizieren und zu sichern. mTLS erfordert, dass beide Einheiten einander durch den Austausch von Zertifikaten authentifizieren. Die Datenübertragung erfolgt nur, wenn beide Einheiten die ausgetauschten Zertifikate erfolgreich authentifizieren.

Der REST Web Services unterstützt .p12-Zertifikatstypen für Windows-Computer und das .pfx-Format für Nicht-Windows-Computer.

  • KeyStore-Dateipfad (optional): Laden Sie die Zertifikatsdatei mit der Option Variable, Control Room-Datei oder Desktop-Datei hoch.
  • Passwort für den KeyStore (optional): Wenn das Zertifikat passwortgeschützt ist, können Sie das Zertifikatspasswort mit der Option Anmeldedaten, Variable oder Unsichere Zeichenfolge authentifizieren. Weitere Informationen zum sicheren Speichern von Passwörtern im Anmeldedaten-Tresor finden Sie unter Anmeldedaten und lockers im Credential Vault.
Weisen Sie die Ausgabe einer Variable zu
Die Antwortausgabe wird in einer Wörterbuchvariablen erfasst. Eine Wörterbuchvariable ist ein Paar aus Schlüssel und Wert. Verwenden Sie den Namen des Antwort-Headers als Schlüssel, um den Header-Wert zurückzugeben, oder verwenden Sie „Body“ als Schlüssel, um den Antwortkörper zurückzugeben.

Diese Option ist in Delete-, Get-, Patch-, Post- und Put-Methode-Aktionen verfügbar.

Anmerkung: Der Antwortschlüssel mit seinem Wert ist in der Wörterbuchvariablen verfügbar, um den Antwortstatus der REST-API anzuzeigen.
Führen Sie die folgenden Schritte aus, um eine Liste der Header-Namen für die API-Ressource zu erhalten:
  1. Fügen Sie nach der Loop-action eine REST Web Services-action ein.
  2. Wählen Sie den Iterator Für jeden Schlüssel im Wörterbuch aus.
  3. Wählen Sie im Feld Wörterbuchvariable die Variable aus, die als Ausgabe die REST Web Services-action enthält.
  4. Weisen Sie $prompt-assignment$ den Wert jedes Schlüssels zu.
  5. Fügen Sie eine „Text in Datei protokollieren“-action ein.
  6. Geben Sie den Dateipfad zu einer Textdatei an, die die Liste der Header-Namen enthält.
  7. Fügen Sie $prompt-assignment$ im Feld Zum Protokollieren Text eingeben ein.
  8. Wählen Sie die Option Vorhandene Datei überschreiben.
  9. Klicken Sie auf Speichern.

    Wenn Sie den bot ausführen, druckt er die Header-Namen aus der API-Ressource in die ausgewählte Datei.

Datei einer Variablen zuordnen
Diese Option ist nur in der Aktion „Dateistream abrufen“ verfügbar. Die Aktion „Dateistream abrufen“ ermöglicht es Ihnen, eine Dateivariable der im URI verfügbaren Datei zuzuweisen. Sie können diese Dateivariable dann in allen nachfolgenden Aktionen innerhalb der Sitzung verwenden. Weitere Informationen zum Zuweisen einer Dateivariable finden Sie unter Verwendung der Aktion „Dateistream abrufen“ (Get file stream).

Werte sicher übermitteln

Sie können Werte sicher vom Credential Vault an den Webdienst übermitteln, indem Sie den locker, die Anmeldedaten und das Attribut in den folgenden unterstützten action-Feldern angeben:
  • URI
  • Benutzerdefinierte Header
  • Textkörper: Für den Inhaltstyp application/x-www-form-urlencoded klicken Sie auf Parameter hinzufügen und wählen Sie den Wert aus dem Credential Vault.

    Für alle anderen Inhaltstypen wählen Sie die Option Anmeldedaten als Parameter auswählen und klicken Sie auf Wählen.

Actions im REST Web Services-package

Action Beschreibung
DELETE-Methode Entfernt die Ressource, die durch den URI identifiziert wird.
GET-Methode Ruft Informationen ab, die durch die im URI enthaltenen Parameter identifiziert werden. Es gibt keinen Inhaltstyp für die GET-Methode, da alle Parameter als Teil des URI übergeben werden.

Die GET-Methode hat folgende Beschränkungen und Merkmale:

  • Die URI-Länge ist auf 2048 Zeichen begrenzt.
  • Alle Parameter werden im URI übergeben.
  • Die GET-Methode gibt Daten preis, die im URI enthalten sind. Sie ist daher weniger sicher als die POST-Methode.
  • Die GET-Methode ändert keine Daten und ist daher für alle Nutzer unabhängig von deren Berechtigung sicher.

Einzelheiten finden Sie unter Verwendung der GET-Methode.
Patch-Methode Ändert die Ressource, die durch den URI identifiziert wird.
POST-Methode Erzeugt eine neue Ressource im URI.
  • Die Parameter werden im Anforderungstext übergeben.
  • Es gibt keine Längenbeschränkung für einen Anforderungstext.

Einzelheiten finden Sie unter Verwendung der POST-Methode.
PUT-Methode Aktualisiert oder ersetzt eine Ressource anhand von Parametern, die im URI oder im Textkörper übergeben werden. Einzelheiten finden Sie unter Verwendung der PUT-Methode.

Proxy support

If your device is configured with a proxy, all outbound requests from this package are routed through the proxy server. See Den Bot Agent mit einem Gerät mit Proxy verbinden.