REST-Schritt

Senden Sie eine ausgehende REST-Webserviceanforderung 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-StudioAktionsschritt. Anwender mit der Rolle „action_Designer“ können eine anwenderdefinierte Aktion mit einem oder mehreren Aktionsschritten erstellen.

Felder

Feld	Beschreibung
Verbindung	Typ der zu verwendenden Verbindung. Definieren Sie Die Verbindung Inline : Definieren Sie Verbindungsinformationen im Aktionsschritt. Verwenden Sie Den Verbindungsalias : Definieren Sie Verbindungsinformationen mithilfe der Tabelle „Verbindungsalias“. Durch die Verwendung eines Alias müssen bei der Verwendung einer Aktion in mehreren Umgebungen nicht mehrere Anmeldeinformations- und Verbindungsinformationsprofile konfiguriert werden. Wenn sich die Verbindungsinformationen ändern, müssen Sie Ihre anwenderdefinierte Aktion nicht aktualisieren. 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. Durch die Verwendung eines Alias müssen bei der Verwendung einer Aktion in mehreren Umgebungen nicht mehrere Anmeldeinformations- und Verbindungsinformationsprofile konfiguriert werden. 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 Aliasse . Der Anmeldeinformationswert wird als Passwortdatenpille (zweifach verschlüsselt) im Datenbereich 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. Durch die Verwendung eines Alias müssen bei der Verwendung einer Aktion in mehreren Umgebungen nicht mehrere Anmeldeinformationen konfiguriert werden. Wenn sich die Anmeldeinformationsinformationen ändern, müssen Sie Ihre anwenderdefinierte Aktion nicht aktualisieren. Weitere Informationen zu Verbindungen und Anmeldeinformationen finden Sie unter Anmeldeinformationen, Verbindungen und Aliasse . Der Anmeldeinformationswert wird als Passwortdatenpille (zweifach verschlüsselt) im Datenbereich 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-ServerZum 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 Parameterlaufzeitdaten, die über einen MID-Server gesendet werden, auf dieselbe Weise 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 eigene eingeben. Wenn Definieren Sie Die Verbindung Inline Ist ausgewählt, 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 standardmäßigen Zeitüberschreitungswert für die Systemverbindung 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 des spezifischen MID-Servers oder MID-Clusters. MID-Server automatisch auswählen : Wählt den MID-Server automatisch aus. Bestimmter MID-Server : Verwendet den von Ihnen ausgewählten MID-Server. Bestimmter MID-Cluster : Verwendet den von Ihnen ausgewählten MID-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-ServerMuss unterstützen, um für die Auswahl berechtigt zu sein. Das System führt den Aktionsschritt von einem aus aus MID-ServerDas 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-ServerMuss unterstützen, um für die Auswahl berechtigt zu sein. Das System führt den Aktionsschritt von einem aus aus MID-ServerDas 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 Bestimmter 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 füllen Sie das REST-Schritt-Formular aus. Weitere Informationen finden Sie unter OpenAPI-Unterstützung im REST-Schritt . Aus REST-Nachricht : Importieren Sie eine 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 die 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 zum Verarbeiten der Anforderung verwendet wird. ABRUFEN 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 alle in der Spezifikation vorhandenen Parameter und Header dem REST-Schritt 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 dem REST-Schritt beide Header hinzu. Entfernen Sie einen der Header je nach Inhaltstyp, den Sie in der Antwort erhalten möchten.
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 alle in der Spezifikation vorhandenen Parameter und Header dem REST-Schritt 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 dem REST-Schritt beide Header hinzu. Entfernen Sie einen der Header je nach Inhaltstyp, den Sie in der Antwort erhalten möchten.
Anforderungstyp	Format der Anforderung. Optionen umfassen. Text : Eine Anforderung in JSON, XML oder einem anderen Textformat. Binär : Eine Anforderung in einem binären Dateiformat. Mehrteilig : Eine Anforderung, die aus mehreren Inhaltstypen besteht. Formular-URL-codiert : Eine Anforderung in einer URL-codierten Abfrage. Hinweis: Dieses Feld kann bearbeitet werden, wenn HTTP-Methode Ist VERÖFFENTLICHEN , PLATZIEREN , PATCH , Oder LÖSCHEN .
Anforderungstext [Text]	Textkörper 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, Teiletyp und Wert an, indem Sie entweder die Felder einzeln verwenden oder ein Inline-Skript für alle Teile verwenden. Sie können die mehrteiligen Werte angeben, indem Sie auf das Symbol „Skripting umschalten“ ( ) Und das Skript wird bearbeitet. Weitere Informationen zum Inline-Skripting finden Sie unter Inline scripts. Name : Der Name des Teils. Es kann eine beliebige gültige Zeichenfolge sein. Teiletyp : Der Typ des Teils. Wählen Sie eine der beiden 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. Wann Datei Ist ausgewählt, 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 , Auswählen 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 , Auswählen Aus Anhang Um den Inhaltstyp des angehängten Datensatzes zu verwenden, oder wählen Sie aus Von Inhaltstyp-Eingabe Um eigene einzugeben. Wert : Der Inhalt des Teils. Für Text ist der Wert der Textinhalt. Für eine 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 Formularwerte Inline-Skript angeben, indem Sie auf das Symbol „Skripting umschalten“ ( klicken ) Und das Skript wird bearbeitet. Weitere Informationen zum Inline-Skripting finden Sie unter Inline scripts. 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 standardmäßigen Wiederholungsrichtlinie. Dieses Kontrollkästchen gilt nicht, wenn Definieren Sie Die Verbindung Inline Ist aus der Verbindungsliste ausgewählt.
Wiederholungsrichtlinie	Standardmäßige Wiederholungsrichtlinie, die zugeordnet ist Verbindungsalias . Wenn Überschreiben Sie die Standardrichtlinie für den Alias Ist ausgewählt, können Sie die standardmäßige Wiederholungsrichtlinie überschreiben und eine andere vorhandene Wiederholungsrichtlinie basierend auf Ihren Anforderungen 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. Beispiel: rest-response.txt . Hinweis: Dieses Feld ist verfügbar, wenn Speichern Sie Als Anhang Ist ausgewählt.
Datensatz der Anhangdatei	Zieldatensatz, dem der Anhang zugeordnet ist. Der Zieldatensatz muss eine Datenpille vom Typ sein Datensatz . Beispiel: Ein bestimmter Incident-Datensatz. Sie können diesen Datensatz in einem vorherigen Schritt suchen oder als Eingabevariable definieren. Die Flow-Ausführungsdetails zeigen die sys_ID des zugeordneten Datensatzes an. Hinweis: Dieses Feld ist verfügbar, wenn Speichern Sie Als Anhang 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 Action error evaluation.

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

Standardmäßig begrenzt das System die Größe von REST-Antworten, die nicht als Anhänge gespeichert werden, auf 5 MB. Direkte REST-Antworten, die diesen Grenzwert überschreiten, generieren 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 Script stepDient zum Analysieren der strukturierten Daten in Variablen, die an anderer Stelle in der Aktion oder in einem Flow verwendet werden sollen. Es gibt auch einen XML-Parser-SchrittDient zum Analysieren eines Antworttextes im XML-Format.

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, 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 zum Analysieren einer REST-Antwort in REST in IntegrationHub-Entwicklerschulung .

• Importieren Sie eine REST-Nachricht in einen REST-Schritt
  Übertragen Sie Daten aus einer vorhandenen Plattform-REST-Nachricht in einen REST-Schritt.