Transformieren von Daten mit JSONata In-Step-Funktionen

Damit JSONata erhalten Sie eine leistungsstarke Open-Source-Abfrage- und Ausdruckssprache, mit der Sie Daten in Ihren Workflows auswählen und transformieren können. Eine kurze Einführung und eine vollständige JSONata Referenz finden Sie in der JSONata.org-Dokumentation.

Das folgende Video beschreibt Variablen und JSONata In-Step-Funktionen anhand eines DynamoDB-Beispiels:

Sie müssen sich anmelden, um die JSONata Abfrage- und Transformationssprache für bestehende Workflows zu verwenden. Wenn Sie einen Workflow in der Konsole erstellen, empfehlen wir, sich JSONata für den State Machine der obersten Ebene zu entscheiden. QueryLanguage Für bestehende oder neue Workflows, die verwenden JSONPath, bietet die Konsole eine Option, in die einzelne Status konvertiert JSONata werden können.

Nach der Auswahl JSONata werden Ihre Workflow-Felder von fünf JSONPath Feldern (InputPath,Parameters, ResultSelectorResultPath, undOutputPath) auf nur zwei Felder reduziert: Arguments undOutput. Außerdem werden Sie keine Schlüsselnamen für JSON-Objekte verwenden.$.

Wenn Sie mit Step Functions noch nicht vertraut sind, müssen Sie nur wissen, dass JSONata Ausdrücke die folgende Syntax verwenden:

JSONata Syntax: "{% <JSONata expression> %}"

Die folgenden Codebeispiele zeigen eine Konvertierung von JSONPath nach JSONata:

# Original sample using JSONPath
{
  "QueryLanguage": "JSONPath", // Set explicitly; could be set and inherited from top-level
  "Type": "Task",
  ...
  "Parameters": {
    "static": "Hello",
    "title.$": "$.title",
    "name.$": "$customerName",  // With $customerName declared as a variable
    "not-evaluated": "$customerName"
  }
}

# Sample after conversion to JSONata
{
  "QueryLanguage": "JSONata", // Set explicitly; could be set and inherited from top-level
  "Type": "Task",
  ...
  "Arguments": { // JSONata states do not have Parameters
    "static": "Hello",
    "title": "{% $states.input.title %}", 
    "name": "{% $customerName %}",   // With $customerName declared as a variable
    "not-evaluated": "$customerName"
  }
}

Bei gegebener Eingabe { "title" : "Doctor" } und customerName zugewiesener "María" Variablen erzeugen beide Zustandsmaschinen das folgende JSON-Ergebnis:

{
  "static": "Hello",
  "title": "Doctor",
  "name": "María",
  "not-evaluated": "$customerName"
 }

Im nächsten Diagramm sehen Sie eine grafische Darstellung, die zeigt, wie die Konvertierung JSONPath (links) nach JSONata (rechts) die Komplexität der Schritte in Ihren Zustandsmaschinen reduziert:

Sie können (optional) Daten aus der Statuseingabe auswählen und in Argumente umwandeln, um sie an Ihre integrierte Aktion zu senden. Mit JSONata können Sie dann (optional) die Ergebnisse der Aktion für die Zuweisung zu Variablen und für die Statusausgabe auswählen und transformieren.

Hinweis: Die Schritte Zuweisen und Ausgeben erfolgen parallel. Wenn Sie sich dafür entscheiden, Daten während der Variablenzuweisung zu transformieren, sind diese transformierten Daten im Ausgabeschritt nicht verfügbar. Sie müssen die JSONata Transformation im Ausgabeschritt erneut anwenden.

QueryLanguage Feld

In Ihren Workflow-ASL-Definitionen gibt es ein QueryLanguage Feld auf der obersten Ebene einer Zustandsmaschinen-Definition und in einzelnen Status. Indem Sie einzelne QueryLanguage Status festlegen, können Sie schrittweise eine bestehende Zustandsmaschine übernehmen JSONata , anstatt die Zustandsmaschine auf einmal zu aktualisieren.

Das QueryLanguage Feld kann auf "JSONPath" oder "JSONata" gesetzt werden. Wenn das QueryLanguage Feld der obersten Ebene weggelassen wird, ist es standardmäßig auf. "JSONPath" Wenn ein Bundesstaat ein QueryLanguage Feld auf Bundesstaatsebene enthält, verwendet Step Functions die angegebene Abfragesprache für diesen Status. Wenn der Bundesstaat kein Feld enthält, wird die QueryLanguage im Feld der obersten Ebene QueryLanguage angegebene Abfragesprache verwendet.

