REST-Schritt

Senden Sie eine ausgehende REST-Webdienstanforderung an ein externes System.

Hinweis:

REST-Schritt ist im Basissystem nicht verfügbar und erfordert das -Abonnement ServiceNow® IntegrationHub. Nachdem das erforderliche Plugin aktiviert wurde, wird der Schritt unter Integrationen angezeigt.

Der ausgehende REST-Webservice ist eine Plattformfunktion, mit der Sie Daten auf einem Webdienstserver, der die REST-Architektur unterstützt, abrufen, erstellen, aktualisieren oder löschen können.

Rollen und Verfügbarkeit

Verfügbar als Workflow-Studio-Aktionsschritt. Benutzer mit der Rolle „action_designer“ können eine anwenderdefinierte Aktion mit einem oder mehreren Aktionsschritten erstellen.

Felder

Feld	Beschreibung
Verbindung	Art der zu verwendenden Verbindung. Verbindung Inline definieren: Definieren Sie die Verbindungsinformationen innerhalb des Aktionsschritts. Verbindungs-Alias verwenden: Definieren Sie die Verbindungsinformationen mithilfe der Tabelle „Verbindungsalias“. Wenn Sie einen Alias verwenden, müssen Sie nicht mehrere Anmeldeinformations- und Verbindungsinformationsprofile konfigurieren, wenn Sie eine Aktion in mehreren Umgebungen verwenden. Ebenso müssen Sie Ihre benutzerdefinierte Aktion nicht aktualisieren, wenn sich die Verbindungsinformationen ändern. Weitere Informationen zu Verbindungen und Anmeldeinformationen finden Sie unter Einführung zu Anmeldeinformationen, Verbindungen und Aliassen.
Verbindungsalias	Aliasdatensatz für Verbindungen und Anmeldeinformationen, den das System zum Ausführen des Aktionsschritts verwendet. Benutzer mit der Rolle „flow_designer“ oder „admin“ können einen zugehörigen Verbindungsdatensatz erstellen oder auswählen. Wenn Sie einen Alias verwenden, müssen Sie nicht mehrere Anmeldeinformations- und Verbindungsinformationsprofile konfigurieren, wenn Sie eine Aktion in mehreren Umgebungen verwenden. Ebenso müssen Sie Ihre anwenderdefinierte Aktion nicht aktualisieren, wenn sich die Verbindungsinformationen ändern. Weitere Informationen zu Verbindungen und Anmeldeinformationen finden Sie unter Anmeldeinformationen, Verbindungen und Aliasnamen. Der Wert der Anmeldeinformationen wird als Datenpille Passwort (zweifach verschlüsselt) im Datenbereich angezeigt. Hinweis: Dieses Feld ist verfügbar, wenn Verbindungsalias verwenden aus der Verbindungsliste ausgewählt wird.
Anmeldeinformationsalias	Anmeldeinformationsalias, den das System zum Ausführen des Aktionsschritts verwendet. Benutzer mit der Rolle „flow_designer“ oder „admin“ können einen zugehörigen Verbindungsdatensatz erstellen oder auswählen. Wenn Sie einen Alias verwenden, müssen Sie nicht mehr mehrere Anmeldeinformationen konfigurieren, wenn Sie eine Aktion in mehreren Umgebungen verwenden. Auch wenn sich die Anmeldeinformationen ändern, müssen Sie Ihre anwenderdefinierte Aktion nicht aktualisieren. Weitere Informationen zu Verbindungen und Anmeldeinformationen finden Sie unter Anmeldeinformationen, Verbindungen und Aliasnamen. Der Wert der Anmeldeinformationen wird als Datenpille Passwort (zweifach verschlüsselt) im Datenbereich angezeigt. Hinweis: Dieses Feld ist verfügbar, wenn Verbindung inline definieren aus der Verbindungsliste ausgewählt wird.
MID verwenden	Option zur Verwendung eines ServiceNow® MID-Server zum Ausführen des REST-Schritt . Aktivieren Sie dieses Kontrollkästchen, um die Felder „MID-Anwendung“ und „Fähigkeiten“ anzuzeigen. Hinweis: Das System protokolliert REST-Anforderungs-, Antwort- und Parameterlaufzeitdaten, die über einen MID-Server gesendet werden, nicht auf die gleiche Weise wie die Protokollierung ausgehender Webservices. Stattdessen können Sie diese Daten in den Flow-Ausführungsdetailsanzeigen.
Basis-URL	Basis-URL für die REST-Anforderung. Wenn Use Connection Alias (Verbindungsalias verwenden) ausgewählt ist, zeigt dieses Feld die Basis-URL an, die dem Alias zugeordnet ist. Sie können die Basis-URL überschreiben, indem Sie auf das Sperrsymbol ( ) klicken und eine eigene URL eingeben. Wenn Verbindung Inline definieren ausgewählt ist, geben Sie eine Basis-URL für die Verbindung ein.
REST-Schritt testen	Schaltfläche zum Testen des REST-Schritts. Wählen Sie zum Testen die Schaltfläche REST-Schritt testen aus. Geben Sie die erforderlichen Eingabewerte ein, und wählen Sie die Schaltfläche Run Test (Test ausführen). Nach dem Ausführen des Tests werden im Abschnitt „Testergebnisse“ des Testfensters alle Schrittausgaben oder Fehlermeldungen angezeigt.
Verbindungszeitüberschreitung	Anzahl der Millisekunden, die das System auf eine erfolgreiche Hostverbindung wartet. Wenn der Schritt während dieser Zeit keine erfolgreiche Verbindung herstellt, kommt es zu einer Zeitüberschreitung der Verbindungsanforderung. Wenn „Verbindung inline definieren“ ausgewählt ist, geben Sie einen Timeout-Wert für die Verbindung ein. Lassen Sie dieses Feld leer, um den Standard-Zeitüberschreitungswert für Verbindungen zu verwenden. Hinweis: Vermeiden Sie es, den Wert für die Verbindungszeitüberschreitung auf Null zu setzen, da dies zu einer veralteten Verbindung führen kann.
MID-Auswahl	Option zum Auswählen des spezifischen MID-Servers oder MID-Clusters. MID-Server automatisch auswählen: Wählt den MID-Server automatisch aus. Spezifischer MID-Server: Verwendet den ausgewählten MID-Server. Spezifischer MID-Cluster: Verwendet den ausgewählten MID-Cluster. Dieses Feld ist verfügbar, wenn „Inline definieren“ in der Verbindungsliste ausgewählt wird und „MID verwenden“ aktiviert ist.
MID-Anwendung	Fähigkeiten, die die MID-Server unterstützen müssen, um ausgewählt zu werden. Das System führt den Aktionsschritt über einen MID-Server aus, der die ausgewählten Fähigkeiten unterstützt. Dieses Feld ist verfügbar, wenn Inline-Verbindung definieren in der Verbindungsliste ausgewählt ist, das Kontrollkästchen MID verwenden aktiviert ist und MID-Server automatisch auswählen in der Liste MID-Auswahl ausgewählt ist.
Fähigkeiten	Fähigkeiten, die die MID-Server unterstützen müssen, um ausgewählt zu werden. Das System führt den Aktionsschritt über einen MID-Server aus, der die ausgewählten Fähigkeiten unterstützt. Dieses Feld ist verfügbar, wenn Inline-Verbindung definieren in der Verbindungsliste ausgewählt ist, das Kontrollkästchen MID verwenden aktiviert ist und MID-Server automatisch auswählen in der Liste MID-Auswahl ausgewählt ist.
MID-Server	Datenpille des erforderlichen MID-Server. Dieses Feld ist verfügbar, wenn Inline-Verbindung definieren in der Verbindungsliste ausgewählt ist, das Kontrollkästchen MID verwenden aktiviert ist und Spezifischer MID-Server in der Liste MID-Auswahl ausgewählt ist.
MID-Cluster	Datenpille für den MID-Cluster, den Sie verwenden möchten. Dieses Feld ist verfügbar, wenn Inline-Verbindung definieren in der Verbindungsliste ausgewählt ist, MID verwenden aktiviert ist und Spezifischer MID-Cluster in der Liste MID-Auswahl ausgewählt ist.
Build-Anforderung	Option zum manuellen Erstellen der Anforderung, zum Importieren einer OpenAPI-Spezifikation oder zum Importieren einer REST-Nachricht. Manuell: Erstellen Sie Aktionseingaben, und füllen Sie das REST-Schrittformular manuell aus. Aus OpenAPI-Spezifikation: Importieren Sie eine OpenAPI-Spezifikation, um Aktionseingaben zu generieren und das REST-Schrittformular auszufüllen. Weitere Informationen finden Sie unter OpenAPI-Unterstützung im REST-Schritt. Aus REST-Nachricht: Importieren Sie eine Plattform-REST-Nachricht. Weitere Informationen hierzu finden Sie unter REST-Nachricht in einen REST-Schritt importieren.
API-Quelle	Option zur Auswahl einer OpenAPI-Spezifikation, die zum Erstellen der Anforderung verwendet wird, oder zur Auswahl von OpenAPI importieren, um eine neue OpenAPI-Spezifikation zu importieren. Sie können Spezifikationen importieren, indem Sie eine URL für YAML oder JSON angeben oder Inhalt kopieren und einfügen. Hinweis: Dieses Feld ist verfügbar, wenn Sie Aus OpenAPI-Spezifikation in der Liste Build-Anforderung auswählen.
API-Vorgang	Option zum Auswählen eines Vorgangs aus der Liste. Verfügbare Vorgänge werden von der OpenAPI-Spezifikation im Feld API-Quelle bereitgestellt. Hinweis: Dieses Feld ist verfügbar, wenn Sie Aus OpenAPI-Spezifikation in der Liste Build-Anforderung auswählen.
REST-Nachricht	Name der zu importierenden REST-Nachricht. Wählen Sie eine REST-Nachricht aus der Liste aus. Hinweis: Dieses Feld ist verfügbar, wenn Sie Aus REST-Nachricht in der Liste Build-Anforderung auswählen.
REST-Nachrichtenfunktion	Name der Funktion, aus der die REST-Nachricht importiert werden soll. Die verfügbaren Optionen hängen von den HTTP-Methoden ab, die der ausgewählten REST-Nachricht zugeordnet sind. Hinweis: Dieses Feld ist verfügbar, wenn Sie Aus REST-Nachricht in der Liste Build-Anforderung auswählen.
REST-Nachricht importieren	Schaltfläche zum Importieren der REST-Nachricht. Hinweis: Dieses Feld ist verfügbar, wenn Sie eine REST-Nachricht im Feld REST-Nachricht auswählen.
Ressourcenpfad	Pfad für die Ressource.
HTTP-Methode	Zur Verarbeitung der Anforderung verwendete HTTP-Methode. GET POST PUT PATCH LÖSCHEN
Abfrageparameter	Name-Wert-Paare, die an den REST-Endpunkt übergeben werden sollen. Sie können diese Parameter manuell erstellen oder Eingabevariablen in die Parameterfelder ziehen und dann einen Wert zuweisen. Unterstützen Sie REST-Schrittanforderungen, die doppelte Abfrageparameternamen enthalten. Wenn Sie eine REST-Anforderung erstellen, die doppelte Abfrageparameternamen enthält, fügt Workflow-Studio der Anforderung die Abfrageparameter in der Reihenfolge hinzu, in der Sie sie definiert haben. Hinweis: Beim Importieren einer OpenAPI-Spezifikation fügt das System dem REST-Schritt alle in der Spezifikation enthaltenen Parameter und Header hinzu. Überprüfen Sie die endgültigen REST-Schrittwerte, und entfernen Sie Parameter, die Sie in der Anforderung nicht senden möchten. Wenn die API beispielsweise Inhaltstypheader für JSON und XML akzeptiert, fügt das System beide Header dem REST-Schritt hinzu. Entfernen Sie je nach Inhaltstyp, den Sie in der Antwort erhalten möchten, einen der Header.
Header	Header, die mit der Anforderung gesendet werden sollen. Sie können Header manuell erstellen oder Eingabevariablen in die Parameterfelder ziehen und dann einen Wert zuweisen. Unterstützen Sie REST-Schrittanforderungen, die doppelte Anforderungsheader enthalten. Wenn Sie eine REST-Anforderung erstellen, die doppelte Anforderungsheader enthält, werden die Header in der von Ihnen definierten Reihenfolge gesendet. Hinweis: Beim Importieren einer OpenAPI-Spezifikation fügt das System dem REST-Schritt alle in der Spezifikation enthaltenen Parameter und Header hinzu. Überprüfen Sie die endgültigen REST-Schrittwerte, und entfernen Sie Parameter, die Sie in der Anforderung nicht senden möchten. Wenn die API beispielsweise Inhaltstypheader für JSON und XML akzeptiert, fügt das System beide Header dem REST-Schritt hinzu. Entfernen Sie je nach Inhaltstyp, den Sie in der Antwort erhalten möchten, einen der Header.
Anforderungstyp	Format der Anforderung. Verfügbare Optionen: Text: Eine Anforderung in JSON, XML oder einem anderen Textformat. Binär: Eine Anfrage in einem binären Dateiformat. Multipart: Eine Anforderung, die aus mehreren Inhaltstypen besteht. Formular-URL-kodiert: Eine Anforderung in einer URL-kodierten Abfrage. Hinweis: Dieses Feld kann bearbeitet werden, wenn die HTTP-MethodePOST, PUT, PATCHoder DELETEausgewählt ist.
Anforderungstext [Text]	Textkörper der Anforderung im JSON- oder XML-Format. In den Flow-Ausführungsdetails wird der Antworttext entweder als Link zum eingebetteten Text-Viewer oder als sys_id des Anhangdatensatzes angezeigt, der die Antwort enthält. Hinweis: Dieses Feld kann bearbeitet werden, wenn Sie in der Liste Anforderungstyp die Option Text auswählen.
Anhang	Anhangsdatensatz, der die Anforderung enthält. Sie können diesen Datensatz in einem vorherigen Schritt suchen oder erstellen und als Eingabevariable definieren. Erstellen Sie sie mithilfe der APIs JSONStreamingBuilder und XMLStreamingBuilder im Schritt Skript. Hinweis: Dieses Feld ist verfügbar, wenn Sie in der Liste Anforderungstyp die Option Binär auswählen.
Name, Teiletyp, Wert	Inhalt einer mehrteiligen Anforderung. Geben Sie für jedes Teil den Namen, den Teiletyp und den Wert an, indem Sie entweder die Felder einzeln oder ein Inline-Skript für alle Teile verwenden. Sie können die mehrteiligen Werte angeben, indem Sie auf das Symbol zum Umschalten der Skripterstellung klicken ( ) und das Skript bearbeiten. Weitere Informationen zum Inline-Skripting finden Sie unter Inline-Skripts. Name: Der Name des Teils. Es kann sich um eine beliebige gültige Zeichenfolge handeln. Teiletyp: Der Typ des Teils. Wählen Sie entweder Text oder Dateiaus. Text: Der Text für das Teil. Sobald Text ausgewählt ist, können Sie den Inhaltstyp angeben. Datei: Die Datei für das Teil. Wenn „Datei“ ausgewählt ist, muss der Wert die sys_id des Anhangdatensatzes sein, der den Inhalt enthält. Sie können diesen Datensatz in einem vorherigen Schritt suchen oder als Eingabewert definieren. Sobald Datei ausgewählt ist, können Sie den Dateinamen und den Inhaltstyp angeben. Wählen Sie für Dateinamefestlegen die Option Aus Anhang aus, um den Dateinamen des angehängten Datensatzes zu verwenden, oder wählen Sie Eingabe Aus Dateiname, um einen eigenen Namen einzugeben. Wählen Sie für Inhaltstyp festlegendie Option Aus Anhang aus, um den Inhaltstyp des angehängten Datensatzes zu verwenden, oder wählen Sie die Eingabe Aus Inhaltstyp aus, um einen eigenen einzugeben. Wert: Der Inhalt des Teils. Bei Text entspricht der Wert dem Textinhalt. Bei einer Datei ist der Wert die sys_id des Anhangsdatensatzes, der den Inhalt enthält. Hinweis: Diese Felder sind verfügbar, wenn Sie Multipart in der Liste Anforderungstyp auswählen.
Name, Wert	Inhalt einer URL-codierten Formularanforderung. Geben Sie jeden Teil der URL-codierten Anforderung mit einem Name-Wert-Paar an, indem Sie die Felder einzeln oder ein Inline-Skript für alle Teile verwenden. Sie können das Inline-Skript für URL-codierte Werte des Formulars angeben, indem Sie auf das Symbol zum Umschalten der Skripterstellung klicken ( ) und das Skript bearbeiten. Weitere Informationen zum Inline-Skripting finden Sie unter Inline-Skripts. Hinweis: Dieses Feld ist verfügbar, wenn Sie Formular URL-codiert in der Liste Anforderungstyp auswählen.
Wiederholungsrichtlinie aktivieren	Option zum Aktivieren der Wiederholungsrichtlinie. Weitere Informationen finden Sie unter Wiederholungsrichtlinie.
Standardrichtlinie für Alias überschreiben	Option zum Überschreiben der Standardwiederholungsrichtlinie. Dieses Kontrollkästchen ist nicht verfügbar, wenn in der Verbindungsliste die Option Verbindung inline definieren ausgewählt ist.
Wiederholungsrichtlinie	Standardwiederholungsrichtlinie, die dem Verbindungsalias zugeordnet ist. Wenn Standardrichtlinie für Alias überschreiben ausgewählt ist, können Sie die Standardwiederholungsrichtlinie überschreiben und eine andere vorhandene Neuversuchsrichtlinie basierend auf Ihrer Anforderung auswählen.
Als Anlage speichern	Option zum Festlegen, ob die Antwort als Datensatz in der Tabelle „Anhang“ [sys_attachment] gespeichert werden soll.
Dateiname des Anhangs	Name des von der REST-Antwort erstellten Anhangs. Zum Beispiel: rest-response.txt. Hinweis: Dieses Feld ist verfügbar, wenn Als Anhang speichern ausgewählt ist.
Datensatz der Dateianlage	Zieldatensatz, dem der Anhang zugeordnet ist. Der Zieldatensatz muss eine Datenpille vom Typ Datensatzsein. Zum Beispiel einen spezifischen Incident-Datensatz. Sie können diesen Datensatz in einem vorherigen Schritt nachschlagen oder als Eingangsvariable definieren. In den Flow-Ausführungsdetails wird die sys_id des zugeordneten Datensatzes angezeigt. Hinweis: Dieses Feld ist verfügbar, wenn Als Anhang speichern ausgewählt ist.

