Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Trasformazione dei dati con Step JSONata Functions
Con JSONata, ottieni un potente linguaggio di query ed espressione open source per **selezionare** e **trasformare** i dati nei tuoi flussi di lavoro. Per una breve introduzione e un JSONata riferimento completo, consultate la [JSONatadocumentazione.org](https://docs.jsonata.org/overview.html).
**JSONata Versione supportata**
Step Functions supporta JSONata la versione 2.0.6.
Il video seguente descrive le variabili e JSONata in Step Functions con un esempio di DynamoDB:
È necessario attivare l'utilizzo del linguaggio di JSONata interrogazione e trasformazione per i flussi di lavoro esistenti. Quando crei un flusso di lavoro nella console, ti consigliamo di scegliere la macchina a JSONata stati di primo livello. `QueryLanguage` Per i flussi di lavoro esistenti o nuovi che lo utilizzano JSONPath, la console offre un'opzione in cui convertire i singoli stati. JSONata
Dopo la selezione JSONata, i campi del flusso di lavoro verranno ridotti da cinque JSONPath campi (`InputPath``Parameters`,`ResultSelector`,`ResultPath`, e`OutputPath`) a soli due campi: `Arguments` e`Output`. Inoltre, **non** verranno utilizzati i nomi `.$` delle chiavi degli oggetti JSON.
Se non conosci Step Functions, devi solo sapere che JSONata le espressioni utilizzano la seguente sintassi:
**JSONata sintassi:** `"{% %}"`
I seguenti esempi di codice mostrano una conversione da JSONPath a 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"
}
}
```
Dato l'input `{ "title" : "Doctor" }` e la variabile `customerName` assegnata a`"María"`, entrambe le macchine a stati produrranno il seguente risultato JSON:
```
{
"static": "Hello",
"title": "Doctor",
"name": "María",
"not-evaluated": "$customerName"
}
```
Nel diagramma seguente, potete vedere una rappresentazione grafica che mostra come la conversione da JSONPath (sinistra) a JSONata (destra) ridurrà la complessità dei passaggi nelle vostre macchine a stati:
![\[Diagramma che confronta i campi in e gli stati. JSONPath JSONata\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/compare-jsonpath-jsonata.png)
È possibile (facoltativamente) selezionare e trasformare i dati dall'input dello stato in **argomenti** da inviare all'azione integrata. **Con JSONata, puoi quindi (facoltativamente) selezionare e trasformare **i risultati** dell'azione per l'assegnazione alle variabili e per l'output dello stato.**
Nota: le fasi di **assegnazione** e **di uscita** avvengono in **parallelo**. Se scegli di trasformare i dati durante l'assegnazione delle variabili, tali dati trasformati **non** saranno disponibili nella fase di output. È necessario riapplicare la JSONata trasformazione nella fase di output.
![\[Diagramma logico di uno stato che utilizza il linguaggio di JSONata interrogazione.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/vars-jsonata.png)
## QueryLanguage campo
Nelle definizioni ASL del flusso di lavoro, c'è un `QueryLanguage` campo al livello superiore della definizione di una macchina a stati e nei singoli stati. Impostando i singoli stati `QueryLanguage` all'interno, è possibile adottarli in modo incrementale JSONata in una macchina a stati esistente anziché aggiornare la macchina a stati tutta in una volta.
Il `QueryLanguage` campo può essere impostato su o. `"JSONPath"` `"JSONata"` Se il `QueryLanguage` campo di primo livello viene omesso, il valore predefinito è. `"JSONPath"` Se uno stato contiene un `QueryLanguage` campo a livello di stato, Step Functions utilizzerà il linguaggio di interrogazione specificato per quello stato. Se lo stato non contiene un `QueryLanguage` campo, utilizzerà il linguaggio di interrogazione specificato nel campo di primo livello`QueryLanguage`.
## Scrittura di JSONata espressioni in stringhe JSON
Quando una stringa nel valore di un campo ASL, un campo oggetto JSON o un elemento dell'array JSON è circondata da `{% %}` caratteri, quella stringa verrà valutata come. JSONata Nota, la stringa deve iniziare `{%` senza spazi iniziali e deve terminare senza `%}` spazi finali. L'apertura o la chiusura errata dell'espressione genereranno un errore di convalida.
Alcuni esempi:
+ `"TimeoutSeconds" : "{% $timeout %}"`
+ `"Arguments" : {"field1" : "{% $name %}"}`in uno stato `Task`
+ `"Items": [1, "{% $two %}", 3]`in uno `Map` stato
Non tutti i campi ASL accettano JSONata. Ad esempio, il `Type` campo di ogni stato deve essere impostato su una stringa costante. Analogamente, il `Resource` campo `Task` dello stato deve essere una stringa costante. Il `Items` campo di `Map` stato accetterà un array JSON, un oggetto JSON o un' JSONata espressione che deve restituire un array o un oggetto.
## Variabile riservata: \$1states
Step Functions definisce una singola variabile riservata chiamata **`$states`**. Negli JSONata stati, le seguenti strutture vengono assegnate `$states` per essere utilizzate nelle JSONata espressioni:
```
# 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
}
```
All'ingresso dello stato, Step Functions assegna l'input di stato a **`$states.input`**. Il valore di `$states.input` può essere utilizzato in tutti i campi che accettano JSONata espressioni. `$states.input`si riferisce sempre all'input di stato originale.
Per `Task``Parallel`, e `Map` afferma:
+ **`$states.result`**fa riferimento al risultato non elaborato dell'API o del flusso di lavoro secondario in caso di successo.
+ **`$states.errorOutput`**fa riferimento all'Error Output se l'API o il sottoflusso di lavoro non sono riusciti.
`$states.errorOutput`può essere utilizzato nel `Catch` campo `Assign` o`Output`.
Il tentativo di accedere `$states.result` a campi e stati `$states.errorOutput` in cui non sono accessibili verrà interrotto al momento della creazione, dell'aggiornamento o della convalida della macchina a stati.
L'`$states.context`oggetto fornisce ai flussi di lavoro informazioni sulla loro esecuzione specifica, ad esempio il token dell'attività e l'input iniziale del flusso di lavoro. `StartTime` Per ulteriori informazioni, consulta[Accesso ai dati di esecuzione dall'oggetto Context in Step Functions](input-output-contextobject.md).
## Gestione degli errori di espressione
In fase di esecuzione, la valutazione delle JSONata espressioni potrebbe non riuscire per una serie di motivi, ad esempio:
+ **Errore di tipo**: un'espressione, ad esempio`{% $x + $y %}`, avrà esito negativo se `$x` o meno `$y` è un numero.
+ **Incompatibilità tra tipi**: un'espressione potrebbe restituire un tipo che il campo non accetterà. Ad esempio, il campo `TimeoutSeconds` richiede un input numerico, quindi l'espressione `{% $timeout %}` avrà esito negativo se `$timeout` restituisce una stringa.
+ **Valore non compreso nell'intervallo**: un'espressione che produce un valore che non rientra nell'intervallo accettabile per un campo avrà esito negativo. Ad esempio, un'espressione come non `{% $evaluatesToNegativeNumber %}` riuscirà nel `TimeoutSeconds` campo.
+ **Mancata restituzione di un risultato**: JSON non può rappresentare un'espressione di valore indefinita, pertanto l'espressione `{% $data.thisFieldDoesNotExist %}` genererebbe un errore.
In ogni caso, l'interprete genererà l'errore:. `States.QueryEvaluationError` Gli stati Task, Map e Parallel possono fornire un `Catch` campo per catturare l'errore e un `Retry` campo per riprovare l'errore.
## Conversione da a JSONPath JSONata
Le sezioni seguenti confrontano e spiegano le differenze tra il codice scritto con JSONPath e JSONata.
### Niente più campi di percorso
ASL richiede agli sviluppatori di utilizzare `Path` versioni dei campi, ad esempio`TimeoutSecondsPath`, per selezionare un valore dai dati di stato durante l'utilizzo JSONPath. Quando si utilizza JSONata, non si utilizzano più `Path` i campi perché ASL interpreterà automaticamente JSONata le espressioni `{% %}` racchiuse in campi non Path, ad esempio. `TimeoutSeconds`
+ JSONPath esempio precedente: `"TimeoutSecondsPath": "$timeout"`
+ JSONata : `"TimeoutSeconds": "{% $timeout %}"`
Allo stesso modo, `Map` lo `ItemsPath` stato è stato sostituito con il `Items` campo che accetta un array JSON, un oggetto JSON o un' JSONata espressione che deve restituire un array o un oggetto.
### Oggetti JSON
ASL utilizza il termine *modello di payload* per descrivere un oggetto JSON che può contenere JSONPath espressioni e valori di `Parameters` campo. `ResultSelector` ASL non utilizzerà il termine modello di payload JSONata perché la JSONata valutazione avviene per tutte le stringhe, indipendentemente dal fatto che si verifichino singolarmente o all'interno di un oggetto JSON o di un array JSON.
### Non più. \$1
ASL richiede di aggiungere '`.$`' ai nomi dei campi nei modelli di payload da utilizzare JSONPath e nelle funzioni intrinseche. Quando si specifica`"QueryLanguage":"JSONata"`, non si utilizza più la convenzione '`.$`' per i nomi dei campi degli oggetti JSON. Invece, racchiudi JSONata le espressioni in `{% %}` caratteri. Utilizzate la stessa convenzione per tutti i campi con valori di stringa, indipendentemente dalla profondità con cui l'oggetto è annidato all'interno di altri array o oggetti.
### Argomenti e campi di output
Quando `QueryLanguage` è impostato su`JSONata`, i vecchi campi di I/O elaborazione verranno disabilitati (`InputPath`, `Parameters``ResultSelector`, `ResultPath` e`OutputPath`) e la maggior parte degli stati riceverà due nuovi campi: `Arguments` e`Output`.
JSONata fornisce un modo più semplice per eseguire I/O trasformazioni rispetto ai campi utilizzati con. JSONPath JSONataLe sue caratteristiche `Arguments` lo rendono `Output` più capace rispetto ai cinque campi precedenti. JSONPath Questi nuovi nomi di campo aiutano anche a semplificare l'ASL e a chiarire il modello per il passaggio e la restituzione di valori.
I `Output` campi `Arguments` and (e altri campi simili come quelli di `Map` state`ItemSelector`) accetteranno un oggetto JSON come:
```
"Arguments": {
"field1": 42,
"field2": "{% jsonata expression %}"
}
```
In alternativa, puoi usare direttamente un' JSONata espressione, ad esempio:
```
"Output": "{% jsonata expression %}"
```
Output può anche accettare qualsiasi tipo di valore JSON, ad esempio:`"Output":true`,`"Output":42`.
I `Output` campi `Arguments` and supportano solo i campi JSONata, quindi non è valido utilizzarli con i flussi di lavoro che utilizzano. JSONPath Al contrario,,`InputPath`, `Parameters` `ResultSelector` `ResultPath``OutputPath`, e gli altri JSONPath campi sono supportati solo in JSONPath, quindi non è valido utilizzare i campi basati sui percorsi quando vengono utilizzati JSONata come flusso di lavoro di primo livello o linguaggio di interrogazione statale.
### Stato Pass
Lo stato facoltativo **Result** in a Pass veniva precedentemente considerato come l'*output* di un'attività virtuale. JSONata Selezionato come linguaggio di ricerca del flusso di lavoro o dello stato, ora puoi utilizzare il nuovo campo **Output**.
### Stato della scelta
Quando vengono utilizzati JSONPath, gli stati di scelta hanno un input `Variable` e numerosi percorsi di confronto, come i seguenti`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"
} ],
}
```
Con JSONata, lo stato di scelta ha un `Condition` punto in cui è possibile utilizzare un' JSONata espressione:
```
# Choice state after JSONata conversion
"Check Price": {
"Type": "Choice",
"Default": "Pause"
"Choices": [
{
"Condition": "{% $current_price <= $states.input.desired_priced %}",
"Next": "Send Notification"
} ]
```
Nota: le variabili e i campi di confronto sono disponibili solo per JSONPath. La condizione è disponibile solo per JSONata.
## JSONata esempi
I seguenti esempi possono essere creati in Workflow Studio per sperimentare JSONata. È possibile creare ed eseguire le macchine a stati oppure utilizzare lo **stato Test** per trasmettere dati e persino modificare la definizione della macchina a stati.
### Esempio: input e output
Questo esempio mostra come `$states.input` utilizzare l'input dello stato e il `Output` campo per specificare l'output dello stato quando si attiva l'attivazione 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 %}"
}
}
}
}
```
Quando il flusso di lavoro viene eseguito con quanto segue come input:
```
{
"customer": {
"firstName": "Martha",
"lastName": "Rivera"
},
"order": {
"items": 7,
"total": 27.91
}
}
```
L'esecuzione dello stato di test o della macchina a stati restituirà il seguente output JSON:
```
{
"lastName": "Last=>Rivera",
"orderValue": 27.91
}
```
![\[Schermata che mostra l'input e l'output di uno stato in fase di test.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/jsonata-basic-io.png)
### Esempio: filtraggio con JSONata
È possibile filtrare i dati con [gli operatori JSONata Path](https://docs.jsonata.org/path-operators). Ad esempio, immagina di avere un elenco di prodotti da inserire e di voler elaborare solo prodotti che contengono zero calorie. È possibile creare una definizione di macchina a stati con il seguente ASL e testare `FilterDietProducts` lo stato con l'input di esempio che segue.
**Definizione di macchina a stati per il filtraggio con JSONata**
```
{
"Comment": "Filter products using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "FilterDietProducts",
"States": {
"FilterDietProducts": {
"Type": "Pass",
"Output": {
"dietProducts": "{% $states.input.products[calories=0] %}"
},
"End": true
}
}
}
```
**Esempio di input per il 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"
}
]
}
```
**Risultato del test della fase sulla vostra macchina a stati**
```
{
"dietProducts": [
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
![\[Esempio di output per JSONata le espressioni in prova.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/test-state-jsonata.png)
## JSONata funzioni fornite da Step Functions
JSONata contiene librerie di funzioni per le funzioni String, Numeric, Aggregation, Boolean, Array, Object, Date/Time e High Order. Step Functions fornisce JSONata funzioni aggiuntive che è possibile utilizzare nelle JSONata espressioni. Queste funzioni integrate sostituiscono le funzioni intrinseche di Step Functions. Le funzioni intrinseche sono disponibili solo negli stati che utilizzano il linguaggio di interrogazione. JSONPath
Nota: JSONata le funzioni integrate che richiedono valori interi come parametri arrotonderanno automaticamente per difetto tutti i numeri non interi forniti.
**\$1partition:** JSONata equivalente alla funzione `States.ArrayPartition` intrinseca per partizionare un array di grandi dimensioni.
Il primo parametro è l'array da partizionare, il secondo parametro è un numero intero che rappresenta la dimensione del blocco. Il valore restituito sarà un array bidimensionale. L'interprete suddivide l'array di input in più array della dimensione specificata dalla dimensione del blocco. La lunghezza dell'ultimo blocco dell'array può essere inferiore alla lunghezza dei blocchi dell'array precedente se il numero di elementi rimanenti nell'array è inferiore alla dimensione del blocco.
```
"Assign": {
"arrayPartition": "{% $partition([1,2,3,4], $states.input.chunkSize) %}"
}
```
**\$1range** - JSONata equivalente alla funzione `States.ArrayRange` intrinseca per generare un array di valori.
Questa funzione richiede tre argomenti. Il primo argomento è un numero intero che rappresenta il primo elemento del nuovo array, il secondo argomento è un numero intero che rappresenta l'elemento finale del nuovo array e il terzo argomento è il valore intero del valore delta per gli elementi del nuovo array. Il valore restituito è una matrice di valori appena generata che va dal primo argomento della funzione al secondo argomento della funzione con elementi intermedi regolati dal delta. Il valore delta può essere positivo o negativo, il che incrementerà o decrementerà ogni elemento dall'ultimo fino al raggiungimento o al superamento del valore finale.
```
"Assign": {
"arrayRange": "{% $range(0, 10, 2) %}"
}
```
**\$1hash** - JSONata equivalente della funzione `States.Hash` intrinseca per calcolare il valore hash di un determinato input.
Questa funzione accetta due argomenti. Il primo argomento è la stringa sorgente da sottoporre a hash. Il secondo argomento è una stringa che rappresenta l'algoritmo di hashing utilizzato per il calcolo dell'hash. L'algoritmo di hashing deve avere uno dei seguenti valori:`"MD5"`,,,`"SHA-1"`,`"SHA-256"`. `"SHA-384"` `"SHA-512"` Il valore restituito è una stringa dell'hash calcolato dei dati.
Questa funzione è stata creata perché JSONata non supporta nativamente la capacità di calcolare gli hash.
```
"Assign": {
"myHash": "{% $hash($states.input.content, $hashAlgorithmName) %}"
}
```
**\$1random** - JSONata equivalente alla funzione `States.MathRandom` intrinseca per restituire un numero casuale n dove. `0 ≤ n < 1`
La funzione accetta un argomento intero *opzionale* che rappresenta il valore iniziale della funzione casuale. Se si utilizza questa funzione con lo stesso valore iniziale, restituisce un numero identico.
Questa funzione sovraccaricata è stata creata perché la JSONata funzione integrata [https://docs.jsonata.org/numeric-functions#random](https://docs.jsonata.org/numeric-functions#random)non accetta un valore iniziale.
```
"Assign": {
"randNoSeed": "{% $random() %}",
"randSeeded": "{% $random($states.input.seed) %}"
}
```
**\$1uuid** - JSONata versione della funzione intrinseca. `States.UUID`
La funzione non accetta argomenti. Questa funzione restituisce un UUID v4.
Questa funzione è stata creata perché non JSONata supporta nativamente la capacità di generazione. UUIDs
```
"Assign": {
"uniqueId": "{% $uuid() %}"
}
```
**\$1parse** - JSONata funzione per deserializzare le stringhe JSON.
La funzione accetta un JSON con stringhe come unico argomento.
JSONata supporta questa funzionalità tramite`$eval`; tuttavia, non `$eval` è supportata nei flussi di lavoro Step Functions.
```
"Assign": {
"deserializedPayload": "{% $parse($states.input.json_string) %}"
}
```