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 Webservices-Server abrufen, erstellen, aktualisieren oder löschen können, der die REST-Architektur unterstützt.

Rollen und Verfügbarkeit

Verfügbar als Aktionsdesigner-Aktionsschritt. Benutzer mit der Rolle „action_designer“ können eine benutzerdefinierte 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 in Anmeldeinformationen, Verbindungen und Aliasse.
Verbindungsalias	Datensatz des Alias 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 zugeordneten 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 benutzerdefinierte 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 (2-fach verschlüsselt) im Datenbereich angezeigt. Hinweis: Dieses Feld ist verfügbar, wenn in der Liste Verbindung die Option Verbindungsalias verwenden 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 zugeordneten 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. Ebenso müssen Sie Ihre benutzerdefinierte Aktion nicht aktualisieren, wenn sich die Anmeldeinformationen ändern. Weitere Informationen zu Verbindungen und Anmeldeinformationen finden Sie unter Anmeldeinformationen, Verbindungen und Aliasnamen. Der Wert der Anmeldeinformationen wird als Datenpille Passwort (2-fach verschlüsselt) im Datenbereich angezeigt. Hinweis: Dieses Feld ist verfügbar, wenn Inline-Verbindung definieren aus der Liste Verbindung ausgewählt wird.
MID verwenden	Option zur Verwendung eines ServiceNow® MID-Server zum Ausführen des REST-Schritt . Aktivieren Sie diese Checkbox, um die Felder MID-Anwendung und Fähigkeiten anzuzeigen. Hinweis: Das System protokolliert REST-Anforderungen, -Antworten 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 Verbindungsalias verwenden ausgewählt ist, wird in diesem Feld die dem Alias zugeordnete Basis-URL angezeigt. Sie können die Basis-URL überschreiben, indem Sie auf das (Schlosssymbol) klicken und eine eigene 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. Klicken Sie zum Testen auf die Schaltfläche REST-Schritt testen. Geben Sie die erforderlichen Eingabewerte ein, und klicken Sie auf die Schaltfläche Test ausführen. Nachdem der Test ausgeführt wurde, werden alle Schrittausgaben oder Fehlermeldungen im Abschnitt „Testergebnisse“ des Testfensters 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, läuft die Verbindungsanforderung ab. Wenn Inline-Verbindung definieren ausgewählt ist, geben Sie einen Zeitüberschreitungswert für die Verbindung ein. Lassen Sie dieses Feld leer, um den Standard-Zeitüberschreitungswert für Verbindungen zu verwenden.
MID-Auswahl	Option zum Auswählen des spezifischen MID-Servers oder MID-Clusters. MID Server automatischauswählen: Wählt den MID Server automatisch aus. Spezifischer MID Server: Verwendet den von Ihnen ausgewählten MID Server. Spezifischer MID-Cluster: Verwendet den von Ihnen ausgewählten MID-Cluster. Dieses Feld ist verfügbar, wenn Inline-Verbindung definieren in der Verbindungsliste ausgewählt ist und MID verwenden aktiviert ist.
MID-Anwendung	Fähigkeiten, die MID-Server unterstützen müssen, um für die Auswahl in Frage zu kommen. Das System führt den Aktionsschritt von einem 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 MID- Auswahlliste ausgewählt ist.
Funktionen	Fähigkeiten, die MID-Server unterstützen müssen, um für die Auswahl in Frage zu kommen. Das System führt den Aktionsschritt von einem 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 MID- Auswahlliste 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 MID-Auswahlliste 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 Liste Verbindung ausgewählt ist, MID verwenden aktiviert ist und Spezifischer MID-Cluster in der MID-Auswahlliste ausgewählt ist.
Build-Anforderung	Option, um die Anforderung manuell zu erstellen, eine OpenAPI-Spezifikation zu importieren oder eine REST-Nachricht zu importieren. 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-Support im REST-Schritt. Aus REST-Nachricht: Importieren Sie eine Plattform-REST-Nachricht. Weitere Informationen finden Sie unter REST-Nachrichten in einen REST-Schritt importieren.
API-Quelle	Option zur Auswahl einer OpenAPI-Spezifikation, die zum Erstellen der Anforderung verwendet wird, oder 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 bereitstellen oder Inhalte kopieren und einfügen. Hinweis: Dieses Feld ist verfügbar, wenn Sie in der Liste Anforderung erstellen die Option Aus OpenAPI-Spezifikation 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 in der Liste Anforderung erstellen die Option Aus OpenAPI-Spezifikation 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 aus der Liste Anforderung erstellen auswählen.
REST-Nachrichtenfunktion	Name der Funktion, die aus der REST-Nachricht importiert werden soll. Die verfügbaren Optionen werden durch die HTTP-Methoden bestimmt, die der ausgewählten REST-Nachricht zugeordnet sind. Hinweis: Dieses Feld ist verfügbar, wenn Sie Aus REST-Nachricht aus der Liste Anforderung erstellen auswählen.
REST-Nachricht importieren	Schaltfläche zum Importieren der REST-Nachricht. Hinweis: Dieses Feld ist verfügbar, wenn Sie eine REST-Nachricht aus dem Feld REST -Nachricht auswählen.
Resource Path	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ützt REST-Schrittanforderungen, die doppelte Abfrageparameternamen enthalten. Wenn Sie eine REST-Anforderung erstellen, die doppelte Abfrageparameternamen enthält, fügt Flow Designer die Abfrageparameter der Anforderung 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 Anforderungskopfzeilen enthalten. Wenn Sie eine REST-Anforderung erstellen, die doppelte Anforderungskopfzeilen enthält, werden die Kopfzeilen in der Reihenfolge gesendet, 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.
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 DELETElautet.
Anforderungstext [Text]	Text der Anforderung im JSON- oder XML-Format. Die Details der Flow-Ausführung zeigen den Antworttext entweder als Link zum eingebetteten Text-Viewer oder als sys_id des Anhangdatensatzes an, der die Antwort enthält. Hinweis: Dieses Feld kann bearbeitet werden, wenn Sie Text aus der Liste Anforderungstyp auswählen.
Anhang	Anhangsdatensatz, der die Anforderung enthält. Sie können diesen Datensatz in einem vorherigen Schritt suchen oder erstellen und ihn als Eingabevariable definieren. Erstellen Sie sie mithilfe der APIs JSONStreamingBuilder und XMLStreamingBuilder im Skriptschritt. Hinweis: Dieses Feld ist verfügbar, wenn Sie Binär in der Liste „Anforderungstyp“ auswählen.
Name, Teiletyp, Wert	Inhalt einer mehrteiligen Anforderung. Geben Sie für jedes Teil seinen Namen, Teiletyp und Wert an, indem Sie entweder die Felder einzeln verwenden oder ein Inline-Skript für alle Teile verwenden. Sie können die Multipart-Werte angeben, indem Sie auf das Symbol zum Umschalten der Skripterstellung (Symbol zum Umschalten der ) klicken und das Skript bearbeiten. Weitere Informationen zum Inline-Skripting finden Sie unter Inline-Skripts. Name: Der Name des Teils. Es kann eine beliebige gültige Zeichenfolge sein. Teiletyp: Der Typ des Teils. Wählen Sie entweder Text oder Datei aus. 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 Dateiname festlegen die Option Aus Anhang aus, um den Dateinamendes angehängten Datensatzes zu verwenden, oder wählen Sie die Eingabe Aus Dateiname aus, um einen eigenen einzugeben. Wählen Sie für „ Inhaltstyp festlegen“ die Option Aus Anhang aus, um den Inhaltstyp des angehängten Datensatzes zu verwenden, oder wählen Sie die Eingabe „ Aus Inhaltstyp“, um einen eigenen Inhaltstyp einzugeben. Wert: Der Inhalt des Teils. Bei Text entspricht der Wert dem Textinhalt. Bei einer Datei ist der Wert die sys_id des Anhangdatensatzes, der den Inhalt enthält. Hinweis: Diese Felder sind verfügbar, wenn Sie Mehrteilig 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 verwenden oder ein Inline-Skript für alle Teile verwenden. Sie können das Inline-Skript für Formular-URL-codierte Werte angeben, indem Sie auf das Symbol zum Umschalten der Skripterstellung (Symbol zum Umschalten der ) 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 Anhang speichern	Option, um anzugeben, ob die Antwort als Datensatz in der Tabelle „Anhang“ [sys_attachment] gespeichert werden soll.
Dateiname der Anlage	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 Anhangdatei	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 Eingabevariable definieren. Die Details der Flow-Ausführung zeigen die sys_id des zugeordneten Datensatzes an. Hinweis: Dieses Feld ist verfügbar, wenn Als Anhang speichern ausgewählt ist.

