Übergeben von Daten zwischen Staaten mit Variablen - AWS Step Functions

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.

Übergeben von Daten zwischen Staaten mit Variablen

Verwaltung des Status mit Variablen und JSONata

Step Functions hat kürzlich Variablen hinzugefügt und JSONata dient der Verwaltung von Zustands- und Transformationsdaten.

Weitere Informationen finden Sie im Blogbeitrag Vereinfachung der Entwicklererfahrung mit Variablen und JSONata in AWS Step Functions

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

Mithilfe von Variablen und Statusausgaben können Sie Daten zwischen den einzelnen Schritten Ihres Workflows weitergeben.

Mithilfe von Workflow-Variablen können Sie Daten in einem Schritt speichern und diese Daten in future Schritten abrufen. Sie könnten beispielsweise eine API-Antwort speichern, die Daten enthält, die Sie möglicherweise später benötigen. Umgekehrt kann die Statusausgabe nur als Eingabe für den nächsten Schritt verwendet werden.

Konzeptioneller Überblick über Variablen

Mit Workflow-Variablen können Sie Daten speichern, auf die Sie später zurückgreifen können. In Schritt 1 könnte beispielsweise das Ergebnis einer API-Anfrage gespeichert werden, sodass ein Teil dieser Anfrage später in Schritt 5 wiederverwendet werden kann.

Im folgenden Szenario ruft die Zustandsmaschine einmal Daten von einer API ab. In Schritt 1 speichert der Workflow die zurückgegebenen API-Daten (bis zu 256 KiB pro Status) in einer Variablen 'x', um sie in späteren Schritten zu verwenden.

Ohne Variablen müssten Sie die Daten durch die Ausgabe von Schritt 1 über Schritt 2 bis Schritt 3 bis Schritt 4 weiterleiten, um sie in Schritt 5 verwenden zu können. Was ist, wenn für diese Zwischenschritte die Daten nicht benötigt werden? Daten über Ausgaben und Eingaben von Bundesstaat zu Bundesstaat zu übertragen, wäre unnötiger Aufwand.

Mit Variablen können Sie Daten speichern und in jedem future Schritt verwenden. Sie können auch Schritte ändern, neu anordnen oder hinzufügen, ohne den Datenfluss zu unterbrechen. Aufgrund der Flexibilität von Variablen müssen Sie Output möglicherweise nur verwenden, um Daten aus den Unterworkflows Parallel und Map zurückzugeben, und zwar am Ende der Ausführung Ihrer Zustandsmaschine.

Diagram showing step 1 assigning a value to $x, used in step 5.

Staaten, die Variablen unterstützen

Die folgenden Zustandstypen unterstützen Assign die Deklaration und Zuweisung von Werten zu Variablen: Pass, Task, Map, Parallel, Choice, Wait.

Um eine Variable festzulegen, stellen Sie ein JSON-Objekt mit Variablennamen und -werten bereit:

"Assign": { "productName": "product1", "count" : 42, "available" : true }

Um auf eine Variable zu verweisen, stellen Sie dem Namen ein Dollarzeichen ($) voran, zum Beispiel. $productName

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 .

Syntax der Variablennamen

Variablennamen folgen den Regeln für Unicode-Identifikatoren, wie sie im Unicode® Standard Annex #31 beschrieben sind. Das erste Zeichen eines Variablennamens muss ein Unicode-ID_Start-Zeichen sein, und das zweite und die nachfolgenden Zeichen müssen Unicode-ID_Continue-Zeichen sein. Die maximale Länge eines Variablennamens ist 80.

Die Konvention für Variablennamen ähnelt den Regeln für JavaScript und andere Programmiersprachen.

Gültigkeitsbereich der Variablen

Step Functions Functions-Workflows vermeiden Wettlaufbedingungen mit Variablen, indem sie einen workflow-lokalen Bereich verwenden.

Der Workflow-lokale Gültigkeitsbereich umfasst alle Zustände innerhalb des States-Felds einer Zustandsmaschine, nicht jedoch Zustände innerhalb der Status Parallel oder Map. Zustände innerhalb von Parallel- oder Map-Status können sich auf Variablen mit äußerem Gültigkeitsbereich beziehen, sie erstellen und verwalten jedoch ihre eigenen, separaten Workflow-lokalen Variablen und Werte.

ParallelZweige und Map Iterationen können auf Variablenwerte aus äußeren Gültigkeitsbereichen zugreifen, aber sie haben keinen Zugriff auf Variablenwerte aus anderen gleichzeitigen Verzweigungen oder Iterationen. Bei der Behandlung von Fehlern Catch kann das Assign Feld in a Variablen im äußeren Bereich, d. h. dem Bereich, in dem der Parallel/Map-Status existiert, Werte zuweisen.