JSONata Ausdrücke in JSON-Zeichenketten schreiben

Wenn eine Zeichenfolge im Wert eines ASL-Felds, eines JSON-Objektfeldes oder eines JSON-Array-Elements von {% %} Zeichen umgeben ist, wird diese Zeichenfolge als JSONata ausgewertet. Beachten Sie, dass die Zeichenfolge {% ohne führende Leerzeichen beginnen und ohne abschließende Leerzeichen %} enden muss. Ein unsachgemäßes Öffnen oder Schließen des Ausdrucks führt zu einem Validierungsfehler.

Hier einige Beispiele:

• "TimeoutSeconds" : "{% $timeout %}"

• "Arguments" : {"field1" : "{% $name %}"}in einem Bundesstaat Task

• "Items": [1, "{% $two %}", 3]in einem Map Staat

Nicht alle ASL-Felder werden akzeptiert JSONata. Beispielsweise muss das Type Feld jedes Bundesstaates auf eine konstante Zeichenfolge festgelegt werden. In ähnlicher Weise muss das Resource Feld des Task Bundesstaates eine konstante Zeichenfolge sein. Das Map Items Statusfeld akzeptiert ein JSON-Array oder einen JSONata Ausdruck, der zu einem Array ausgewertet werden muss.

Reservierte Variable: $states

Step Functions definiert eine einzelne reservierte Variable namens $states. In JSONata Staaten werden die folgenden Strukturen $states zur Verwendung in JSONata Ausdrücken zugewiesen:

# Reserved $states variable in JSONata states
$states = {
  "input":       // Original input to the state
  "result":      // API or sub-workflow's result (if successful)
  "errorOutput": // Error Output (only available in a Catch)
  "context":     // Context object
}

Bei der Zustandseingabe weist Step Functions die Statuseingabe zu $states.input. Der Wert von $states.input kann in allen Feldern verwendet werden, die JSONata Ausdrücke akzeptieren. $states.inputbezieht sich immer auf die ursprüngliche Statuseingabe.

Für TaskParallel, und gibt Map an:

• $states.resultbezieht sich bei Erfolg auf das Rohergebnis der API oder des Unterworkflows.

• $states.errorOutputbezieht sich auf die Fehlerausgabe, wenn die API oder der Unterworkflow fehlgeschlagen sind.

  $states.errorOutputkann im Catch Feld Assign oder Output verwendet werden.

Der Versuch, auf Felder und Zustände zuzugreifen$states.result, auf die nicht zugegriffen werden kann, wird bei der Erstellung, Aktualisierung oder Überprüfung der Zustandsmaschine abgefangen. $states.errorOutput

Das $states.context Objekt stellt Ihren Workflows Informationen über deren spezifische Ausführung zur Verfügung, z. B. StartTime Aufgabentoken und erste Workflow-Eingaben. Weitere Informationen hierzu finden Sie unter Zugreifen auf Ausführungsdaten aus dem Context-Objekt in Step Functions .

Behandlung von Ausdrucksfehlern

Zur Laufzeit kann die Auswertung von JSONata Ausdrücken aus verschiedenen Gründen fehlschlagen, z. B.:

• Typfehler — Ein Ausdruck, wie z. B.{% $x + $y %}, schlägt fehl, wenn es sich um eine Zahl $y handelt $x oder nicht.

• Typinkompatibilität — Ein Ausdruck kann einen Typ ergeben, den das Feld nicht akzeptiert. Das Feld TimeoutSeconds erfordert beispielsweise eine numerische Eingabe, sodass der Ausdruck {% $timeout %} fehlschlägt, wenn er eine Zeichenfolge $timeout zurückgibt.

• Wert außerhalb des zulässigen Bereichs — Ein Ausdruck, der einen Wert erzeugt, der außerhalb des zulässigen Bereichs für ein Feld liegt, schlägt fehl. Beispielsweise schlägt ein Ausdruck wie {% $evaluatesToNegativeNumber %} wird in dem TimeoutSeconds Feld fehl.

• Fehler beim Zurückgeben eines Ergebnisses — JSON kann keinen Ausdruck mit undefiniertem Wert darstellen, daher {% $data.thisFieldDoesNotExist %} würde der Ausdruck zu einem Fehler führen.

In jedem Fall gibt der Interpreter den folgenden Fehler aus:. States.QueryEvaluationError Ihre Status „Task“, „Map“ und „Parallel“ können ein Catch Feld catch Erfassung des Fehlers und ein Retry Feld zur Wiederholung des Fehlers bereitstellen.

