REST-Schritt

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

Hinweis:

REST-Schritt Ist im Basissystem nicht verfügbar und erfordert ServiceNow® IntegrationHubAbonnement. Nachdem das erforderliche Plugin aktiviert wurde, ist der Schritt unter Integrationen sichtbar.

Ausgehender REST-Webservice Ist eine Plattformfunktion, mit der Sie Daten auf einem Webserviceserver abrufen, erstellen, aktualisieren oder löschen können, der die REST-Architektur unterstützt.

Rollen und Verfügbarkeit

Verfügbar als Workflow-Studio-Aktionsschritt. Anwender 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 in Anmeldeinformationen, Verbindungen und Aliasse .
Verbindungsalias	Alias-Datensatz für Verbindungen und Anmeldeinformationen, den das System zur Ausführung des Aktionsschritts verwendet. Anwender 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. Wenn sich die Verbindungsinformationen ändern, müssen Sie Ihre anwenderdefinierte Aktion nicht aktualisieren. Weitere Informationen zu Verbindungen und Anmeldeinformationen finden Sie unter Anmeldeinformationen, Verbindungen und Aliasnamen. Der Anmeldeinformationswert wird im Datenbereich als Passwortdatenpille (zweifach verschlüsselt) angezeigt. Hinweis: Dieses Feld ist verfügbar, wenn Verwenden Sie Den Verbindungsalias Ist aus der Verbindungsliste ausgewählt.
Anmeldeinformationsalias	Anmeldeinformationsalias, den das System zur Ausführung des Aktionsschritts verwendet. Anwender 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. 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 Anmeldeinformationswert wird im Datenbereich als Passwortdatenpille (zweifach verschlüsselt) angezeigt. Hinweis: Dieses Feld ist verfügbar, wenn Definieren Sie Die Verbindung Inline Ist aus der Verbindungsliste ausgewählt.
MID verwenden	Option zur Verwendung von ServiceNow® MID-Server Zum Ausführen von REST-Schritt . Aktivieren Sie dieses Kontrollkästchen, um anzuzeigen MID-Anwendung Und Fähigkeiten Felder. Hinweis: Das System protokolliert keine REST-Anforderungs-, Antwort- und Parameter-Laufzeitdaten, die über einen MID-Server gesendet werden Protokollierung ausgehender Webservices Tritt auf. Stattdessen können Sie diese Daten in anzeigen Flow-Ausführungsdetails .
Basis-URL	Basis-URL für die REST-Anforderung. Wenn Verwenden Sie Den Verbindungsalias Ist ausgewählt, zeigt dieses Feld die Basis-URL an, die dem Alias zugeordnet ist. Sie können die Basis-URL überschreiben, indem Sie auf das Schlosssymbol ( ) Und Eingabe Ihres eigenen. 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 aus REST-Schritt testen Schaltfläche. Geben Sie alle erforderlichen Eingabewerte ein, und wählen Sie aus Test Ausführen Schaltfläche. Nach den Testläufen 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, tritt bei der Verbindungsanforderung eine Zeitüberschreitung auf. Wenn Definieren Sie Die Verbindung Inline Ist ausgewählt, 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. Hinweis: Vermeiden Sie das Festlegen von Verbindungszeitüberschreitung Wert auf Null, da dies zu einer veralteten Verbindung führen kann.
MID-Auswahl	Option zum Auswählen eines bestimmten MID-Servers oder MID-Clusters. Wählen Sie eine der folgenden Optionen aus. Wählen Sie DEN MID-Server automatisch aus : Ihr ServiceNowInstanz wählt aus MID-ServerOhne manuelle Eingabe. Spezifischer MID-Server : Ihr ServiceNowInstanz verwendet MID-ServerDie Sie angeben. Spezifischer MID-Cluster : Ihr ServiceNowInstanz verwendet den von Ihnen angegebenen MID-Cluster. Ein MID-Cluster ist eine Gruppe von MID-Servern, die Ihren aktivieren ServiceNowInstanz zur Verarbeitung mehrerer Integrationen und zur Verbesserung der Integrationsgeschwindigkeit. Weitere Informationen finden Sie unter Configure a MID Server cluster. Dieses Feld ist verfügbar, wenn Definieren Sie Die Verbindung Inline Ist aus der Verbindungsliste und ausgewählt MID verwenden Ist aktiviert.
MID-Anwendung	Fähigkeiten der MID-Server Muss unterstützen, um für die Auswahl berechtigt zu sein. Das System führt den Aktionsschritt von einem aus aus MID-Server Die die ausgewählten Fähigkeiten unterstützt. Dieses Feld ist verfügbar, wenn Definieren Sie Die Verbindung Inline Ist aus der Verbindungsliste ausgewählt, MID verwenden Kontrollkästchen ist aktiviert, und MID-Server automatisch auswählen Ist aus der MID-Auswahlliste ausgewählt.
Fähigkeiten	Fähigkeiten der MID-Server Muss unterstützen, um für die Auswahl berechtigt zu sein. Das System führt den Aktionsschritt von einem aus aus MID-Server Die die ausgewählten Fähigkeiten unterstützt. Dieses Feld ist verfügbar, wenn Definieren Sie Die Verbindung Inline Ist aus der Verbindungsliste ausgewählt, MID verwenden Kontrollkästchen ist aktiviert, und MID-Server automatisch auswählen Ist aus der MID-Auswahlliste ausgewählt.
MID-Server	Datenpille des erforderlichen MID-Server. Dieses Feld ist verfügbar, wenn Definieren Sie Die Verbindung Inline Ist aus der Verbindungsliste ausgewählt, MID verwenden Kontrollkästchen ist aktiviert, und Bestimmter MID-Server Ist aus der MID-Auswahlliste ausgewählt.
MID-Cluster	Datenpille für den MID-Cluster, den Sie verwenden möchten. Dieses Feld ist verfügbar, wenn Definieren Sie Die Verbindung Inline Ist aus der Verbindungsliste ausgewählt, MID verwenden Ist aktiviert, und Spezifischer MID-Cluster Ist aus der MID-Auswahlliste ausgewählt.
Build-Anforderung	Option zum manuellen Erstellen der Anforderung, Importieren einer OpenAPI-Spezifikation oder Importieren einer REST-Nachricht. Manuell : Erstellen Sie Aktionseingaben, und füllen Sie das REST-Schritt-Formular manuell aus. Aus OpenAPI-Spezifikation : Importieren Sie eine OpenAPI-Spezifikation, um Aktionseingaben zu generieren und das REST-Schritt-Formular auszufüllen. Weitere Informationen finden Sie unter OpenAPI-Unterstützung im REST-Schritt . Aus REST-Nachricht : Import einer Plattform-REST-Nachricht. Weitere Informationen finden Sie unter Importieren Sie eine REST-Nachricht in einen REST-Schritt .
API-Quelle	Option zum Auswählen einer OpenAPI-Spezifikation, die zum Erstellen der Anforderung verwendet wird, oder wählen Sie aus Importieren Sie OpenAPI Dient zum Importieren einer neuen OpenAPI-Spezifikation. Sie können Spezifikationen importieren, indem Sie eine URL für YAML oder JSON angeben oder Inhalte kopieren und einfügen. Hinweis: Dieses Feld ist verfügbar, wenn Sie auswählen Aus OpenAPI-Spezifikation Aus der Liste „Build-Anforderung“.
API-Vorgang	Option zum Auswählen eines Vorgangs aus der Liste. Verfügbare Vorgänge werden von der OpenAPI-Spezifikation in bereitgestellt API-Quelle Feld. Hinweis: Dieses Feld ist verfügbar, wenn Sie auswählen Aus OpenAPI-Spezifikation Aus der Liste „Build-Anforderung“.
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 auswählen Aus REST-Nachricht Aus der Liste „Build-Anforderung“.
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 auswählen Aus REST-Nachricht Aus der Liste „Build-Anforderung“.
REST-Nachricht importieren	Schaltfläche zum Importieren der REST-Nachricht. Hinweis: Dieses Feld ist verfügbar, wenn Sie eine REST-Nachricht aus auswählen REST-Nachricht Feld.
Ressourcenpfad	Pfad für die Ressource.
HTTP-Methode	HTTP-Methode, die zur Verarbeitung der Anforderung verwendet wird. 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, Workflow-StudioFügt der Anforderung die Abfrageparameter in derselben 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 derselben 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 HTTP-Methode Ist VERÖFFENTLICHEN , PLATZIEREN , PATCH , Oder LÖSCHEN .
Anforderungstext [Text]	Text der Anforderung im JSON- oder XML-Format. Die Flow-Ausführungsdetails zeigen den Antworttext entweder als Link zum eingebetteten Textanzeigeprogramm oder als sys_ID des Anhangdatensatzes an, der die Antwort enthält. Hinweis: Dieses Feld kann bearbeitet werden, wenn Sie auswählen Text Aus der Liste Anforderungstyp.
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 es mit JSONStreamingBuilder Und XMLStreamingBuilder APIs im Skriptschritt. Hinweis: Dieses Feld ist verfügbar, wenn Sie auswählen Binär Aus der Liste Anforderungstyp.
Name, Teiletyp, Wert	Inhalt einer mehrteiligen Anforderung. Geben Sie für jedes Teil seinen Namen, seinen Teiletyp und seinen Wert entweder einzeln in den Feldern oder mithilfe eines Inline-Skripts für alle Teile an. Sie können die mehrteiligen Werte angeben, indem Sie auf das Symbol zum Umschalten der Skripterstellung ( klicken ) Und das Skript wird bearbeitet. 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 aus Text Oder Datei . Text : Der Text für das Teil. Einmal Text Ist ausgewählt, können Sie den Inhaltstyp angeben. Datei : Die Datei für das Teil. Wenn Datei Ist ausgewählt, die Wert Muss die sys_ID des Anhangsdatensatzes sein, der den Inhalt enthält. Sie können diesen Datensatz in einem vorherigen Schritt suchen oder als Eingabewert definieren. Einmal Datei Ist ausgewählt, können Sie den Dateinamen und den Inhaltstyp angeben. Für Dateinamen Festlegen , Wählen Sie aus Aus Anhang Um den Dateinamen des angehängten Datensatzes zu verwenden, oder wählen Sie aus Aus Eingabe „Dateiname“ Um eigene einzugeben. Für Legen Sie Den Inhaltstyp Fest , Wählen Sie aus Aus Anhang Um den Inhaltstyp des angehängten Datensatzes zu verwenden, oder wählen Sie aus Aus Inhaltstyp-Eingabe Um eigene einzugeben. Wert : Der Inhalt des Teils. Bei Text ist der Wert der 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 auswählen Mehrteilig Aus der Liste Anforderungstyp.
Name, Wert	Inhalt einer URL-codierten Formular-Anforderung. 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 die URL-codierten Werte des Formulars Inline-Skripts angeben, indem Sie auf das Symbol zum Umschalten der Skripterstellung ( klicken ) Und das Skript wird bearbeitet. Weitere Informationen zum Inline-Skripting finden Sie unter Inline-Skripts. Hinweis: Dieses Feld ist verfügbar, wenn Sie auswählen Formular-URL-codiert Aus der Liste Anforderungstyp.
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 der Anlage	Name des Anhangs, der von der REST-Antwort erstellt wurde. Zum Beispiel: rest-response.txt. Hinweis: Dieses Feld ist verfügbar, wenn Als Anhang Speichern Ist ausgewählt.
Datensatz der Dateianlage	Zieldatensatz, dem der Anhang zugeordnet ist. Der Zieldatensatz muss eine Datenpille vom Typ sein Datensatz . Zum Beispiel einen spezifischen Incident-Datensatz. Sie können diesen Datensatz in einem vorherigen Schritt nachschlagen oder als Eingangsvariable definieren. Die Flow-Ausführungsdetails zeigen die sys_ID des zugehörigen Datensatzes an. Hinweis: Dieses Feld ist verfügbar, wenn Als Anhang Speichern Ist ausgewählt.

