Datenstromaktionen und -paginierung

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 8 Minuten Lesedauer

    • Senden Sie REST-, SOAP- oder JDBC- Anforderungen von Workflow-Studio an APIs, die einen Stream von Antwortdaten größer als 10 MB oder paginierte Ergebnisse zurückgeben. Parsen Sie Streamdaten in eine Reihe komplexer Objektausgaben, und verwenden Sie die Datenpillen in anderen Aktionen in einem Flow.

    Erstellen Sie beispielsweise eine Datenstrom -Aktion, um eine große Menge von Mitarbeiterdaten von der HR-Website einer Drittpartei zu importieren. Die Aktion Datenstrom sendet eine REST-Anforderung an die Drittpartei-Site und verarbeitet die Antwort, um Datensätze in der Tabelle „Benutzer“ [sys_user] auszufüllen.
    Hinweis:
    Datenstromaktionen erfordern ein IntegrationHub-Abonnement. Weitere Informationen finden Sie unter Gesetzliche Zeitpläne – IntegrationHub Übersicht.

    Vorteile

    Datenstrom -Aktionen bieten diese Vorteile.

    • Analysieren und formatieren Sie einen Stream mit Antwortdaten, die größer als 10 MB sind.
    • Senden Sie automatisch mehrere Anforderungen an APIs, die ggf. die Ergebnisse paginieren.
    • Kann in IntegrationHub Import und zum Erstellen einer Datenquelleverwendet werden.
    • Ermöglichen Sie Flow Designern, große Anforderungen ohne komplexe Codierung oder Konfiguration zu verarbeiten.
    • Aktivieren Sie Flow Designer für jedes Objekt in einem Datenstrom mit Flow-Logik vom Typ Für alle verarbeiten. Beispielsweise können Sie eine Datenstrom-Aktion erstellen, die Dokumentdaten von einer Drittanbieterwebsite importiert. Wenn Sie die Aktion einem Flow hinzufügen, fügt Workflow-Studio die Aktion automatisch einem Flow-Logikblock vom Typ Für alle hinzu, sodass Flow-Designer ganz einfach einen Datensatz in ServiceNow für jedes Objekt im Datenstrom erstellen können. Siehe Verwenden Sie eine Datenstrom -Aktion in einem Flow.
    • Ermöglichen Sie Flow Designern, Datenstrom -Aktionen in mehreren Flows wiederzuverwenden und dabei dieselbe Datenquelle auf verschiedene Arten zu verwenden.

    Ausführen einer Datenstromaktion

    Es gibt zwei Möglichkeiten, eine Datenstrom -Aktion auszuführen.

    Aus einem Flow
    Sie können jedes Objekt in einem Datenstrom mit Flow-Logik vom Typ Für alle verarbeiten. Beispielsweise können Sie eine Datenstrom-Aktion erstellen, die Dokumentdaten von einer Drittanbieterwebsite importiert. Wenn Sie die Aktion einem Flow hinzufügen, fügt Workflow-Studio die Aktion automatisch einem Flow-Logikblock vom Typ Für alle hinzu, sodass Flow-Designer ganz einfach einen Datensatz in ServiceNow für jedes Objekt im Datenstrom erstellen können. Siehe Verwenden Sie eine Datenstrom -Aktion in einem Flow.
    Aus einem Skript
    Sie können einen Datenstrom mit der Methode executeDataStreamAction() in der Klasse FlowAPI starten. Weitere Informationen finden Sie unter FlowAPI.

    Aktionsgliederung

    Datenstrom -Aktionen folgen einer festgelegten Struktur. Befolgen Sie die Eingabeaufforderungen, um der Aktionsgliederung Schritte hinzuzufügen und sie zu entfernen. Sie können einer Aktion Datenstrom nicht manuell Schritte hinzufügen.

    Abbildung : 1. REST- und SOAP-Datenstromaktionen
    REST- und SOAP-Datenstromaktion.
    Abbildung : 2. JDBC-Datenstromaktion
    JDBC-Datenstromaktion
    Hinweis:
    Durch das Löschen einer Option auf einer Konfigurationsseite wird der Schritt aus der Gliederung Datenstrom entfernt, und alle dem Schritt zugeordneten Daten werden gelöscht.

    Fehlerbewertung der Aktion

    Verwenden Sie die Fehlerauswertung, um Schrittfehler zu erfassen und das Fehlerverhalten jedes Schritts anzugeben, den Sie einer Datenstromaktion hinzufügen. Sie können auch eigene Fehlerbedingungen erstellen, indem Sie angeben, wann eine Aktion einen Fehlerstatus zurückgibt, sowie die Statuscodes und Nachrichten, die zurückgegeben werden.

    Vorverarbeitung der Aktion

    Verwenden Sie die Kategorie „Aktionsvorverarbeitung“, um Details zu Verbindungen und Anmeldeinformationen abzurufen oder ein Vorverarbeitungsskript auszuführen.

    Wählen Sie Verbindungsinformationen abrufen aus, um Verbindungs- und Anmeldeinformationsdetails abzurufen und in Ihrer Aktion zu verwenden. Wenn Sie diese Option auswählen, wird der Schritt Verbindungsinformationen abrufen als erster Schritt in der Aktionsvorverarbeitung hinzugefügt. Weitere Informationen finden Sie unter Get Connection Info step.

    Wählen Sie Vorverarbeitungsskript aktivieren, um ein Vorverarbeitungsskript auszuführen, bevor die Aktion die erste API-Anforderung sendet. Validieren Sie beispielsweise Aktionseingaben, oder legen Sie Standardwerte fest. Durch Auswahl dieser Option wird der Aktion Datenstrom ein Skriptschritt hinzugefügt. Weitere Informationen finden Sie unter Script step.

    Die Vorverarbeitung wird einmal pro Aktion vor der ersten API-Anforderung ausgeführt.

    Dies ist eine optionale Komponente der Aktion Datenstrom, die entweder auf der -Instanz oder einem MID-Serverausgeführt wird.

    Anforderung

    Verwenden Sie die Kategorie Anforderung, um zu konfigurieren, wie die Aktion API-Anforderungen sendet. Der Abschnitt „Anforderung“ wird einmal pro Seite der Ergebnisse ausgeführt. Anforderungskomponenten stellen die folgenden Konfigurationsoptionen bereit.

    Schritt „Paginierungssetup“

    Anforderung Ergebnisse in Stapeln. Sobald eine Seite mit Daten verarbeitet wurde, führt die Aktion Datenstrom den Anforderungsabschnitt erneut aus, um den nächsten Ergebnissatz zurückzugeben. Verwenden Sie den Setup-Schritt für die Paginierung, um die für die API erforderlichen Paginierungsoptionen einzurichten. Konfigurieren Sie den Schritt „Paginierungseinrichtung“ manuell, oder wählen Sie eine vorgefertigte Vorlage aus, um allgemeine Konfigurationen anzuwenden. Wenden Sie beispielsweise die Vorlage Grenzwert/Offset an, um die Anzahl der pro Seite zurückgegebenen Elemente (Grenze) und die Startnummer für das erste Element (Offset) anzugeben. Aktualisieren Sie nach dem Anwenden einer Vorlage die Werte, um sicherzustellen, dass die Konfiguration den API-Anforderungen entspricht.

    Hinweis:
    Für Lizenzierungszwecke zählt jede Anforderung als eine Transaktion, einschließlich jeder Anforderung für die nächste Seite mit Ergebnissen.

    Der Wert der reservierten, schreibgeschützten getNextPage- Variablen bestimmt, ob eine andere Seite mit Ergebnissen angefordert werden soll. Solange die getNextPage-Variable auf „true“ gesetzt ist und die vorherige Seite Daten enthält, sendet die Aktion weiterhin Anforderungen für die nächste Seite.

    Hinweis:
    Sie müssen den Wert im Skript explizit auf „true“ festlegen, da er sonst standardmäßig „false“ lautet.
    Dies ist eine optionale Anforderungskomponente, die nur in der -Instanz ausgeführt wird.
    Hinweis:
    Paginierung gilt nicht für den JDBC-Schritt.
    Skriptschritt

    Führen Sie vor jeder Anforderung für die nächste Seite mit Ergebnissen ein Skript aus. Verwenden Sie dieses Skript für die Datenvalidierung und -transformation beim Aufrufen einer paginierten API. Generieren Sie beispielsweise eine JSON-Payload für die nächste Seitenanforderung. Durch Auswahl dieser Option wird der Aktion Datenstrom ein Skriptschritt hinzugefügt. Weitere Informationen finden Sie unter Script step.

    Dies ist eine optionale Anforderungskomponente, die entweder auf der -Instanz oder einem MID-Serverausgeführt wird.

    REST- oder SOAP-Schritt

    Senden Sie eine REST- oder SOAP-Anforderung an die API einer Drittpartei. Wählen Sie ein Datenformat aus, um der Aktion Datenstrom einen zugeordneten Schritt hinzuzufügen. Weitere Informationen finden Sie unter REST-Schritt und SOAP-Schritt.

    Dies ist eine obligatorische Anforderungskomponente, die entweder auf der -Instanz oder einem MID-Serverausgeführt wird.

    JDBC-Schritt

    Senden Sie eine JDBC-Anforderung an die API einer Drittpartei. Verwenden Sie das Transformationsskript, um Daten zu formatieren und der Aktion Datenstrom einen zugehörigen Schritt hinzuzufügen. Weitere Informationen finden Sie unter JDBC-Schritt und JDBC-Testschritt. Alle Daten werden abgerufen, und eine Paginierung ist nicht erforderlich.

    Dies ist eine obligatorische Anforderungskomponente, die auf einem MID-Serverausgeführt wird.

    Analyse in REST- und SOAP-Schritten

    Verwenden Sie die Kategorie Analyse, um zu konfigurieren, wie die Aktion Datenstromelemente in komplexe Datenobjekte unterteilt. Verwenden Sie den Schritt Splitter, um Elemente in einem XML- oder JSON-Stream zu identifizieren und zu trennen, und verwenden Sie den Schritt Skript-Parser, um jedes Element in ein komplexes Objekt umzuwandeln. Der Abschnitt Analyse wird einmal pro Element im Stream ausgeführt. Mit dem Objekt „fd_data“ können Sie in Ihrer Datenstromaktion auf Ausgaben aus vorherigen Schritten zugreifen, außer:
    • REST- oder SOAP-Schritt-Antworttext, Stream oder Fehlermeldungsausgaben
    • Splitter-Schrittausgaben

    Aufteilen und Analysieren eines Streams von Benutzerdatensätzen.

    Weitere Informationen zu komplexen Daten finden Sie unter Komplexe Daten. Analysekomponenten stellen die folgenden Konfigurationsoptionen bereit.

    Splitter-Schritt

    Identifizieren den übergeordneten Knoten im Antwortstream, der einem komplexen Objekt zugeordnet werden soll. Identifizieren Sie beispielsweise ein Benutzerelement in einer XML-Nutzlast, um für jeden Benutzer im Antwortstream ein komplexes Objekt zu erstellen.

    Wählen Sie einen Splitter-Typ aus, um wiederholte Elemente in einem XML- oder JSON-Datenstrom zu identifizieren und zu trennen.

    • JSON: Identifiziert Objekte in einem Stream von JSON-Daten. Verwenden Sie einen JSONPath-Ausdruck, um ein JSON-Array zu identifizieren, das wiederholte Daten enthält.
    • XML: Identifiziert Objekte in einem Stream von XML-Daten. Verwenden Sie einen XPath-Ausdruck, um ein XML-Element zu identifizieren, das wiederholte Daten enthält.

    Dies ist eine obligatorische Analysekomponente, die nur in der Instanz ausgeführt wird.

    Schritt „Skriptparser“

    Verwenden von JavaScript und ServiceNow-APIs zum Zuordnen von Elementen im Antwortstrom zu einer komplexen Objektausgabe, die vom globalen Objekt targetObject dargestellt wird. Ordnen Sie beispielsweise Incident-Datensatzelemente, die im Splitter-Schritt identifiziert wurden, einem komplexen Objekt zu, das Incident-Felder enthält. Wenn der Datenstrom gleichgeordnete Elemente zu dem im Splitter-Schritt identifizierten Element enthält, die keinem komplexen Objekt zugeordnet werden sollen, schließen Sie Bedingungen ein, um diese Elemente auszuschließen. Sie können Elemente im Stream überspringen, indem Sie im Skriptabschnitt des Skript-Parser-Schritts wo immer dies erforderlich ist, „outputs.state = 'SKIP'“ hinzufügen.

    Dies ist eine obligatorische Analysekomponente, die nur in der Instanz ausgeführt wird.

    Abbildung : 3. Übersicht über die Aktionen „REST- und SOAP-Datenstrom“.
    Übersicht über die Aktion „REST- und SOAP-Datenstrom“.

    Skript in JDBC-Schritt umwandeln

    Für die JDBC-Datenstromaktion ist keine Paginierung erforderlich. Außerdem sind keine Splitter- und Parser-Schritte erforderlich.

    Der JDBC-Schritt generiert für jeden abgerufenen Datensatz ein komplexes Objekt. Daher sind die Vorverarbeitung der Aktion und das Transformationsskript in der JDBC-Datenstromaktion optional. Bei Verwendung des Transformationsskripts muss der Aktionsdesigner den internen Namen der Tabellenspalten im Transformationsskript angeben.
    Abbildung : 4. Übersicht über die JDBC-Datenstromaktion
    Übersicht über die JDBC-Datenstromaktion.

    Datenstromausgaben in SOAP- und REST-Schritten

    Beim Entwerfen einer Datenstrom -Aktion müssen Sie eine einzelne Ausgabe vom Typ „Objekt“ oder „Dynamisches Objekt“ erstellen. Der Schritt „Skript-Parser“ ordnet diesem Objekt mithilfe des globalen Objekts targetObject Elemente im Stream zu.

    Zur Laufzeit teilt und analysiert das System den Stream der Antwortdaten entsprechend der Konfiguration Datenstrom. Jedes Element im Stream ist der komplexen Objektstruktur zugeordnet, die durch den Skript-Parser-Schritt und die Objektausgabe definiert wurde. Dies führt zu einer großen Reihe von komplexen Objekten. Weitere Informationen zu komplexen Daten finden Sie unter Komplexe Daten.

    Datenstromausgaben in JDBC-Schritt

    Die Ausgabe von JDBC-Schritten ist ein komplexer Objektstrom. Ganze Daten werden in nur einer Anforderung abgerufen.
    Hinweis:
    • Mit der JDBC-Datenstromaktion können Sie nur Daten abrufen und keine Datensätze aktualisieren oder löschen.
    • Die Felder „Maximale Zeile“ und „Maximale Nutzlastgröße (KB)“, die im JDBC-Schritt verfügbar sind, sind in der JDBC-Datenstromaktion nicht verfügbar.

    Ausführungsdetails in REST- und SOAP-Schritten

    Zeigen Sie die Konfigurations- und Laufzeitergebnisse für jedes -Element an, das von einer Datenstrom -Aktion verarbeitet wurde. Wählen Sie eine Datensatznummer aus, um die zugehörigen Konfigurations- und Laufzeitdetails anzuzeigen. Standardmäßig enthalten die Ausführungsdetails Anforderungen für die letzten 1000 Elemente. Um die Anzahl der Elemente in den Ausführungsdetails zu ändern, aktualisieren Sie die Systemeigenschaft com.snc.process_flow.reporting.datastream.item.lastn.

    Ausführungsdetails für eine Datenstromaktion.

    Zusammenfassung des Datenstroms

    Zeigen Sie eine Übersicht über die Ausführung an, die diese Informationen enthält.

    • Seitenanzahl: Anzahl der Seiten, die von einer paginierten API zurückgegeben werden.
    • Gesamtanzahl der Elemente: Anzahl der Elemente im Antwortstream, die komplexen Objektausgaben zugeordnet sind.
    • Fehleranzahl: Anzahl der aufgetretenen Fehler.
    Seitendetails

    Zeigen Sie Laufzeitdaten für jeden Schritt in der Aktion Datenstrom an. Wählen Sie eine Seite aus, um Laufzeitdetails für jede Anforderung an eine paginierte API anzuzeigen. Standardmäßig enthalten die Ausführungsdetails Anforderungen für die letzten fünf Seiten. Um die Anzahl der Anforderungen in den Ausführungsdetails zu ändern, aktualisieren Sie die Systemeigenschaft com.snc.process_flow.page.reporting.lastn. Legen Sie den Wert auf 0 fest, um Seiten aus den Ausführungsdetails zu entfernen, und -1, um alle Seiten einzubeziehen.

    Hinweis:
    Das Einschließen aller Seiten kann die Leistung beeinträchtigen und wird nicht empfohlen.

    Laufzeitdetails

    Ausführungsdetails im JDBC-Schritt

    Die Konstruktion des komplexen Ausgabeobjektschemas ist für die JDBC-Datenstromaktion nicht erforderlich. Sie können die Abfrage testen und das Abfrageergebnis anzeigen. Weitere Informationen finden Sie unter JDBC-Testschritt. Konfigurieren Sie die MID-Server -Eigenschaften mid.jdbc.datastream.max.record.size und mid.jdbc.datastream.fail.when.attachement.limit.exceeded, um Daten gemäß Ihren Anforderungen abzurufen. Weitere Informationen finden Sie unter Eigenschaften des MID-Servers.