Erstellen Sie eine Datenstromaktion

Freigeben Version: Washingtondc

Aktualisiert 1. Februar 2024

9 Minuten Lesedauer

Erstellen Sie eine wiederverwendbare Aktion, um einen Stream von Antwortdaten innerhalb eines Flow zu verarbeiten.

Vorbereitungen

Richten Sie eine Anwendung im geführten Anwendungsersteller ein, um Flow Designer -Inhalte zu speichern.
Deaktivieren Sie alle in Konflikt stehenden Business Rules oder Workflows, bevor Sie eine Aktion erstellen.
Erforderliche Rolle: action_designer oder admin

Warum und wann dieser Vorgang ausgeführt wird

Wenn Sie eine benutzerdefinierte Anwendung erstellen, die Ihren Flow Designer-Inhalt enthält, können Sie ihn mit dem Anwendungs-Repository oder dem ServiceNow Storebereitstellen.

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.

Prozedur

Navigieren zu Alle > Flow Designer > Designer.
Klicken Sie auf die Registerkarte Aktionen, und wählen Sie Datenstromaus.

Füllen Sie die Aktionseigenschaften aus und klicken Sie auf Senden.


Feld	Beschreibung
Name	Name der Aktion.
Ist zugreifbar von	Zugriff von allen Anwendungsbereichen oder nur innerhalb des angegebenen Anwendungsbereichs.
Kategorie	Definierte Kategorie innerhalb des Anwendungsbereichs für eine Aktion.
Beschreibung	Beschreibung der Aktion.
Schutz	Wählen Sie aus, ob die Aktion schreibgeschützt ist. Sie können nur dann einen Wert auswählen, wenn sich die Aktion in einem Anwendungsbereich befindet, den Sie besitzen. Der Standardwert ist "Kein".
Anwendung	Anwendungsbereich der Aktion.
In-Flow-Anmerkung	Text, der unter dem Aktionstitel in Flow Designer angezeigt wird, um Flow-Designer dabei zu unterstützen, was die Aktion tut, wenn sie in einem Flow verwendet wird.

Eine leere Datenstrom Aktion wird geöffnet.

Definieren Sie Aktionseingaben, um Daten für die Aktionsschritte verfügbar zu machen.
1. Wählen Sie + Eingabe erstellen und füllen Sie die Felder aus.
  Eingaben werden im rechten Fensterbereich als Data-Pills dargestellt.
Weitere Informationen zu Aktionseingaben finden Sie unter Aktionsdesigner Erstellen von benutzerdefinierten Aktionen.
Klicken Sie in der Gliederung Datenstrom auf Vorverarbeitung der Aktion, und konfigurieren Sie die gewünschten Optionen.
1. Wählen Sie Verbindungsinformationen abrufen aus, um den Schritt „Verbindungsinformationen abrufen“ als ersten Schritt in der Vorverarbeitung der Aktion hinzuzufügen.
  Mit dem Schritt „Verbindungsinformationen abrufen“ können Sie Verbindungs- und Anmeldeinformationen abrufen, die in Ihrer Aktion verwendet werden sollen. Weitere Informationen finden Sie unter Get Connection Info step.
2. Wählen Sie Vorverarbeitungsskript aktivieren, um ein Vorverarbeitungsskript, bevor die Aktion die erste API-Anforderung sendet. Validieren Sie beispielsweise Aktionseingaben, oder legen Sie Standardwerte fest. Die Vorverarbeitung wird einmal pro Aktion vor der ersten API-Anforderung ausgeführt.auszuführen.
  
  Durch Auswahl dieser Option wird der Aktion Datenstrom ein Skriptschritt hinzugefügt. Weitere Informationen finden Sie unter Script step.
  
  Wichtig:
  Datenstrom-Aktionen erfordern eine konstante Verbindung mit dem Antwortstrom. Sie unterstützen keine Vorverarbeitungsskripts, die die Aktion anhalten, um einen MID-Server aufzurufen, oder die Aktion anhalten, um auf eine Bedingung oder Dauer zu warten. Ein Vorverarbeitungsskript, das die Aktion aus irgendeinem Grund anhält, gibt eine Fehlermeldung zurück.
Klicken Sie in der Gliederung Datenstrom auf Anforderung, und konfigurieren Sie die gewünschten Optionen.
1. Wählen Sie im Feld Wie werden Daten abgerufen die Option REST-Schritt, SOAP-Schrittoder JDBC-Schritt aus, um den zugehörigen Schritt der Aktion Datenstrom hinzuzufügen.
  Weitere Informationen finden Sie unter REST-Schritt, SOAP-Schrittund JDBC-Schritt .
  
  Dieser Abschnitt kann entweder auf dem MID-Server oder der Instanz ausgeführt werden. Die Umgebung wird durch das Feld MID-Server verwenden im zugeordneten Verbindungsdatensatz [sys_connection] bestimmt.
  Hinweis:
  Wenn Sie den JDBC-Schritt verwenden, müssen Sie ihn testen. Nach erfolgreicher Ausführung können Sie das Ergebnis verwenden, um die Schrittausgabe und die Ausgabe der Datenstromaktion zu erstellen.
  
  Wenn Sie den REST-Schritt oder den SOAP-Schritt verwenden, müssen Sie die Ausgabe der Datenstromaktion manuell erstellen.