Felder für Aktionsfehlerauswertung

Feld	Beschreibung
Wenn dieser Schritt fehlschlägt	Option, um mit der Ausführung des nächsten Schritts fortzufahren oder zur Fehlerauswertung zu wechseln. Informationen zur Verwendung des Schrittstatuscodes oder der Meldung für eine Fehlerbedingung für eine benutzerdefinierte Aktion finden Sie unter Aktionsfehlerbewertung.

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 Antwortgrößenbegrenzung mit der Systemeigenschaft glide.pf.rest.response_payload_max_size. Diese Systemeigenschaft unterstützt einen maximalen Wert von 1024, wodurch die Größe der REST-Antwort auf 10 MB begrenzt wird.

Analysieren einer REST-Antwort

REST API-Aufrufe geben Daten im Antworttext zurück. Die Antworttextdaten 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 in einem Flow verwendet werden sollen. Es gibt auch einen , um einen Antworttext zu analysieren, der in einem XML-Format vorliegt.

Die allgemeine Strategie zum Abrufen extrahierter Daten aus der Antwort besteht in der folgenden Vorgehensweise.

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 aus dem REST-Schritt zu übergeben.
   • Erstellen Sie Ausgabevariablen, um Daten aus der Antwort zurückzugeben.
3. Erstellen Sie ein Skript, um Daten zu analysieren und zuzuordnen.
   • Verwenden Sie die JSON.parse()- Methode 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 im REST in der IntegrationHub-Entwicklerschulung.