Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Mengubah data dengan Step JSONata Functions
Dengan JSONata, Anda mendapatkan kueri open source dan bahasa ekspresi yang kuat untuk **memilih** dan **mengubah** data dalam alur kerja Anda. Untuk pengantar singkat dan JSONata referensi lengkap, lihat [JSONatadokumentasi.org](https://docs.jsonata.org/overview.html).
**JSONata Versi yang didukung**
Step Functions mendukung JSONata versi 2.0.6.
Video berikut menjelaskan variabel dan JSONata dalam Step Functions dengan contoh DynamoDB:
Anda harus memilih untuk menggunakan bahasa JSONata kueri dan transformasi untuk alur kerja yang ada. Saat membuat alur kerja di konsol, kami sarankan memilih JSONata untuk mesin status tingkat atas. `QueryLanguage` Untuk alur kerja yang ada atau baru yang digunakan JSONPath, konsol menyediakan opsi untuk mengonversi status individual menjadi JSONata.
Setelah memilih JSONata, bidang alur kerja Anda akan dikurangi dari lima JSONPath bidang (`InputPath`,,`Parameters`, `ResultSelector``ResultPath`, dan`OutputPath`) menjadi hanya dua bidang: `Arguments` dan`Output`. Juga, Anda **tidak** akan menggunakan `.$` pada nama kunci objek JSON.
Jika Anda baru mengenal Step Functions, Anda hanya perlu tahu bahwa JSONata ekspresi menggunakan sintaks berikut:
**JSONata sintaks:** `"{% %}"`
Contoh kode berikut menunjukkan konversi dari JSONPath ke 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"
}
}
```
Diberikan input `{ "title" : "Doctor" }` dan variabel yang `customerName` ditugaskan ke`"María"`, kedua mesin status akan menghasilkan hasil JSON berikut:
```
{
"static": "Hello",
"title": "Doctor",
"name": "María",
"not-evaluated": "$customerName"
}
```
Pada diagram berikutnya, Anda dapat melihat representasi grafis yang menunjukkan bagaimana mengonversi JSONPath (kiri) ke JSONata (kanan) akan mengurangi kompleksitas langkah-langkah di mesin status Anda:
Anda dapat (opsional) memilih dan mengubah data dari input status menjadi **Argumen** untuk dikirim ke tindakan terintegrasi Anda. **Dengan JSONata, Anda kemudian dapat (opsional) memilih dan mengubah **hasil** dari tindakan untuk menetapkan ke variabel dan untuk Output status.**
Catatan: Langkah **penetapan** dan **Output** terjadi **secara paralel**. Jika Anda memilih untuk mengubah data selama penetapan variabel, data yang diubah itu **tidak** akan tersedia di langkah Output. Anda harus menerapkan kembali JSONata transformasi dalam langkah Output.
## QueryLanguage lapangan
Dalam definisi ASL alur kerja Anda, ada `QueryLanguage` bidang di tingkat atas definisi mesin negara dan di masing-masing negara bagian. Dengan menyetel `QueryLanguage` di dalam masing-masing status, Anda dapat secara bertahap mengadopsi JSONata di mesin status yang ada daripada memutakhirkan mesin status sekaligus.
`QueryLanguage`Bidang dapat diatur ke `"JSONPath"` atau`"JSONata"`. Jika `QueryLanguage` bidang tingkat atas dihilangkan, defaultnya adalah. `"JSONPath"` Jika status berisi `QueryLanguage` bidang tingkat status, Step Functions akan menggunakan bahasa kueri yang ditentukan untuk status tersebut. Jika negara tidak berisi `QueryLanguage` bidang, maka itu akan menggunakan bahasa kueri yang ditentukan di `QueryLanguage` bidang tingkat atas.
## Menulis JSONata ekspresi dalam string JSON
Ketika string dalam nilai bidang ASL, bidang objek JSON, atau elemen array JSON dikelilingi oleh `{% %}` karakter, string itu akan dievaluasi sebagai. JSONata Catatan, string harus dimulai `{%` dengan tanpa spasi utama, dan harus `%}` diakhiri tanpa spasi tambahan. Membuka atau menutup ekspresi dengan tidak benar akan menghasilkan kesalahan validasi.
Beberapa contoh:
+ `"TimeoutSeconds" : "{% $timeout %}"`
+ `"Arguments" : {"field1" : "{% $name %}"}`dalam suatu `Task` negara
+ `"Items": [1, "{% $two %}", 3]`dalam suatu `Map` negara
Tidak semua bidang ASL menerima JSONata. Misalnya, setiap `Type` bidang status harus disetel ke string konstan. Demikian pula, `Resource` bidang `Task` negara harus berupa string konstan. `Items`Bidang `Map` status akan menerima array JSON, objek JSON, atau JSONata ekspresi yang harus mengevaluasi ke array atau objek.
## Variabel yang dicadangkan: $ negara
Step Functions mendefinisikan variabel cadangan tunggal yang disebut **`$states`**. Di JSONata negara bagian, struktur berikut ditugaskan `$states` untuk digunakan dalam JSONata ekspresi:
```
# 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
}
```
Pada entri status, Step Functions menetapkan input status ke **`$states.input`**. Nilai `$states.input` dapat digunakan di semua bidang yang menerima JSONata ekspresi. `$states.input`selalu mengacu pada input status asli.
Untuk`Task`,`Parallel`, dan `Map` menyatakan:
+ **`$states.result`**mengacu pada hasil mentah API atau sub-alur kerja jika berhasil.
+ **`$states.errorOutput`**mengacu pada Output Kesalahan jika API atau sub-alur kerja gagal.
`$states.errorOutput`dapat digunakan di `Catch` lapangan `Assign` atau`Output`.
Mencoba mengakses `$states.result` atau `$states.errorOutput` di bidang dan status di mana mereka tidak dapat diakses akan tertangkap saat pembuatan, pembaruan, atau validasi mesin status.
`$states.context`Objek memberikan informasi alur kerja Anda tentang eksekusi spesifik mereka, seperti, token tugas`StartTime`, dan input alur kerja awal. Untuk mempelajari lebih lanjut, lihat[Mengakses data eksekusi dari objek Context di Step Functions](input-output-contextobject.md).
## Menangani kesalahan ekspresi
Saat runtime, evaluasi JSONata ekspresi mungkin gagal karena berbagai alasan, seperti:
+ **Jenis kesalahan** - Ekspresi, seperti`{% $x + $y %}`, akan gagal jika `$x` atau `$y` bukan angka.
+ **Ketidakcocokan tipe** - Ekspresi mungkin mengevaluasi tipe yang tidak akan diterima bidang. Misalnya, bidang `TimeoutSeconds` membutuhkan input numerik, sehingga ekspresi `{% $timeout %}` akan gagal jika `$timeout` mengembalikan string.
+ **Nilai di luar jangkauan** - Ekspresi yang menghasilkan nilai yang berada di luar rentang yang dapat diterima untuk bidang akan gagal. Misalnya, ekspresi seperti `{% $evaluatesToNegativeNumber %}` akan gagal di `TimeoutSeconds` lapangan.
+ **Kegagalan untuk mengembalikan hasil** - JSON tidak dapat mewakili ekspresi nilai yang tidak ditentukan, sehingga ekspresi `{% $data.thisFieldDoesNotExist %}` akan menghasilkan kesalahan.
+ **Batas memori terlampaui** - JSONata Ekspresi yang menghabiskan terlalu banyak memori selama evaluasi akan gagal dengan kesalahan`Expression evaluation memory limit exceeded`. Hal ini dapat terjadi dengan ekspresi yang memproses atau mengubah sejumlah besar data. Untuk mengatasi batasan ini, pertimbangkan untuk memindahkan transformasi data ke fungsi Lambda.
+ **Expression timeout** - JSONata Ekspresi yang membutuhkan waktu lebih dari 1 detik untuk mengevaluasi akan gagal dengan `Expression evaluation timeout` kesalahan. Ini dapat terjadi dengan ekspresi yang berisi loop tak terbatas atau operasi yang sangat mahal.
+ **Stack overflow** - JSONata Ekspresi yang melebihi kedalaman rekursi maksimum akan gagal dengan file. `Stack overflow error` Jika rekursi tidak berakhir, pastikan fungsi memiliki kasus dasar atau kondisi terminasi yang benar. Jika rekursi berakhir tetapi tumpukan panggilan tumbuh terlalu dalam, pertimbangkan untuk menulis ulang fungsi sebagai rekursif ekor untuk mengurangi kedalaman tumpukan.
Dalam setiap kasus, penerjemah akan melempar kesalahan:`States.QueryEvaluationError`. Status Tugas, Peta, dan Paralel Anda dapat menyediakan `Catch` bidang untuk menangkap kesalahan, dan `Retry` bidang untuk mencoba lagi kesalahan tersebut.
## Konversi dari ke JSONPath JSONata
Bagian berikut membandingkan dan menjelaskan perbedaan antara kode yang ditulis dengan JSONPath dan JSONata.
### Tidak ada lagi bidang jalur
ASL mengharuskan pengembang menggunakan `Path` versi bidang, seperti dalam`TimeoutSecondsPath`, untuk memilih nilai dari data status saat menggunakan JSONPath. Saat Anda menggunakan JSONata, Anda tidak lagi menggunakan `Path` bidang karena ASL akan menafsirkan JSONata ekspresi `{% %}` -tertutup secara otomatis untuk Anda di bidang non-Path, seperti. `TimeoutSeconds`
+ JSONPath contoh warisan: `"TimeoutSecondsPath": "$timeout"`
+ JSONata : `"TimeoutSeconds": "{% $timeout %}"`
Demikian pula, `Map` keadaan `ItemsPath` telah diganti dengan `Items` bidang yang menerima array JSON, objek JSON, atau JSONata ekspresi yang harus mengevaluasi ke array atau objek.
### Objek JSON
ASL menggunakan istilah *template payload* untuk menggambarkan objek JSON yang dapat berisi JSONPath ekspresi untuk `Parameters` dan `ResultSelector` nilai bidang. ASL tidak akan menggunakan istilah template payload JSONata karena JSONata evaluasi terjadi untuk semua string apakah itu terjadi sendiri atau di dalam objek JSON atau array JSON.
### Tidak ada lagi. $
ASL mengharuskan Anda untuk menambahkan '`.$`' ke nama bidang di template payload untuk digunakan JSONPath dan Fungsi Intrinsik. Saat Anda menentukan`"QueryLanguage":"JSONata"`, Anda tidak lagi menggunakan konvensi '`.$`' untuk nama bidang objek JSON. Sebaliknya, Anda melampirkan JSONata ekspresi dalam `{% %}` karakter. Anda menggunakan konvensi yang sama untuk semua bidang bernilai string, terlepas dari seberapa dalam objek tersebut bersarang di dalam array atau objek lain.
### Argumen dan Bidang Output
Ketika `QueryLanguage` diatur ke`JSONata`, bidang I/O pemrosesan lama akan dinonaktifkan (`InputPath`,, `Parameters``ResultSelector`, `ResultPath` dan`OutputPath`) dan sebagian besar negara bagian akan mendapatkan dua bidang baru: `Arguments` dan`Output`.
JSONata menyediakan cara yang lebih sederhana untuk melakukan I/O transformasi dibandingkan dengan bidang yang digunakan. JSONPath JSONatafitur membuat `Arguments` dan `Output` lebih mampu daripada lima bidang sebelumnya dengan JSONPath. Nama bidang baru ini juga membantu menyederhanakan ASL Anda dan memperjelas model untuk meneruskan dan mengembalikan nilai.
`Output`Bidang `Arguments` and (dan bidang serupa lainnya seperti `Map` state`ItemSelector`) akan menerima objek JSON seperti:
```
"Arguments": {
"field1": 42,
"field2": "{% jsonata expression %}"
}
```
Atau, Anda dapat menggunakan JSONata ekspresi secara langsung, misalnya:
```
"Output": "{% jsonata expression %}"
```
Output juga dapat menerima semua jenis nilai JSON juga, misalnya:`"Output":true`,`"Output":42`.
`Output`Bidang `Arguments` dan hanya mendukung JSONata, jadi tidak valid untuk menggunakannya dengan alur kerja yang digunakan. JSONPath Sebaliknya,,`InputPath`,`Parameters`, `ResultSelector` `ResultPath``OutputPath`, dan JSONPath bidang lainnya hanya didukung di JSONPath, jadi tidak valid untuk menggunakan bidang berbasis jalur saat menggunakan JSONata sebagai alur kerja tingkat atas atau bahasa kueri status Anda.
### Status Lulus
**Hasil** opsional dalam status Pass sebelumnya diperlakukan sebagai *output* dari tugas virtual. Dengan JSONata dipilih sebagai alur kerja atau bahasa kueri status, Anda sekarang dapat menggunakan bidang **Output** baru.
### Negara pilihan
Saat menggunakan JSONPath, status pilihan memiliki input `Variable` dan banyak jalur perbandingan, seperti berikut ini`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"
} ],
}
```
Dengan JSONata, status pilihan memiliki `Condition` tempat Anda dapat menggunakan JSONata ekspresi:
```
# Choice state after JSONata conversion
"Check Price": {
"Type": "Choice",
"Default": "Pause"
"Choices": [
{
"Condition": "{% $current_price <= $states.input.desired_priced %}",
"Next": "Send Notification"
} ]
```
Catatan: Variabel dan bidang perbandingan hanya tersedia untuk JSONPath. Kondisi hanya tersedia untuk JSONata.
## JSONata contoh
Contoh berikut dapat dibuat di Workflow Studio untuk bereksperimen JSONata. Anda dapat membuat dan menjalankan mesin status, atau menggunakan **status Uji** untuk meneruskan data dan bahkan memodifikasi definisi mesin status.
### Contoh: Input dan Output
Contoh ini menunjukkan `$states.input` cara menggunakan input status dan `Output` bidang untuk menentukan output status saat Anda memilih 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 %}"
}
}
}
}
```
Ketika alur kerja dijalankan dengan berikut sebagai input:
```
{
"customer": {
"firstName": "Martha",
"lastName": "Rivera"
},
"order": {
"items": 7,
"total": 27.91
}
}
```
Uji status atau eksekusi mesin status akan mengembalikan output JSON berikut:
```
{
"lastName": "Last=>Rivera",
"orderValue": 27.91
}
```
### Contoh: Memfilter dengan JSONata
Anda dapat memfilter data Anda dengan [operator JSONata Path](https://docs.jsonata.org/path-operators). Misalnya, bayangkan Anda memiliki daftar produk untuk input, dan Anda hanya ingin memproses produk yang mengandung nol kalori. Anda dapat membuat definisi mesin status dengan ASL berikut dan menguji `FilterDietProducts` status dengan masukan sampel berikut.
**Definisi mesin negara untuk penyaringan dengan JSONata**
```
{
"Comment": "Filter products using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "FilterDietProducts",
"States": {
"FilterDietProducts": {
"Type": "Pass",
"Output": {
"dietProducts": "{% $states.input.products[calories=0] %}"
},
"End": true
}
}
}
```
**Masukan sampel untuk pengujian**
```
{
"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"
}
]
}
```
**Keluaran dari pengujian langkah di mesin negara Anda**
```
{
"dietProducts": [
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
## JSONata fungsi yang disediakan oleh Step Functions
JSONata berisi pustaka fungsi untuk fungsi String, Numerik, Agregasi, Boolean, Array, Objek, Tanggal/Waktu, dan Urutan Tinggi. Step Functions menyediakan JSONata fungsi tambahan yang dapat Anda gunakan dalam JSONata ekspresi Anda. Fungsi bawaan ini berfungsi sebagai pengganti fungsi intrinsik Step Functions. Fungsi intrinsik hanya tersedia di negara bagian yang menggunakan bahasa JSONPath kueri.
Catatan: JSONata Fungsi bawaan yang memerlukan nilai integer sebagai parameter akan secara otomatis membulatkan nomor non-integer yang disediakan.
**$partition -** JSONata setara dengan fungsi `States.ArrayPartition` intrinsik untuk mempartisi array besar.
Parameter pertama adalah array untuk partisi, parameter kedua adalah integer yang mewakili ukuran potongan. Nilai kembali akan menjadi array dua dimensi. Interpreter memotong array input menjadi beberapa array dari ukuran yang ditentukan oleh ukuran chunk. Panjang potongan array terakhir mungkin kurang dari panjang potongan array sebelumnya jika jumlah item yang tersisa dalam array lebih kecil dari ukuran potongan.
```
"Assign": {
"arrayPartition": "{% $partition([1,2,3,4], $states.input.chunkSize) %}"
}
```
**$range** - JSONata setara dengan fungsi `States.ArrayRange` intrinsik untuk menghasilkan array nilai.
Fungsi ini membutuhkan tiga argumen. Argumen pertama adalah integer yang mewakili elemen pertama dari array baru, argumen kedua adalah integer yang mewakili elemen akhir dari array baru, dan argumen ketiga adalah bilangan bulat nilai delta untuk elemen dalam array baru. Nilai kembali adalah larik nilai yang baru dihasilkan mulai dari argumen pertama fungsi hingga argumen kedua fungsi dengan elemen di antaranya disesuaikan dengan delta. Nilai delta bisa positif atau negatif yang akan menambah atau mengurangi setiap elemen dari yang terakhir sampai nilai akhir tercapai atau terlampaui.
```
"Assign": {
"arrayRange": "{% $range(0, 10, 2) %}"
}
```
**$hash** - JSONata setara dengan fungsi `States.Hash` intrinsik untuk menghitung nilai hash dari input yang diberikan.
Fungsi ini membutuhkan dua argumen. Argumen pertama adalah string sumber yang akan di-hash. Argumen kedua adalah string yang mewakili algoritma hashing untuk perhitungan hash. Algoritma hashing harus menjadi salah satu dari nilai berikut:`"MD5"`,,`"SHA-1"`, `"SHA-256"``"SHA-384"`,`"SHA-512"`. Nilai kembali adalah string dari hash yang dihitung dari data.
Fungsi ini dibuat karena JSONata tidak secara native mendukung kemampuan untuk menghitung hash.
```
"Assign": {
"myHash": "{% $hash($states.input.content, $hashAlgorithmName) %}"
}
```
**$random** - JSONata setara dengan fungsi `States.MathRandom` intrinsik untuk mengembalikan angka acak n dimana. `0 ≤ n < 1`
Fungsi ini mengambil argumen integer *opsional* yang mewakili nilai seed dari fungsi acak. Jika Anda menggunakan fungsi ini dengan nilai seed yang sama, ia mengembalikan angka yang identik.
Fungsi kelebihan beban ini dibuat karena JSONata fungsi bawaan [https://docs.jsonata.org/numeric-functions#random](https://docs.jsonata.org/numeric-functions#random)tidak menerima nilai seed.
```
"Assign": {
"randNoSeed": "{% $random() %}",
"randSeeded": "{% $random($states.input.seed) %}"
}
```
**$uuid** - JSONata versi fungsi intrinsik. `States.UUID`
Fungsi ini tidak membutuhkan argumen. Fungsi ini mengembalikan UUID v4.
Fungsi ini dibuat karena JSONata tidak secara native mendukung kemampuan untuk menghasilkan UUIDs.
```
"Assign": {
"uniqueId": "{% $uuid() %}"
}
```
**$parse** - JSONata berfungsi untuk deserialisasi string JSON.
Fungsi ini mengambil JSON stringified sebagai satu-satunya argumen.
JSONata mendukung fungsi ini melalui`$eval`; Namun, tidak `$eval` didukung dalam alur kerja Step Functions.
```
"Assign": {
"deserializedPayload": "{% $parse($states.input.json_string) %}"
}
```