2. Wählen Sie Paginierung aktivieren, um 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. anzufordern. Diese Option fügt der Gliederung Datenstrom einen Schritt „Paginierungseinrichtung“ hinzu.
  
  Hinweis:
  Für einen JDBC-Schritt ist die Paginierung nicht anwendbar. Jede Seite kann bis zu 1 GB Daten abrufen, und eine Anforderung kann bis zu 8 GB Daten abrufen.
3. Wählen Sie Vor jeder Anforderung ein Skript ausführen aus, um beim Aufruf einer paginierten API vor jeder Anforderung für die nächste Seite ein Skript auszuführen.
  Schreiben Sie beispielsweise ein Skript, um variable Datentypen aus der ersten Antwort zu transformieren, bevor Sie eine Anforderung für die nächste Seite senden.
  
  Durch Auswahl dieser Option wird der Aktion Datenstrom ein Skriptschritt hinzugefügt. Weitere Informationen finden Sie unter Script step.
  
  Hinweis:
  Für einen JDBC-Schritt gilt dies nicht.
  
  Dieser Abschnitt kann entweder auf dem MID-Server oder in der Instanz ausgeführt werden. Die Umgebung wird vom Feld Erforderliche Laufzeit des Skriptschritts bestimmt.
  
  Wichtig:
  Vermeiden Sie es, die Ausführungsumgebung zwischen der Instanz und dem MID-Server mehrmals zu wechseln. Beispielsweise könnten Sie den Anforderungsskriptschritt für die Ausführung auf dem MID-Server konfigurieren, den REST-Schritt jedoch für die Instanz. In diesem Fall wechselt das System die Umgebung für jede Datenseite zwischen der Instanz und dem MID-Server, was die Leistung beeinträchtigen kann.
Wahlweise: Wenn die Paginierung aktiviert ist, konfigurieren Sie den Schritt „Paginierung einrichten“.
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.
1. Erstellen Sie Paginierungsvariablen.
  Wenn die API einer Drittpartei beispielsweise einen Grenzwertparameter in der Anforderung verwendet, erstellen Sie die Grenzwertvariable, und legen Sie den Anfangswert fest, um die Anzahl der Ergebnisse pro Seite zu begrenzen. Der Anfangswert wird nur in der ersten Anforderung verwendet. getNextPage ist eine reservierte, schreibgeschützte Variable. 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.
2. Definieren Sie im Feld Nächster Wert von, wie Paginierungsvariablen einen Wert für nachfolgende Anforderungen erhalten.
  Wählen Sie aus:
  - Skript: Schreiben Sie ein Paginierungsvariablenskript, um zu definieren, wie Variablen ausgefüllt werden. Paginierungsvariablen unterstützen nur den Datentyp Zeichenfolge. Zum Ausführen von mathematischen Operationen müssen Sie den Wert in eine ganze Zahl konvertieren, alle erforderlichen Vorgänge ausführen und sie dann wieder in eine Zeichenfolge konvertieren.
  - Antworttext: Verwenden Sie einen Wert in der Antwort aus der vorherigen Anforderung, um die Variable auszufüllen. Wenn die Antwort im JSON-Format vorliegt, legen Sie Wert extrahieren mit auf JSONPath-Ausdruck fest, und geben Sie den Pfad zum Wert im Feld Ausdruck an. Wenn die Antwort im XML-Format vorliegt, legen Sie Wert extrahieren mit auf XPath-Ausdruck fest, und geben Sie den Pfad zum Wert an.
In diesem Beispiel hat die Variable getNextPage den Wert „true“, bis die Variable nextOffset den Gesamtanzahlwert erreicht, der im API-Antwortheader zurückgegeben wird. 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. Dieses Beispiel enthält eine allgemeine Konfiguration für Grenzwert/Offset-Paginierung. Die APIs von Drittanbietern, mit denen Ihre Datenstrom -Aktion interagiert, verwenden möglicherweise ein Seitentoken oder eine andere Methode.

Im Paginierungsskript enthält das pageResponse- Objekt response_headers, response_bodyund einen Statuscode.

Wichtig:
Vermeiden Sie Endlosschleifen in Paginierungsanforderungen, indem Sie eine Bedingung erstellen, die die Variable getNextPage auf „false“ setzt. Brechen Sie Flows mit langer Ausführungszeit ab. Testen Sie Datenstrom-Aktionen immer, bevor Sie sie in der Produktion verwenden.
Klicken Sie in der Gliederung Datenstrom auf Analyse, und konfigurieren Sie die gewünschten Optionen.

Hinweis:
Für einen JDBC-Schritt gilt dies nicht.
1. Wählen Sie im Feld Wie werden Sie jeden Datensatz identifizierenJSON/XML-Splitter aus, um der Gliederung Datenstrom einen Splitter-Schritt hinzuzufügen.
2. Wählen Sie im Feld Wie werden die einzelnen Elemente in ein Objekt analysiert die Option Skriptparser aus, um der Gliederung Datenstrom einen Skriptparser-Schritt hinzuzufügen.
Konfigurieren Sie den Splitter-Schritt.