Fehlerbewertung der Aktion

Wenn dieser Schritt fehlschlägt

Datentyp: Choice

Option, um den nächsten Schritt auszuführen oder zur Fehlerauswertung zu wechseln. Informationen zur Verwendung des Schrittstatuscodes oder der Nachricht für eine anwenderdefinierte Aktionsfehlerbedingung finden Sie unter Fehlerbewertung der Aktion.

Größenbeschränkungen für REST-Antworten

Standardmäßig begrenzt das System die Größe von REST-Antworten, die nicht als Anlagen gespeichert werden, auf 5 MB. Direkte REST-Antworten, die diesen Grenzwert überschreiten, erzeugen einen Fehler. Um größere Antwortgrößen zu unterstützen, speichern Sie die Antwort entweder als Anhang, oder erhöhen Sie die Größenbeschränkung für die Antwort mit der Systemeigenschaft glide.pf.rest.response_payload_max_size. Diese Systemeigenschaft unterstützt einen maximalen Wert von 10240 KB, wodurch die Größe der REST-Antwort auf 10 MB begrenzt wird.

Eine REST-Antwort wird analysiert

REST-API-Aufrufe geben Daten im Antworttext zurück. Die Daten des Antworttexts sind normalerweise im JSON- oder XML-Format strukturiert. Sie können Skriptschritt verwenden, um die strukturierten Daten in Variablen zu analysieren, die an anderer Stelle in der Aktion oder im Flow verwendet werden können. Es gibt auch einen XML parser step zum Analysieren eines Antworttexts, der im XML-Format vorliegt.

Die allgemeine Strategie zum Abrufen extrahierter Daten aus der Antwort besteht darin, Folgendes zu tun.

1. Überprüfen Sie den Antworttext, um die zurückzugebenden Daten auszuwählen.
2. Erstellen Sie Eingabe- und Ausgabevariablen im Skriptschritt.
   • Erstellen Sie eine Eingabevariable, um den Antworttext vom REST-Schritt zu übergeben.
   • Erstellen Sie Ausgabevariablen, um Daten aus der Antwort zurückzugeben.
3. Erstellen Sie ein Skript zum Analysieren und Zuordnen von Daten.
   • Verwenden Sie die Methode JSON.parse() in einem Skriptschritt, um einen JSON-Antworttext zu analysieren.
   • Ordnen Sie die analysierten Daten den Ausgabevariablen zu.
4. Erstellen Sie Aktionsausgaben für die Ausgabevariablen, um die Daten für einen Flow verfügbar zu machen.

Ein detailliertes Beispiel finden Sie im Abschnitt zum Analysieren einer REST-Antwort in der REST in IntegrationHub-Entwicklerschulung.