Ausnahme: Distributed Map-Status können derzeit nicht auf Variablen in äußeren Gültigkeitsbereichen verweisen.

Eine Variable ist in einem Bereich vorhanden, wenn ihr ein Status im Bereich einen Wert zuweist. Um häufige Fehler zu vermeiden, darf eine in einem inneren Bereich zugewiesene Variable nicht denselben Namen haben wie eine in einem äußeren Bereich zugewiesene Variable. Wenn beispielsweise der Bereich der obersten Ebene einer aufgerufenen Variablen einen Wert zuweistmyVariable, kann kein anderer Bereich (innerhalb einesMap,Parallel) ebenfalls einen Wert zuweisenmyVariable.

Der Zugriff auf Variablen hängt vom aktuellen Gültigkeitsbereich ab. Parallel- und Map-Status haben ihren eigenen Gültigkeitsbereich, können aber auf Variablen in äußeren Bereichen zugreifen.

Wenn ein Parallel- oder Map-Status abgeschlossen ist, verlassen alle ihre Variablen den Gültigkeitsbereich und es kann nicht mehr darauf zugegriffen werden. Verwenden Sie das Ausgabefeld, um Daten aus Parallel-Verzweigungen und Map-Iterationen weiterzugeben.

Weisen Sie das Feld in ASL zu

Das Assign Feld in ASL wird verwendet, um einer oder mehreren Variablen Werte zuzuweisen. Das Assign Feld ist auf der obersten Ebene jedes Bundesstaates (außer Succeed undFail), innerhalb der Choice staatlichen Regeln und innerhalb von Catch Feldern verfügbar. Zum Beispiel:

# Example of Assign with JSONata "Store inputs": { "Type": "Pass", "Next": "Get Current Price", "Comment": "Store the input desired price into a variable: $desiredPrice", "Assign": { "desiredPrice": "{% $states.input.desired_price %}", "maximumWait": "{% $states.input.max_days %}" } },

Das Assign Feld benötigt ein JSON-Objekt. Jedes Feld der obersten Ebene benennt eine Variable, die zugewiesen werden soll. In den vorherigen Beispielen lauten die Variablennamen desiredPrice undmaximumWait. {% ... %}Gibt bei Verwendung einen JSONata Ausdruck an JSONata, der Variablen oder komplexere Ausdrücke enthalten kann. Weitere Informationen zu JSONata Ausdrücken finden Sie in der JSONata.org-Dokumentation.

Bei Verwendung JSONataals Abfragesprache zeigt das folgende Diagramm, wie Felder Zuweisen und Ausgeben parallel verarbeitet werden. Beachten Sie die Implikation: Die Zuweisung von Variablenwerten hat keinen Einfluss auf den Status Output.

Diagram showing a comparison of JSONPath and JSONata flow.

Im folgenden JSONata Beispiel werden Daten order.product aus der Statuseingabe abgerufen. Die Variable currentPrice wird auf einen Wert aus dem Ergebnis der Aufgabe gesetzt.

# Example of Task with JSONata assignment from result { "Type": "Task", ... "Assign": { "product": "{% $states.input.order.product %}", "currentPrice": "{% $states.result.Payload.current_price %}" }, "Next": "the next state" }

Hinweis: Sie können einem Teil einer Variablen keinen Wert zuweisen. Zum Beispiel können Sie"Assign":{"x":42}, aber Sie können nicht "Assign":{"x.y":42} oder"Assign":{"x[2]":42}.

Reihenfolge der Auswertung in einem Zuweisungsfeld

Alle Variablenreferenzen in Step Functions Functions-Zuständen verwenden die Werte wie bei der Zustandseingabe.

Diese Tatsache ist wichtig, um zu verstehen, wie das Assign Feld einer oder mehreren Variablen Werte zuweist. Zuerst werden neue Werte berechnet, dann weist Step Functions den Variablen die neuen Werte zu. Die neuen Variablenwerte werden ab dem nächsten Status verfügbar sein. Betrachten Sie zum Beispiel das folgende Assign Feld:

# Starting values: $x=3, $a=6 "Assign": { "x": "{% $a %}", "nextX": "{% $x %}" } # Ending values: $x=6, $nextX=3

Im vorherigen Beispiel x wird die Variable sowohl zugewiesen als auch referenziert.

Denken Sie daran, dass alle Ausdrücke zuerst ausgewertet und dann Zuweisungen vorgenommen werden. Und neu zugewiesene Werte werden im nächsten Status verfügbar sein.