Auswertung des Aktionsfehlers

Wenn dieser Schritt fehlschlägt

Datentyp: Choice

Option, um den nächsten Schritt fortzusetzen oder zur Fehlerauswertung zu wechseln. Informationen zur Verwendung des Schrittstatuscodes oder der Meldung für eine anwenderdefinierte Aktionsfehlerbedingung finden Sie unter Aktionsfehlerauswertung.

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ößenbeschränkung mit glide.pf.rest.response_payload_max_sizeSystemeigenschaft. Diese Systemeigenschaft unterstützt einen Höchstwert von 10240 KB, wodurch die REST-Antwort auf 10 MB beschränkt wird.

Analyse 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 verwenden Skriptschritt Dient zum Analysieren der strukturierten Daten in Variablen, die an anderer Stelle in der Aktion oder in einem Flow verwendet werden können. Es gibt auch einen XML parser step Dient zum Analysieren eines Antworttextes im XML-Format.

Die allgemeine Strategie zum Abrufen von extrahierten Daten aus der Antwort lautet wie folgt.

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, die im Antworttext aus dem REST-Schritt übergeben werden soll.
   • Erstellen Sie Ausgabevariablen, um Daten aus der Antwort zurückzugeben.
3. Erstellen Sie ein Skript zum Analysieren und Zuordnen von Daten.
   • Verwenden Sie JSON.Parse() Methode in einem Skriptschritt zum Analysieren eines JSON-Antworttextes.
   • 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 „Analyse einer REST-Antwort“ in REST in IntegrationHub – Entwicklerschulung (Zürich) .