Dieser Schritt identifiziert 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.

Hinweis:
Für einen JDBC-Schritt gilt dies nicht.
1. Wählen Sie im Feld Quellformat das vom Anforderungsabschnitt zurückgegebene Format aus.
  - 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.
2. Definieren Sie im Feld Elementpfad den absoluten Pfad zu dem Element im Datenstrom, das Sie einem Objekt zuordnen möchten.
  
  JSON
  
  Identifizieren Sie den absoluten Pfad zu einem Array von Objekten als JSONPath-Ausdruck. Verwenden Sie beispielsweise $.result, um jedes Element in einem JSON- Ergebnis -Array in ein Ergebnisobjekt zu unterteilen.
  Hinweis:
  Wenn Sie ein Array im Stammknoten eines JSON-Datenstroms auswählen, zeigt das System den absoluten Pfad als $.* in Ausführungsdetails und Fehlermeldungen an.
  
  XML
  
  Identifizieren Sie den absoluten Pfad zu einem sich wiederholenden Datenobjekt als XPath-Ausdruck. Verwenden Sie beispielsweise /result, um jede Instanz eines Ergebnis -XML-Elements in ein Ergebnisobjekt zu trennen.
  Hinweis:
  Der Splitter-Schritt ignoriert XML-Namespaces
  Angenommen, der REST-Schritt gibt einen Stream von JSON-Daten zurück. Der Elementpfad $.response.result.companies gibt jedes Element im Unternehmen -Array zurück.
```
{
  "response": {
    "result": {
      "companies": [
        {
          "name": "company1"
        },
        {
          "name": "company2"
        },
        {
          "name": "company3"
        }
      ],
      "metadata": {
        "token": 1558666526
      }
    }
  }
} 
```
  Angenommen, der REST-Schritt gibt einen XML-Datenstrom zurück. Der Elementpfad /response/result/companies/company gibt jedes Unternehmenselement aus den XML-Daten zurück.
```
<response>
  <result>
    <companies>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <batch>10645C53D4BED73YQ</batch> 
    </companies>
    <metadata>
      <timestamp>1558666526</timestamp>
    </metadata>
  </result>
</response>
```
Verwenden Sie im Schritt „Skriptparser“ JavaScript und ServiceNow -APIs, um Elemente im Antwortstream einer komplexen Objektausgabe zuzuordnen, die durch das globale 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.

Hinweis:
Für einen JDBC-Schritt gilt dies nicht.
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.
Ein Beispielskript, das eine JSON-Antwort analysiert.
```
(function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.id=record.number;
    outputs.targetObject.name=record.short_description;
})(inputs, outputs)
```
Ein Beispielskript, das eine XML-Antwort analysiert.
```
(function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.id = xmlDoc.getNodeText("/result/number");
    outputs.targetObject.name = xmlDoc.getNodeText("/result/short_description");
})(inputs, outputs)
```
Wahlweise: Wenn Sie den JDBC-Schritt ausgewählt haben, klicken Sie auf Umwandeln.
Klicken Sie nach dem erfolgreichen Testen des JDBC-Schritts auf Ergebnis verwenden, um die Schrittausgabe und die Ausgabe der Datenstromaktion zu erstellen. Sie können dieses Ergebnis verwenden oder es mit dem Transformationsskript anpassen.
1. Aktivieren Sie das Kontrollkästchen Transformationsskript aktivieren, um die Standardausgabe des Datenstroms umzuwandeln und anzupassen.
Erstellen Sie eine komplexe Objektausgabe.

Hinweis:
Für einen JDBC-Schritt gilt dies nicht.
1. Wählen Sie Ausgaben in der Aktionsgliederung aus, und klicken Sie auf +, um eine Ausgabe zu erstellen.
2. Aktualisieren Sie das Feld Bezeichnung, um das Objekt darzustellen.
  Wenn die Aktion beispielsweise einen Stream von Unternehmensdatensätzen analysiert, fügen Sie die Bezeichnung Unternehmen hinzu.
3. Aktualisieren Sie das Feld Typ auf Objekt.
  Dies ist die komplexe Objektausgabe, die durch das globale Objekt targetObject im Schritt „Skriptparser“ dargestellt wird.
4. Fügen Sie dem komplexen Objekt über das Symbol + untergeordnete Felder hinzu.
5. Machen Sie den Namen jedes untergeordneten Felds benutzerfreundlicher, damit Sie im Skript sinnvoll darauf verweisen können.
  
  Der Wert im Feld Name ist der interne Name, der im Schritt „Skriptparser“ verwendet wird. Um beispielsweise auf die Ausgabe „Stadt“ im Schritt „Skriptparser“ zu verweisen, verwenden Sie „ outputs.targetObject.city“.
  
  Warnung:
  Nach dem Speichern der Aktion Datenstrom können Sie keine Werte im Feld Name ändern.
Klicken Sie auf Speichern.
Aktionsdesigner speichert einen Entwurf der Aktion.

Nächste Maßnahme

Testen Sie eine Datenstrom -Aktion.