Konvertierung von zu JSONPath JSONata

In den folgenden Abschnitten werden die Unterschiede zwischen Code, der mit JSONPath und geschrieben wurde, verglichen und erklärt JSONata.

Keine Pfadfelder mehr

ASL erfordert, dass Entwickler Path Versionen von Feldern verwendenTimeoutSecondsPath, um bei der Verwendung JSONPath einen Wert aus den Statusdaten auszuwählen. Wenn Sie diese Option verwenden JSONata, verwenden Sie keine Path Felder mehr, da ASL in Feldern, {% %} die keinen Pfad enthalten JSONata , automatisch für Sie interpretiert, z. B. TimeoutSeconds

• JSONPath Beispiel aus einer älteren Version: "TimeoutSecondsPath": "$timeout"

• JSONata : "TimeoutSeconds": "{% $timeout %}"

In ähnlicher Weise ItemsPath wurde der Map Status durch das Items Feld ersetzt, das ein JSON-Array oder einen JSONata Ausdruck akzeptiert, der als Array ausgewertet werden muss.

JSON-Objekte

ASL verwendet den Begriff Payload-Vorlage, um ein JSON-Objekt zu beschreiben, das JSONPath Ausdrücke für Parameters und ResultSelector Feldwerte enthalten kann. ASL verwendet den Begriff Payload-Vorlage nicht für, JSONata da die JSONata Auswertung für alle Zeichenketten erfolgt, unabhängig davon, ob sie eigenständig oder innerhalb eines JSON-Objekts oder eines JSON-Arrays vorkommen.

Nicht mehr. $

ASL verlangt, dass Sie '.$' an Feldnamen in zu verwendenden Payload-Vorlagen JSONPath und systeminternen Funktionen anhängen. Wenn Sie angeben"QueryLanguage":"JSONata", verwenden Sie nicht mehr die Konvention '.$' für Feldnamen von JSON-Objekten. Stattdessen schließen Sie JSONata Ausdrücke in {% %} Zeichen ein. Sie verwenden dieselbe Konvention für alle Felder mit Zeichenkettenwerten, unabhängig davon, wie tief das Objekt in anderen Arrays oder Objekten verschachtelt ist.

Argumente und Ausgabefelder

Wenn der auf gesetzt QueryLanguage istJSONata, werden die alten I/O-Verarbeitungsfelder deaktiviert (InputPathParameters,ResultSelector, ResultPath undOutputPath) und die meisten Staaten erhalten zwei neue Felder: Arguments undOutput.

JSONata bietet im Vergleich zu den Feldern, die mit JSONPath verwendet wurden, eine einfachere Methode zur Durchführung von I/O-Transformationen. JSONataDie Funktionen machen Arguments und Output leistungsfähiger als die vorherigen fünf Felder mit JSONPath. Diese neuen Feldnamen helfen auch dabei, Ihre ASL zu vereinfachen und das Modell für die Übergabe und Rückgabe von Werten zu verdeutlichen.

Die Output Felder Arguments und (und andere ähnliche Felder wie die von Map stateItemSelector) akzeptieren entweder ein JSON-Objekt wie:

"Arguments": {
    "field1": 42, 
    "field2": "{% jsonata expression %}"
}

Oder Sie können einen JSONata Ausdruck direkt verwenden, zum Beispiel:

"Output": "{% jsonata expression %}"

Die Ausgabe kann auch jede Art von JSON-Wert akzeptieren, zum Beispiel:"Output":true,"Output":42.

Die Output Felder Arguments und werden nur unterstützt JSONata, daher ist es nicht zulässig, sie mit Workflows zu verwenden JSONPath, die Umgekehrt werdenInputPath,Parameters,ResultSelector, ResultPathOutputPath, und andere JSONPath Felder nur in unterstützt. Daher ist es nicht zulässig JSONPath, pfadbasierte Felder zu verwenden, wenn Sie sie JSONata als oberste Workflow- oder Statusabfragesprache verwenden.

Status übergeben

Das optionale Ergebnis im Status „Bestanden“ wurde bisher als Ausgabe einer virtuellen Aufgabe behandelt. Wenn Sie die Sprache für die Workflow- oder Statusabfrage JSONata ausgewählt haben, können Sie jetzt das neue Ausgabefeld verwenden.

Status „Auswahl“

