REST-Internetdienst Paket

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

Arbeiten mit REST-Internetdienst-Aktionen

Geben Sie die folgenden Informationen an, um eine REST-Anforderung zu senden und eine Antwort zu erhalten. Nicht alle Parameter sind für alle Methoden erforderlich.
  • Den URI eingeben: Eindeutige Adresse für eine API-Ressource.
  • Proxy-Konfiguration: Um den Proxy einzustellen, wählen Sie die Registerkarte System oder Benutzerdefiniert der Proxy-Konfiguration.
    Option Beschreibung
    System

    Der Systemproxy ist der Proxy, der auf dem Bot Runner-Rechner konfiguriert ist, auf dem der Bot ausgeführt wird.

    Wenn diese Option ausgewählt ist, verwendet der Bot-Agent den Systemproxy.
    Benutzerdefiniert

    Diese Option ermöglicht es Ihnen, benutzerdefinierte Proxy-Einstellungen innerhalb der Aktionen von REST-Internetdienst zu konfigurieren. Wenn beispielsweise eine REST-API über einen anderen Proxy als den Systemproxy geleitet werden soll, können Sie die Option Benutzerdefiniert auswählen und Proxy-Details innerhalb der REST-Aktionen angeben.

    Machen Sie die folgenden Angaben:

    • Host: Der Hostname oder die IP-Adresse des Proxys
    • Port: Die Portnummer des Proxys
    • Nutzername (optional): Der für die Proxy-Authentifizierung verwendete Nutzername
    • Passwort (optional): Das für die Proxy-Authentifizierung verwendete Passwort
      Anmerkung: Wenn es sich bei dem zu konfigurierenden Proxy um einen authentifizierten Proxy handelt, müssen Sie die Authentifizierungsdaten in den Feldern Nutzername und Passwort angeben.
    Für die Felder Host, Port, Nutzername und Passwort wählen Sie die Registerkarte Anmeldedaten, Variable oder Unsichere Zeichenfolge:
    • Anmeldedaten: Verwenden Sie einen im Credential Vault verfügbaren Wert.
    • Variable: Verwenden Sie eine Variable, die einen Anmeldedatenwert in einer nutzerdefinierten Variable speichert.
    • Unsichere Zeichenfolge: Geben Sie den Wert, den Sie verwenden möchten, manuell ein.
  • Authentifizierungsmodus: Es gibt drei unterstützte Authentifizierungsmodi:
    • Keine Authentifizierung: Verwenden Sie diese Option, um auf die Endpunkte zuzugreifen, die keine Authentifizierung für den Zugriff auf ihre Server erfordern.
    • Nutzertoken für Control Room: Die REST-Internetdienst-Aktionen nutzen das Token, das bei der Anmeldung im Control Room generiert wurde, um auf die Endpunkte zuzugreifen.
    • Basic: Basic ist die einfachste Art, Nutzer zu authentifizieren. Wenn Sie diese Option wählen, müssen Sie den Nutzernamen und das Passwort eingeben. Bei dieser Technik wird ein Header namens Authorization verwendet, der eine base64-kodierte Darstellung des eingegebenen Nutzernamens und Passworts enthält.
    • Angemeldeter AD-Nutzer: Active Directory-Nutzer, die zum Zugriff auf die entsprechende API berechtigt sind, werden über das AD authentifiziert. Für die Anforderung sind keine Anmeldedaten erforderlich.
    • Authentifizierung über Windows NT LAN Manager (NTLM) (AD-Nutzer): Challenge/Response-Authentifizierungsmethode, mit der Clients ihren Nutzernamen und ihr Passwort als verschlüsselte Anmeldedaten oder als Klartext angeben können. Wir empfehlen, dass Sie Anmeldedaten verwenden, die im Automation Anywhere-Credential Vault gespeichert sind.
    • OAuth2 – Control Room verwaltet: Wenn Sie OAuth in den Control Room integrieren, können Sie Token, die zur Authentifizierung bei Drittanbietern verwendet werden, zentral verwalten und sicher speichern. Sie müssen den Webdienst konfigurieren und die Authentifizierungsdetails (wie etwa Client-ID, Geheimer Clientschlüssel, Autorisierungs-URL usw.) notieren, um die OAuth-Verbindung im Control Room zu nutzen. Weitere Details finden Sie unter Konfigurieren Sie OAuth-Verbindungen im Control Room

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

  • Header: Nicht alle Methoden benötigen einen Header. Ein Header enthält die mit der Anforderung verbundenen Metadaten.
  • Inhaltstyp: Wenn ein Header einen Inhaltstyp enthält, definiert dieser die Content Negotiation Inhaltsvereinbarung zwischen dem Client und dem Server. REST-Internetdienst Aktionen unterstützen die folgenden Inhaltstypen:
    • application/x-www-form-urlencoded: Kodieren Sie die Parameter in der URL.
    • JSON (application/json): Geben Sie einen Text für die JSON-Anforderung ein.
    • XML (application/xml): Geben Sie einen Text für XML-Anforderung ein.
    • Text (text/plain)
    • XML (text/xml)
    • HTML (text/html)
    • multipart/form-data:
      • Senden Sie Binärdaten, in den meisten Fällen zum Hochladen von Dateien auf den Server. Sie werden in Fällen verwendet, in denen Sie mehrere Teile in einer einzigen Anforderung senden, die in der Regel Textdaten (wie Formularfelder) und möglicherweise einen Dateiupload umfasst. Sie können auch eine FileStream-Variable verwenden. Weitere Informationen finden Sie unten.
      • FileStream: Der FileStream kann nach der Zuweisung zu einer Variablen gelesen werden. Sie können beispielsweise einen FileStream lesen, der einer Variablen in einem OneDrive-Speicherort zugewiesen ist. Weitere Informationen finden Sie unter Aktion „Datei zuweisen“.FileStream für REST Web Services
    • Binär: Verwenden Sie Binary, um RAW-Dateien wie Bilder, Videos und Audiodateien zu senden. Wenn Sie Binary auswählen, können Sie eine Binärdatei hochladen (als Variable, Control Room-Datei oder Desktop-Datei).
    • 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
  • Ersatz hinzufügen: Ermöglicht die Eingabe von Variablen in den REST-Anforderungstext. Eine Variable ist eine symbolische Darstellung von Daten, mit der Sie auf einen Wert zuzugreifen können, ohne ihn manuell eingeben zu müssen, wo immer Sie ihn benötigen. Zum Beispiel die folgende REST-Text-Anforderung:
    {
   "name":"{{name}}",
   "email":"{{email}}",
   "status":"Active"
}
    Im obigen Anforderungstext können Sie die Variablen innerhalb von doppelten Klammern ersetzen, indem Sie auf Ersetzung hinzufügen klicken und die erforderlichen Werte hinzufügen.
  • Erweiterte Optionen:
    • Fehlerantwort erfassen: Wählen Sie das Kontrollkästchen, um die Fehlerantwort zu erfassen, außer bei der Antwort Erfolg/Ok. Die Einzelheiten zur Fehlerantwort werden im Antwortkörper festgehalten.
    • Unsichere Verbindung bei der Verwendung von https erlauben: Wählen Sie das Kontrollkästchen aus, unsichere Verbindung bei https zu erlauben.
    • Cookies akzeptieren: Wählen Sie das Kontrollkästchen, um Sitzungscookies aus Serverantworten automatisch zu erfassen.
      • Erfassen: Wenn diese Funktion aktiviert ist, werden Sitzungscookies, die in Serverantworten enthalten sind, erfasst.
      • Sicherer Speicher: Erfasste Cookies sind innerhalb des Prozessspeichers verschlüsselt, so werden sie niemals dauerhaft gespeichert und sind außerhalb Ihrer Automatisierungssitzung nicht zugänglich.
      • Wiederverwenden: Cookies werden automatisch in nachfolgende REST-Aufrufe einbezogen, wodurch die manuelle Handhabung von Cookies entfällt und die Zuverlässigkeit der Automatisierung verbessert wird.
      • Handhabung mehrerer Cookies: Die Funktion verarbeitet mehrere vom Server zurückgegebene Cookies nahtlos, so dass alle erforderlichen Authentifizierungsdaten enthalten sind.
      • Vernichtung: Erfasste Cookies werden automatisch vernichtet, wenn die Automatisierungssitzung endet oder der Bot die Ausführung abschließt, um Datensicherheit und Datenschutz zu garantieren.
      Anmerkung: Die erfassten Cookies sind spezifisch für die Domäne, aus der sie stammen, und werden nicht automatisch für nachfolgende REST-Aufrufe genutzt, die an verschiedene Domänen gerichtet sind. Das bedeutet, dass Cookies, die von domainA.com erfasst wurde, nicht für Anfragen an domainB.com verwendet werden.
    • Datei herunterladen: (Nur verfügbar mit der Get-Methode) Aktivieren Sie dieses Kontrollkästchen, um die Datei an einen bestimmten Ort herunterzuladen. Die URI muss eine Datei zurückgeben/herunterladen. Geben Sie den gewünschten Ordnerpfad und Dateinamen mit Erweiterung an. Vergewissern Sie sich, dass Sie die richtige Dateierweiterung verwenden. Beispiel: C:/Users/Downloads/image01.jpg
      Tipp: Markieren Sie die Option Datei überschreiben, wenn sie bereits existiert, um eine Datei mit demselben Namen zu überschreiben, der bereits in dem Ordner vorhanden ist, in dem Sie die Datei speichern möchten.
      Fehlerbehandlung:
      Ungültiger URI:
      Wenn der angegebene URI falsch ist, wird eine Fehlermeldung angezeigt.
      Datei nicht gefunden:
      Wenn die API-Antwort leer ist, weil die Datei nicht an dem angegebenen Ort existiert, wird eine Fehlermeldung angezeigt.
      Unzureichende Berechtigungen:
      Wenn Sie keine Schreibberechtigung für den Download-Speicherort haben, wird eine Fehlermeldung angezeigt.
      Dateierweiterung stimmt nicht überein:
      Wenn die Dateierweiterung nicht dem erwarteten Typ entspricht, wird eine Fehlermeldung angezeigt.
  • Auf Abschluss der Aktion warten: Sie können einen Timeout-Wert festlegen, wenn Sie eine REST-Anforderung senden und eine Antwort erhalten. Beim Durchführen von Aktionen wie POST, PUT, DELETE, PATCH und GET im Feld Warten, bis die Aktion abgeschlossen ist, können Sie die Wartezeit (in Millisekunden) angeben. Standardmäßig beträgt die Wartezeit 60.000 Millisekunden.
  • Ausgabevariable: Die Antwortausgabe wird in einer Wörterbuchvariable erfasst. Eine Wörterbuchvariable ist ein Paar aus Schlüssel und Wert. Verwenden Sie den Namen des Antwort-Heades als Schlüssel, um den Header-Wert zurückzugeben, oder „Text“ (Body) als Schlüssel, um den Antworttext zurückzugeben.
    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 eine Schleife Aktion nach der REST-Internetdienst Aktion hinzu.
    2. Wählen Sie den Für jeden Schlüssel im Wörterbuch Iterator.
    3. Im Feld Wörterbuchvariable wählen Sie die Variable, die die REST-Internetdienst Aktion-Ausgabe hält.
    4. Weisen Sie den Wert jedes Schlüssels zu $prompt-assignment$ zu.
    5. Fügen Sie eine In Datei protokollieren Aktion hinzu.
    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.

