Datenstromaktionen und Paginierung

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 8 Minuten Lesedauer

    • Senden Sie REST-, SOAP- oder JDBC- Anforderungen von Flow Designer 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 einer Drittanbieter-HR-Website zu importieren. Die Aktion Datenstrom sendet eine REST-Anforderung an die Drittanbieter-Site und verarbeitet die Antwort, um Datensätze in der Benutzertabelle [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, der größer als 10 MB ist.
    • Senden Sie ggf. automatisch mehrere Anforderungen an APIs, die Ergebnisse paginieren.
    • Kann in IntegrationHub -Import und zum Erstellen einer Datenquelle verwendet werden.
    • Ermöglichen Sie Flow Designern die Verarbeitung großer Anforderungen ohne komplexe Codierung oder Konfiguration.
    • Ermöglichen Sie Flow Designern 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 Flow Designer 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 die Wiederverwendung von Datenstrom Aktionen in mehreren Flows, wobei dieselbe Datenquelle auf verschiedene Arten verwendet wird.

    Eine Datenstrom-Aktion wird ausgeführt

    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 Flow Designer 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 executeDataStreamAction()-Methode in der FlowAPI-Klasse starten. Weitere Informationen finden Sie unter FlowAPI.

    Aktionsgliederung

    Datenstrom -Aktionen folgen einer festgelegten Struktur. Befolgen Sie die Eingabeaufforderungen, um Schritte zur Aktionsgliederung hinzuzufügen und zu entfernen. Sie können einer Datenstrom -Aktion keine Schritte manuell 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.

    Aktionsvorverarbeitung

    Verwenden Sie die Kategorie „Aktionsvorverarbeitung“, um Verbindungs- und Anmeldeinformationsdetails abzurufen oder ein Vorverarbeitungsskript auszuführen.

    Wählen Sie Verbindungsinformationen abrufen aus, um Verbindungs- und Anmeldeinformationen abzurufen, die in Ihrer Aktion verwendet werden sollen. Wenn Sie diese Option auswählen, wird der Schritt „Verbindungsinformationen abrufen“ als erster Schritt in der Vorverarbeitung der Aktion hinzugefügt. Weitere Informationen finden Sie unter Get Connection Info step.

    Wählen Sie Vorverarbeitungsskript aktivieren aus, 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 Datenstrom Aktionskomponente, die entweder für die Instanz oder einen MID-Serverausgeführt wird.

    Anforderung

    Verwenden Sie die Anforderungskategorie, um zu konfigurieren, wie die Aktion API-Anforderungen sendet. Der Abschnitt „Anforderung“ wird einmal pro Ergebnisseite ausgeführt. Anforderungskomponenten bieten diese Konfigurationsoptionen.

    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 Ergebnisseite.

    Der Wert der reservierten, schreibgeschützten getNextPage -Variablen bestimmt, ob eine weitere Ergebnisseite 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 auf „false“ gesetzt wird.
    Dies ist eine optionale Anforderungskomponente, die nur für die 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 Ergebnisseite ein Skript aus. Verwenden Sie dieses Skript für die Datenvalidierung und -transformation beim Aufruf einer paginierten API. Generieren Sie beispielsweise eine JSON-Nutzlast 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 in der Instanz oder auf einem MID-Serverausgeführt wird.

    REST- oder SOAP-Schritt

    Senden Sie eine REST- oder SOAP-Anforderung an eine Drittpartei-API. 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 auf einem MID-Serverausgeführt wird.

    JDBC-Schritt

    Senden Sie eine JDBC-Anforderung an eine Drittpartei-API. Verwenden Sie ein Transformationsskript, um Daten zu formatieren und der Aktion Datenstrom einen zugeordneten Schritt hinzuzufügen. Weitere Informationen finden Sie unter JDBC-Schritt und JDBC-Testschritt. Alle Daten werden abgerufen und es ist keine Paginierung erforderlich.

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

    Analysieren 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 aus einem XML- oder JSON-Stream zu identifizieren und zu trennen, und verwenden Sie den Schritt „Skriptparser“, um jedes Element in ein komplexes Objekt umzuwandeln. Der Abschnitt „Analyse“ wird einmal pro Element im Stream ausgeführt. Sie können mit dem Objekt fd_data auf Ausgaben aus vorherigen Schritten in Ihrer Datenstromaktion zugreifen, mit Ausnahme von:
    • REST- oder SOAP-Schritt-Antworttext, Stream oder Fehlermeldungsausgaben
    • Splitter-Schrittausgaben

    Einen Stream von Benutzerdatensätzen aufteilen und analysieren.

    Weitere Informationen zu komplexen Daten finden Sie unter Komplexe Daten. Analysekomponenten bieten diese Konfigurationsoptionen.

    Schritt „Splitter“

    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 für die Instanz ausgeführt wird.

    Schritt „Skriptparser“

    Verwenden Sie 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 „outputs.state = 'SKIP'“ an beliebiger Stelle zum Skriptabschnitt des Skriptparser-Schritts hinzufügen.

    Dies ist eine obligatorische Analysekomponente, die nur für die Instanz ausgeführt wird.

    Abbildung : 3. Übersicht über Aktionen für REST- und SOAP-Datenströme
    Übersicht über die Aktion „REST- und SOAP-Datenstrom“.

    Skript in JDBC-Schritt umwandeln

    Die JDBC-Datenstromaktion erfordert keine Paginierung. Außerdem sind keine Splitter- und Parser-Schritte erforderlich.

    Der JDBC-Schritt generiert ein komplexes Objekt für jeden der abgerufenen Datensätze. 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 JDBC-Datenstromaktionen
    Ü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 „Skriptparser“ ordnet Elemente im Stream diesem Objekt zu, indem er das globale Objekt targetObject verwendet.

    Zur Laufzeit teilt und analysiert das System den Stream von Antwortdaten gemäß der Konfiguration Datenstrom. Jedes Element im Stream wird der komplexen Objektstruktur zugeordnet, die durch den Skriptparser-Schritt und die Objektausgabe definiert wird, was zu einer großen Reihe komplexer Objekte führt. Weitere Informationen zu komplexen Daten finden Sie unter Komplexe Daten.

    Datenstromausgaben im JDBC-Schritt

    Die Ausgabe von JDBC-Schritten ist ein komplexer Objektstream. Ganze Daten werden nur in 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 von einer Datenstrom -Aktion verarbeitete Element an. Wählen Sie eine Datensatznummer aus, um die 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 Datenstrom-Aktion.

    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.
    • Gesamtanzahlder 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 auf -1, um alle Seiten einzuschließen.

    Hinweis:
    Das Einbeziehen aller Seiten kann sich auf die Leistung auswirken und wird nicht empfohlen.

    Laufzeitdetails

    Ausführungsdetails im JDBC-Schritt

    Die Erstellung 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 MID Server-Eigenschaften.