Bei der Verwendung JSONPath haben Auswahlstatus eine Eingabe Variable und zahlreiche Vergleichspfade, wie z. B. die folgendenNumericLessThanEqualsPath:

# JSONPath choice state sample, with Variable and comparison path
"Check Price": {
  "Type": "Choice",
  "Default": "Pause",
  "Choices": [
  {
    "Variable": "$.current_price.current_price",
    "NumericLessThanEqualsPath": "$.desired_price",
    "Next": "Send Notification"
  } ],
}

Mit hat der Auswahlstatus eine JSONata, Condition in der Sie einen JSONata Ausdruck verwenden können:

# Choice state after JSONata conversion
"Check Price": {
  "Type": "Choice",
  "Default": "Pause"
  "Choices": [
    {
      "Condition": "{% $current_price <= $states.input.desired_priced %}",
      "Next": "Send Notification"
    } ]
    

Hinweis: Variablen und Vergleichsfelder sind nur für verfügbar JSONPath. Die Bedingung ist nur für verfügbar JSONata.

JSONata Beispiele

Die folgenden Beispiele können in Workflow Studio zum Experimentieren erstellt werden JSONata. Sie können die Zustandsmaschinen erstellen und ausführen oder den Teststatus verwenden, um Daten zu übergeben und sogar die Zustandsmaschinen-Definition zu ändern.

Beispiel: Eingabe und Ausgabe

Dieses Beispiel zeigt, wie Sie $states.input die Statuseingabe und das Output Feld verwenden, um die Statusausgabe anzugeben, wenn Sie sich dafür entscheiden JSONata.

{
  "Comment": "Input and Output example using JSONata",
  "QueryLanguage": "JSONata",
  "StartAt": "Basic Input and Output",
  "States": {
    "Basic Input and Output": {
      "QueryLanguage": "JSONata",
      "Type": "Succeed",
      "Output": {
        "lastName": "{% 'Last=>' & $states.input.customer.lastName %}",
        "orderValue": "{% $states.input.order.total %}"
      }
    }
  }
}

Wenn der Workflow mit dem Folgenden als Eingabe ausgeführt wird:

{
  "customer": {
    "firstName": "Martha",
    "lastName": "Rivera"
  },
  "order": {
    "items": 7,
    "total": 27.91
  }
}

Bei der Ausführung des Teststatus oder der Zustandsmaschine wird die folgende JSON-Ausgabe zurückgegeben:

{
  "lastName": "Last=>Rivera",
  "orderValue": 27.91
}

Beispiel: Filtern mit JSONata

Sie können Ihre Daten mit JSONata Pfadoperatoren filtern. Stellen Sie sich beispielsweise vor, Sie haben eine Liste von Produkten zur Eingabe und möchten nur Produkte verarbeiten, die keine Kalorien enthalten. Sie können eine Zustandsmaschinen-Definition mit der folgenden ASL erstellen und den FilterDietProducts Status mit der folgenden Beispieleingabe testen.

Zustandsmaschinen-Definition zum Filtern mit JSONata

{
  "Comment": "Filter products using JSONata",
  "QueryLanguage": "JSONata",
  "StartAt": "FilterDietProducts",
  "States": {
    "FilterDietProducts": {
      "Type": "Pass",
      "Output": {
        "dietProducts": "{% $states.input.products[calories=0] %}"
      },
      "End": true
    }
  }
}

Beispieleingabe für den Test

{
  "products": [
    {
      "calories": 140,
      "flavour": "Cola",
      "name": "Product-1"
    },
    {
      "calories": 0,
      "flavour": "Cola",
      "name": "Product-2"
    },
    {
      "calories": 160,
      "flavour": "Orange",
      "name": "Product-3"
    },
    {
      "calories": 100,
      "flavour": "Orange",
      "name": "Product-4"
    },
    {
      "calories": 0,
      "flavour": "Lime",
      "name": "Product-5"
    }
  ]
}

Ergebnis des Testens des Schritts in Ihrer Zustandsmaschine

{
    "dietProducts": [
        {
            "calories": 0,
            "flavour": "Cola",
            "name": "Product-2"
        },
        {
            "calories": 0,
            "flavour": "Lime",
            "name": "Product-5"
        }
    ]
}

JSONata von Step Functions bereitgestellte Funktionen

JSONata enthält Funktionsbibliotheken für Funktionen vom Typ String, Numeric, Aggregation, Boolean, Array, Object, Date/Time und High Order. Step Functions bietet zusätzliche JSONata Funktionen, die Sie in Ihren JSONata Ausdrücken verwenden können. Diese integrierten Funktionen dienen als Ersatz für die intrinsischen Funktionen von Step Functions. Systeminterne Funktionen sind nur in Staaten verfügbar, die die Abfragesprache verwenden. JSONPath

Hinweis: Integrierte JSONata Funktionen, die Ganzzahlwerte als Parameter benötigen, runden automatisch alle angegebenen Zahlen ab, die keine ganzen Zahlen sind.

$partition — JSONata entspricht einer States.ArrayPartition systemeigenen Funktion zur Partitionierung eines großen Arrays.

Der erste Parameter ist das zu partitionierende Array, der zweite Parameter ist eine Ganzzahl, die die Chunk-Größe darstellt. Der Rückgabewert wird ein zweidimensionales Array sein. Der Interpreter teilt das Eingabearray in mehrere Arrays der durch die Chunk-Größe angegebenen Größe auf. Die Länge des letzten Array-Chunks kann geringer sein als die Länge der vorherigen Array-Chunks, wenn die Anzahl der verbleibenden Elemente im Array kleiner als die Chunk-Größe ist.

"Assign": {
  "arrayPartition": "{% $partition([1,2,3,4], $states.input.chunkSize) %}"
}

$range — JSONata entspricht einer systemeigenen Funktion zur States.ArrayRange Generierung eines Wertearrays.

Diese Funktion benötigt drei Argumente. Das erste Argument ist eine Ganzzahl, die das erste Element des neuen Arrays darstellt, das zweite Argument ist eine Ganzzahl, die das letzte Element des neuen Arrays darstellt, und das dritte Argument ist die Ganzzahl mit Deltawert für die Elemente im neuen Array. Der Rückgabewert ist ein neu generiertes Array von Werten, das vom ersten Argument der Funktion bis zum zweiten Argument der Funktion reicht, wobei Elemente dazwischen durch das Delta angepasst werden. Der Deltawert kann positiv oder negativ sein, wodurch jedes Element vom letzten Element bis zum Erreichen oder Überschreiten des Endwerts erhöht oder verringert wird.

"Assign": {
  "arrayRange": "{% $range(0, 10, 2) %}"
}

$hash — JSONata entspricht der States.Hash systemeigenen Funktion zur Berechnung des Hashwerts einer bestimmten Eingabe.

Diese Funktion benötigt zwei Argumente. Das erste Argument ist die Quellzeichenfolge, die gehasht werden soll. Das zweite Argument ist eine Zeichenfolge, die den Hash-Algorithmus für die Hash-Berechnung darstellt. Der Hash-Algorithmus muss einen der folgenden Werte haben:"MD5",,, "SHA-1""SHA-256","SHA-384". "SHA-512" Der Rückgabewert ist eine Zeichenfolge mit dem berechneten Hash der Daten.

Diese Funktion wurde entwickelt, weil sie die Berechnung von Hashes JSONata nicht nativ unterstützt.

"Assign": {
  "myHash": "{% $hash($states.input.content, $hashAlgorithmName) %}"
}

$random — JSONata entspricht der systemeigenen Funktion zur States.MathRandom Rückgabe einer Zufallszahl n, wobei. 0 ≤ n < 1

Die Funktion verwendet ein optionales Integer-Argument, das den Startwert der Zufallsfunktion darstellt. Wenn Sie diese Funktion mit demselben Ausgangswert verwenden, gibt sie eine identische Zahl zurück.

Diese überladene Funktion wurde erstellt, weil die integrierte JSONata Funktion $randomkeinen Startwert akzeptiert.

"Assign": {
   "randNoSeed": "{% $random() %}",
   "randSeeded": "{% $random($states.input.seed) %}"
}

$uuid — JSONata Version der systemeigenen Funktion. States.UUID

Die Funktion akzeptiert keine Argumente. Diese Funktion gibt eine v4-UUID zurück.

Diese Funktion wurde erstellt, weil sie JSONata die Fähigkeit zur Generierung nicht nativ unterstützt. UUIDs

"Assign": {
  "uniqueId": "{% $uuid() %}"
}

$parse — JSONata Funktion zur Deserialisierung von JSON-Strings.

Die Funktion verwendet ein stringifiziertes JSON als einziges Argument.

JSONata unterstützt diese Funktionalität über$eval; $eval wird jedoch in Step Functions Functions-Workflows nicht unterstützt.

"Assign": {
  "deserializedPayload": "{% $parse($states.input.json_string) %}"
}