Werte sicher übermitteln

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

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

Aktionen in der REST-Internetdienst Paket

Aktion Beschreibung
DELETE-Methode Entfernt die Ressource, die vom URI identifiziert wurde.
GET-Methode Ruft Informationen ab, die durch die im URI enthaltenen Parameter identifiziert wurden. Es gibt keinen Inhaltstyp für die GET-Methode, weil alle Parameter als Teil des URI übergeben werden.

Die Beschränkungen und Merkmale der GET-Methode umfasst Folgendes:

  • Die URI-Länge ist auf 2048 Zeichen begrenzt.
  • Alle Parameter werden im URI übergeben.
  • Die GET-Methode gibt Daten frei, die sich im URI befinden, was sie gegenüber der POST Methode weniger sicher macht.
  • GET ändert keine Daten, was sie sicher für alle Nutzer unabhängig von der Autorisierung macht.

Einzelheiten finden Sie unter Verwendung der GET-Methode.
Patch-Methode Ändert die Ressource, die durch den URI identifiziert wurde.
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 wurden. Einzelheiten finden Sie unter Verwendung der PUT-Methode.

Proxy-Support

Wenn Ihr Gerät mit einem Proxy konfiguriert ist, werden alle ausgehenden Anforderungen von diesem Paket über den Proxyserver geleitet. Einzelheiten finden Sie unter Den Bot-Agent mit einem Gerät mit Proxy verbinden.