Lassen Sie uns das Beispiel im Detail durchgehen. Nehmen wir an, $x dass in einem früheren Status ein Wert von drei (3) und ein Wert von sechs (6) zugewiesen $a wurde. Die folgenden Schritte beschreiben den Vorgang:

  1. Alle Ausdrücke werden anhand der aktuellen Werte aller Variablen ausgewertet.

    Die Auswertung des Ausdrucks "{% $a %}" ergibt 6 und "{% $x %}" die Auswertung ergibt 3.

  2. Als Nächstes werden die folgenden Aufgaben vorgenommen:

    $xwird der Wert sechs (6) zugewiesen

    $nextXwird drei (3) zugewiesen

Hinweis: Wenn es $x nicht zuvor zugewiesen worden wäre, würde das Beispiel fehlschlagen, weil $x es undefiniert wäre.

Zusammenfassend lässt sich sagen, dass Step Functions alle Ausdrücke auswertet und dann Zuweisungen vornimmt. Die Reihenfolge, in der die Variablen im Assign Feld vorkommen, spielt keine Rolle.

Einschränkungen

Die maximale Größe einer einzelnen Variablen beträgt 256 KiB, sowohl für Standard- als auch für Express-Workflows.

Die maximale kombinierte Größe für alle Variablen in einem einzigen Assign Feld beträgt ebenfalls 256 KiB. Sie könnten beispielsweise 128 KiB X und Y zuweisen, aber Sie könnten nicht gleichzeitig 256 KiB in demselben Feld X und Y zuweisen. Assign

Die Gesamtgröße aller gespeicherten Variablen darf 10 MiB pro Ausführung nicht überschreiten.

Verwenden von Variablen in Staaten JSONPath

Variablen sind auch in Staaten verfügbar, die sie JSONPath für ihre Abfragesprache verwenden.

Sie können in jedem Feld, das einen JSONpath Ausdruck ($.oder eine $$. Syntax) akzeptiert, auf eine Variable verweisen, mit Ausnahme vonResultPath, das eine Position in der Statuseingabe angibt, an der das Ergebnis des Zustands eingefügt werden soll. Variablen können nicht in ResultPath verwendet werden.

In bezieht JSONPath sich das $ Symbol auf den „aktuellen“ Wert und $$ steht für das Status-Kontextobjekt. JSONPath Ausdrücke können $. wie in beginnen$.customer.name. Sie können auf den Kontext $$. wie in zugreifen$$.Execution.Id.

Um auf eine Variable zu verweisen, verwenden Sie auch das $ Symbol vor einem Variablennamen, z. B. $x oder$order.numItems.

In JSONPathFeldern, die systeminterne Funktionen akzeptieren, können Variablen beispielsweise in den Argumenten verwendet werden. States.Format('The order number is {}', $order.number)

Das folgende Diagramm zeigt, wie der Schritt „Zuweisen“ in einer JSONPathAufgabe gleichzeitig mit dem folgenden Vorgang ausgeführt wird: ResultSelector

Logical diagram of a state that uses JSONPath query language.

Zuweisen von Variablen in JSONPath

JSONPath Variablenzuweisungen verhalten sich ähnlich wie Payload-Vorlagen. Felder, die mit enden, .$ geben an, dass es sich bei dem Wert um einen JSONPath Ausdruck handelt, den Step Functions während der Ausführung der Zustandsmaschine zu einem Wert auswertet (zum Beispiel: $.order..product und$.order.total).

# Example of Assign with JSONPath { "Type": "Task", ... "Assign": { "products.$": "$.order..product", "orderTotal.$": "$.order.total" }, "Next": "the next state" }

Bei JSONPath Staaten hängt der Wert von $ in einem Assign Feld vom Statustyp ab. In Task,Map, Parallel states, $ bezieht sich der auf das API-/Sub-Workflow-Ergebnis. In Choice und Wait State $ bezieht sich auf die tatsächliche Eingabe, d. h. den Wert, nachdem er auf die Statuseingabe angewendet InputPath wurde. For Pass $ bezieht sich auf das Ergebnis, unabhängig davon, ob es durch das Result Feld oder die Parameters FelderInputPath/generiert wurde.

Im folgenden JSONPath Beispiel wird der details Variablen ein JSON-Objekt, das Ergebnis des JSONPath Ausdrucks $.result.code und das Ergebnis des JSONPath Ausdrucks States.Format('Hello {}', $customer.name) zugewiesenmessage. resultCode Wenn es in einem Task Zustand war, dann $ in $.order.items und $.result.code bezieht sich auf das API-Ergebnis. Der startTime Variablen wird ein Wert aus dem Context-Objekt zugewiesen,$$.Execution.StartTime.

"Assign": { "details": { "status": "SUCCESS", "lineItems.$": "$.order.items" }, "resultCode.$": "$.result.code", "message.$": "States.Format('Hello {}', $customer.name)", "startTime.$": "$$.Execution.StartTime" }