Variabel Global di CloudFlow untuk Berbagi Data Silang State - CloudFlow

Dalam alur kerja multi-state, setiap state menerima output dari state sebelumnya sebagai input. Jika State A menghasilkan nilai yang hanya dibutuhkan oleh State Z, nilai tersebut harus melewati setiap state perantara meskipun tidak digunakan oleh state-state tersebut. Rantai ini menambah kompleksitas dan menyulitkan pemeliharaan alur kerja.

Variabel global mengatasi masalah ini dengan memungkinkan penyimpanan nilai di satu state dan pembacaannya langsung dari state lain tanpa melewati seluruh rantai.

Referensi cepat

Operasi	Sintaks	Contoh
Write	`GlobalConstructor` dalam definisi state	`myVar.$: $Output.Body`
Read	`$Global.<key>` expression	`$Global.myVar`
Panjang kunci maksimum	128 Byte	--
Ukuran nilai maksimum	256 KiB	--

Cara kerja

Variabel global menyediakan penyimpanan kunci-nilai tingkat eksekusi. Setiap state dapat menulis data ke penyimpanan ini saat selesai, dan setiap state berikutnya dapat membaca data tersebut secara langsung tanpa menerimanya melalui rantai input.

Konstruktor

CloudFlow menggunakan tiga konstruktor untuk mengelola alur data di dalam dan antar state:

Konstruktor	Tujuan	Kapan digunakan
`GlobalConstructor`	Menulis nilai ke penyimpanan global	Membagikan data antar state yang tidak berdekatan
`InputConstructor`	Mengubah bentuk data masukan untuk suatu state	Memfilter atau menyusun ulang input sebelum state dijalankan
`OutputConstructor`	Mengubah bentuk data keluaran dari suatu state	Memfilter atau menyusun ulang output sebelum diteruskan ke state berikutnya

Ketiga konstruktor ini dapat mereferensikan $Context dan $Global untuk mengekstraksi informasi.

Diagram berikut menunjukkan bagaimana konstruktor berinteraksi di dalam suatu state:

Perilaku utama:

$Output adalah hasil mentah dari panggilan Task. Untuk task callback asinkron, $Output berisi hasil callback tersebut.
Ketika GlobalConstructor dijalankan, output-nya digabung dengan nilai $Global yang sudah ada: $Global = Merge($Global, GlobalConstructor($Context, $Global)).
$Global dapat diakses sepanjang eksekusi alur kerja.

Urutan evaluasi

Konstruktor dievaluasi dalam urutan tetap di setiap state. Memahami urutan ini sangat penting karena GlobalConstructor dan OutputConstructor membaca snapshot $Output dan $Global yang berbeda:

Task dijalankan dan menghasilkan $Output (hasil mentah task).
GlobalConstructor dievaluasi, menggunakan $Output (hasil mentah task, bukan hasil OutputConstructor).
OutputConstructor dievaluasi, menggunakan $Global (nilai sebelum GlobalConstructor memperbaruinya).

Contoh pengerjaan:

Sebuah state Task mengembalikan $Output = {"status": "ok", "data": {"id": 42}}. Penyimpanan global saat ini adalah $Global = {"previousId": 10}.

GlobalConstructor:
  latestId.$: $Output.data.id       # Menulis 42 ke $Global.latestId

OutputConstructor:
  combined.$: $Global.previousId    # Membaca 10 (nilai SEBELUM GlobalConstructor dijalankan)

Setelah state ini selesai:

$Global = {"previousId": 10, "latestId": 42} (digabung)
Output state = {"combined": 10} (menggunakan nilai $Global sebelum diperbarui)

Penting

$Output dalam GlobalConstructor merujuk pada output mentah dari state Task, bukan hasil dari OutputConstructor. Demikian pula, $Global dalam OutputConstructor merujuk pada nilai sebelum GlobalConstructor memperbaruinya.

Menulis variabel global

Gunakan GlobalConstructor untuk menulis variabel global. Konstruktor ini dijalankan di akhir setiap eksekusi state, dan struktur datanya berupa Map[String]Any.

Contoh berikut menyimpan header dan body dari respons fungsi sebagai variabel global terpisah:

Type: StateMachine
Name: MyWorkFlow
SpecVersion: v1
StartAt: InvokeFunction
States:
  - Type: Task
    Name: InvokeFunction
    Action: FC:InvokeFunction
    TaskMode: RequestComplete
    Parameters:
      resourceArn: >-
        acs:fc:cn-hangzhou:123456:functions/myFunction/LATEST
      invocationType: Sync
      body.$: $Input
    GlobalConstructor:
      InvokeFunctionResultHeader.$: $Output.Header   # Simpan header respons
      InvokeFunctionResultBody.$: $Output.Body        # Simpan body respons
    End: true

Dalam definisi ini:

InvokeFunctionResultHeader.$: $Output.Header menyimpan header respons fungsi dalam variabel global InvokeFunctionResultHeader.
InvokeFunctionResultBody.$: $Output.Body menyimpan body respons fungsi dalam variabel global InvokeFunctionResultBody.

Membaca variabel global

Gunakan kata kunci $Global untuk membaca variabel global. Ekspresi apa pun yang mendukung konstruksi dapat mengakses penyimpanan global melalui $Global.<key>.

Contoh berikut menunjukkan alur kerja dua state di mana state pertama menulis variabel global dan state kedua membacanya:

Type: StateMachine
Name: MyWorkFlow
SpecVersion: v1
StartAt: InvokeFunction1
States:
  - Type: Task
    Name: InvokeFunction1
    Action: FC:InvokeFunction
    TaskMode: RequestComplete
    Parameters:
      invocationType: Sync
      resourceArn: acs:fc:cn-hangzhou:123456:functions/myFunction/LATEST
    GlobalConstructor:
      InvokeFunctionPayload.$: $Output.Body     # Simpan body respons untuk digunakan nanti
    Next: InvokeFunction
  - Type: Task
    Name: InvokeFunction
    Action: FC:InvokeFunction
    TaskMode: RequestComplete
    Parameters:
      resourceArn: acs:fc:cn-hangzhou:123456:functions/myFunction/LATEST
      invocationType: Sync
      body.$: $Global.InvokeFunctionPayload     # Baca nilai yang disimpan sebagai input
    OutputConstructor:
      demo.$: $Global                           # Output seluruh penyimpanan global
    End: true

Dalam definisi ini:

InvokeFunction1 menyimpan body responsnya dalam variabel global InvokeFunctionPayload.
InvokeFunction membaca $Global.InvokeFunctionPayload dan meneruskannya sebagai parameter body dalam pemanggilan fungsi.
OutputConstructor memetakan seluruh isi $Global ke bidang demo dalam output state.

Verifikasi nilai variabel global dengan memeriksa output eksekusi di Konsol CloudFlow:

Batasan

Item	Nilai maksimum
Panjang kunci variabel	128 Byte
Panjang nilai variabel	256 KiB
Ukuran konteks (`InputConstructor` dan output `OutputConstructor` saat menggunakan `$Global`)	64 KiB

Jika batasan ini tidak memenuhi kebutuhan Anda, ajukan tiket untuk meminta peningkatan kuota.

Catatan

Saat meneruskan data melalui $Global, output dari InputConstructor maupun OutputConstructor harus tetap berada dalam batas ukuran konteks 64 KiB.

Kondisi race dalam eksekusi paralel

Variabel global dibagikan di seluruh state dalam satu eksekusi. Ketika logika paralel (state Parallel atau Map) ada, penulisan bersamaan dapat saling menimpa. Ikuti panduan berikut:

Skenario	Panduan
Parallel Status	Gunakan kunci unik untuk setiap cabang. Setiap cabang menulis ke kuncinya sendiri untuk menghindari penimpaan.
Map states	Jangan menulis variabel global. Semua iterasi berbagi definisi `GlobalConstructor` yang sama, sehingga mereka menulis ke kunci yang sama dan saling menimpa.
Eksekusi anak terdistribusi	Eksekusi anak dalam mode terdistribusi tidak dapat mengakses variabel global dari eksekusi induk. Mereka berjalan pada level `Execution` yang berbeda dengan penyimpanan global terpisah.