Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Transformieren von Daten mit JSONata In-Step-Funktionen
Mit 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](https://docs.jsonata.org/overview.html).
**Unterstützte JSONata Version**
Step Functions unterstützt JSONata Version 2.0.6.
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`, `ResultSelector``ResultPath`, und`OutputPath`) auf nur zwei Felder reduziert: `Arguments` und`Output`. 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:** `"{% %}"`
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:
![\[Diagramm, das die Felder in JSONPath und in JSONata den Bundesstaaten vergleicht.\]](http://docs.aws.amazon.com/de_de/step-functions/latest/dg/images/compare-jsonpath-jsonata.png)
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.
![\[Logisches Diagramm eines Zustands, der die JSONata Abfragesprache verwendet.\]](http://docs.aws.amazon.com/de_de/step-functions/latest/dg/images/vars-jsonata.png)
## 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, ein JSON-Objekt oder einen JSONata Ausdruck, der als Array oder Objekt ausgewertet werden muss.
## Reservierte Variable: \$1states
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.input`bezieht sich immer auf die ursprüngliche Statuseingabe.
Für `Task``Parallel`, und gibt `Map` an:
+ **`$states.result`**bezieht sich bei Erfolg auf das Rohergebnis der API oder des Unterworkflows.
+ **`$states.errorOutput`**bezieht sich auf die Fehlerausgabe, wenn die API oder der Unterworkflow fehlgeschlagen sind.
`$states.errorOutput`kann 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 finden Sie unter[Zugreifen auf Ausführungsdaten aus dem Context-Objekt in Step Functions](input-output-contextobject.md).
## 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 verwenden`TimeoutSecondsPath`, 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, ein JSON-Objekt oder einen JSONata Ausdruck akzeptiert, der als Array oder Objekt 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. \$1
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 das auf gesetzt `QueryLanguage` ist`JSONata`, werden die alten I/O Verarbeitungsfelder deaktiviert (`InputPath`, `Parameters``ResultSelector`, `ResultPath` und`OutputPath`) und die meisten Staaten erhalten zwei neue Felder: `Arguments` und`Output`.
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` state`ItemSelector`) 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 werden`InputPath`,`Parameters`,`ResultSelector`, `ResultPath``OutputPath`, 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.
### Übergabezustand
Der optionale Status „**Ergebnis** in einem 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 folgenden`NumericLessThanEqualsPath`:
```
# 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
}
```
![\[Screenshot, der die Eingabe und Ausgabe eines zu testenden Zustands zeigt.\]](http://docs.aws.amazon.com/de_de/step-functions/latest/dg/images/jsonata-basic-io.png)
### Beispiel: Filtern mit JSONata
Sie können Ihre Daten mit JSONata [Pfadoperatoren](https://docs.jsonata.org/path-operators) 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"
}
]
}
```
![\[Beispielausgabe für JSONata Ausdrücke, die getestet werden.\]](http://docs.aws.amazon.com/de_de/step-functions/latest/dg/images/test-state-jsonata.png)
## 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.
**\$1partition —** 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) %}"
}
```
**\$1range** — 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) %}"
}
```
**\$1hash** — 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) %}"
}
```
**\$1random** — 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 [https://docs.jsonata.org/numeric-functions#random](https://docs.jsonata.org/numeric-functions#random)keinen Startwert akzeptiert.
```
"Assign": {
"randNoSeed": "{% $random() %}",
"randSeeded": "{% $random($states.input.seed) %}"
}
```
**\$1uuid** — 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() %}"
}
```
**\$1parse** — 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) %}"
}
```