Batasan kode fungsi orkestrator

Durable Functions adalah ekstensi Azure Functions yang memungkinkan Anda membangun aplikasi yang canggih. Anda dapat menggunakan fungsi orkestrator untuk mengatur eksekusi fungsi tahan lama lainnya dalam aplikasi fungsi. Fungsi orkestrator teguh, andal, dan berpotensi berjalan lama.

Batasan kode orkestrator

Fungsi orkestrator menggunakan sumber peristiwa untuk memastikan eksekusi yang dapat diandalkan dan untuk mempertahankan status variabel lokal. Perilaku pemutaran ulang kode orkestrator membuat batasan pada jenis kode yang dapat Anda tulis dalam fungsi orkestrator. Misalnya, fungsi orkestrator harus deterministik: fungsi orkestrator akan diputar ulang beberapa kali, dan harus menghasilkan hasil yang sama setiap kali.

Menggunakan API deterministik

Bagian ini menyediakan beberapa panduan sederhana yang membantu memastikan kode bersifat deterministik.

Fungsi orkestrator dapat memanggil API apa pun dalam bahasa target mereka. Namun, penting untuk diketahui bahwa fungsi orkestrator hanya memanggil API deterministik. API deterministik adalah API yang selalu mengembalikan nilai yang sama dengan input yang sama, tidak peduli kapan atau seberapa sering dipanggil.

Bagian berikut memberikan panduan tentang API dan pola yang harus Anda hindari karena tidak bersifat deterministik. Pembatasan ini hanya berlaku untuk fungsi orkestrator. Jenis fungsi lain tidak memiliki batasan tersebut.

Catatan

Beberapa jenis batasan kode dijelaskan di bawah ini. Daftar ini sayangnya ini tidak lengkap dan beberapa kasus penggunaan mungkin tidak tercakup. Hal terpenting perlu untuk dipertimbangkan saat menulis kode orkestrator adalah apakah API yang Anda gunakan bersifat deterministik. Setelah Anda merasa nyaman dengan pemikiran seperti ini, mudah untuk memahami API mana yang aman untuk digunakan dan mana yang tidak tanpa perlu merujuk ke daftar terdokumentasi ini.

Tanggal dan waktu

API yang mengembalikan tanggal atau waktu saat ini bersifat nondeterministik dan tidak boleh digunakan dalam fungsi orkestrator. Hal ini dikarenakan setiap pemutaran ulang fungsi orkestrator akan menghasilkan nilai yang berbeda. Anda sebaiknya menggunakan API setara Durable Functions untuk mendapatkan tanggal atau waktu saat ini, yang tetap konsisten di seluruh pemutaran ulang.

C#

Jangan gunakan DateTime.Now, DateTime.UtcNow, atau API yang setara untuk mendapatkan waktu saat ini. Kelas seperti Stopwatch juga harus dihindari. Untuk fungsi orkestrator dalam proses .NET, gunakan properti IDurableOrchestrationContext.CurrentUtcDateTime untuk mendapatkan waktu saat ini. Untuk fungsi orkestrator terisolasi .NET, gunakan properti TaskOrchestrationContext.CurrentDateTimeUtc untuk mendapatkan waktu saat ini.

DateTime startTime = context.CurrentUtcDateTime;
// do some work
TimeSpan totalTime = context.CurrentUtcDateTime.Subtract(startTime);

JavaScript

Jangan gunakan API seperti new Date() atau Date.now() untuk mendapatkan tanggal dan waktu saat ini. Sebagai gantinya, gunakan DurableOrchestrationContext.currentUtcDateTime.

// create a timer that expires 2 minutes from now
const expiration = moment.utc(context.df.currentUtcDateTime).add(2, "m");
const timeoutTask = context.df.createTimer(expiration.toDate());

Python

Jangan gunakan datetime.now(), gmtime(), atau API serupa untuk mendapatkan waktu saat ini. Sebagai gantinya, gunakan DurableOrchestrationContext.current_utc_datetime.

# create a timer that expires 2 minutes from now
expiration = context.current_utc_datetime + timedelta(seconds=120)
timeout_task = context.create_timer(expiration)

PowerShell

Jangan gunakan cmdlet seperti Get-Date atau .NET API seperti [System.DateTime]::Now untuk mendapatkan waktu saat ini. Sebagai gantinya, gunakan $Context.CurrentUtcDateTime.

$expiryTime = $Context.Input.ExpiryTime
while ($Context.CurrentUtcDateTime -lt $expiryTime) {
    # do work
}

Java

Jangan gunakan API seperti LocalDateTime.now() atau Instant.now() untuk mendapatkan tanggal dan waktu saat ini. Sebagai gantinya, gunakan TaskOrchestrationContext.getCurrentInstant().

Instant startTime = ctx.getCurrentInstant();
// do some work
Duration totalTime  = Duration.between(startTime, ctx.getCurrentInstant());

GUID dan UUID

API yang mengembalikan GUID atau UUID acak adalah bukan deterministik karena nilai yang dihasilkan berbeda untuk setiap pemutaran ulang. Bergantung pada bahasa komputer mana yang Anda gunakan, API bawaan untuk menghasilkan GUID atau UUID deterministik mungkin tersedia. Jika tidak, gunakan fungsi aktivitas untuk mengembalikan GUID atau UUID yang dihasilkan secara acak.

C#

Jangan gunakan API seperti Guid.NewGuid() untuk menghasilkan GUID acak. Sebagai gantinya, gunakan API objek konteks NewGuid() untuk menghasilkan GUID acak yang aman untuk pemutaran ulang orkestrator.

Guid randomGuid = context.NewGuid();

Catatan

GUID yang dihasilkan dengan API konteks orkestrasi adalah UUID Jenis 5.

JavaScript

Jangan gunakan modul uuid atau fungsi crypto.randomUUID() untuk menghasilkan UUID acak. Sebagai gantinya, gunakan metode bawaan objek konteks newGuid() untuk menghasilkan GUID acak yang aman untuk pemutaran ulang orkestrator.

const randomGuid = context.df.newGuid();

Catatan

UUID yang dihasilkan dengan API konteks orkestrasi adalah UUID Jenis 5.

Python

Jangan gunakan modul uuid untuk menghasilkan UUID acak. Sebagai gantinya, gunakan metode bawaan objek konteks new_guid() untuk menghasilkan UUID acak yang aman untuk pemutaran ulang orkestrator.

randomGuid = context.new_guid()

Catatan

UUID yang dihasilkan dengan API konteks orkestrasi adalah UUID Jenis 5.

PowerShell

Jangan gunakan cmdlet seperti New-Guid atau .NET API seperti [System.Guid]::NewGuid() secara langsung dalam fungsi orkestrator. Sebagai gantinya, hasilkan GUID acak dalam fungsi aktivitas dan kembalikan ke fungsi orkestrator.

Java

Jangan gunakan java.util.UUID.randomUUID() atau metode serupa untuk membuat UUID baru secara langsung di fungsi orkestrator. Sebagai gantinya, hasilkan UUID acak dalam fungsi aktivitas dan kembalikan ke fungsi orkestrator.

Angka acak

Gunakan fungsi aktivitas untuk mengembalikan angka acak ke fungsi orkestrator. Nilai yang dikembalikan fungsi aktivitas selalu aman untuk diputar ulang karena disimpan ke dalam riwayat orkestrasi.

Atau, generator angka acak dengan nilai benih tetap dapat digunakan secara langsung dalam fungsi orkestrator. Pendekatan ini aman selama urutan angka yang sama dihasilkan untuk setiap pemutaran ulang orkestrasi.

Pengikatan

Fungsi orkestrator tidak boleh menggunakan pengikatan apa pun, bahkan termasuk pengikatan klien orkestrasi dan klien entitas. Selalu gunakan pengikatan input dan output dari dalam fungsi klien atau aktivitas. Ini penting karena fungsi orkestrator dapat diputar ulang beberapa kali, menyebabkan I/O nondeterministik dan duplikat dengan sistem eksternal.

Variabel statis

Hindari menggunakan variabel statik dalam fungsi orkestrator karena nilainya dapat berubah dari waktu ke waktu, yang menghasilkan perilaku runtime nondeterministik. Sebagai gantinya, gunakan konstanta, atau batasi penggunaan variabel statik untuk fungsi aktivitas.

Catatan

Bahkan di luar fungsi orkestrator, menggunakan variabel statik di Azure Functions dapat menjadi masalah karena berbagai alasan karena tidak ada jaminan bahwa status statik akan bertahan di beberapa eksekusi fungsi. Variabel statik harus dihindari kecuali dalam kasus penggunaan yang sangat spesifik, seperti upaya terbaik dalam penembolokan memori dalam fungsi aktivitas atau entitas.

Variabel lingkungan

Jangan gunakan variabel lingkungan dalam fungsi orkestrator. Nilai-nilainya dapat berubah dari waktu ke waktu, menghasilkan perilaku runtime yang bukan deterministik. Jika fungsi orkestrator memerlukan konfigurasi yang ditentukan dalam variabel lingkungan, Anda harus meneruskan nilai konfigurasi ke fungsi orkestrator sebagai input atau sebagai nilai yang dikembalikan fungsi aktivitas.

Jaringan dan HTTP

Gunakan fungsi aktivitas untuk melakukan panggilan jaringan keluar. Jika Anda perlu melakukan panggilan HTTP dari fungsi orkestrator, Anda juga dapat menggunakan API HTTP yang tahan lama.

API pemblokiran rangkaian

Memblokir API seperti "tidur" dapat menyebabkan masalah performa dan skala untuk fungsi orkestrator dan harus dihindari. Dalam paket Konsumsi Azure Functions, paket dapat mengakibatkan biaya waktu eksekusi yang tidak perlu. Gunakan alternatif untuk memblokir API saat tersedia. Misalnya, gunakan Timer Durable untuk membuat penundaan yang aman untuk pemutaran ulang dan tidak dihitung dalam waktu eksekusi fungsi orkestrator.

API asinkron

Kode orkestrator tidak boleh memulai operasi asinkron apa pun kecuali yang ditentukan oleh objek konteks pemicu orkestrasi. Misalnya, jangan pernah gunakan Task.Run, Task.Delay, dan HttpClient.SendAsync di .NET atau setTimeout dan setInterval di JavaScript. Fungsi orkestrator hanya boleh menjadwalkan pekerjaan asinkron menggunakan API SDK Durable, seperti menjadwalkan fungsi aktivitas. Jenis pemanggilan asinkron lainnya harus dilakukan di dalam fungsi aktivitas.

Fungsi JavaScript asinkron

Selalu deklarasikan fungsi orkestrator JavaScript sebagai fungsi generator sinkron. Anda tidak dapat mendeklarasikan fungsi orkestrator JavaScript sebagai async karena runtime Node.js tidak menjamin bahwa fungsi asinkron bersifat deterministik.

Python coroutines

Anda tidak dapat mendeklarasikan fungsi orkestrator Python sebagai koroutin. Dengan kata lain, jangan pernah mendeklarasikan fungsi orkestrator Python dengan kata kunci async karena semantik koroutin tidak sejalan dengan model pemutaran ulang Durable Functions. Anda harus selalu mendeklarasikan fungsi orkestrator Python sebagai generator, artinya Anda harus mengharapkan context API untuk menggunakan yield alih-alih await.

API threading .NET

Kerangka Kerja Tugas Durable menjalankan kode orkestrator pada satu alur dan tidak dapat berinteraksi dengan alur lainnya. Menjalankan kelanjutan asinkron pada rangkaian kumpulan pekerja, eksekusi orkestrasi dapat mengakibatkan eksekusi atau kebuntuan nondeterministik. Karena alasan ini, fungsi orkestrator hampir tidak boleh menggunakan API threading. Misalnya, jangan pernah menggunakan ConfigureAwait(continueOnCapturedContext: false) dalam fungsi orkestrator. Ini memastikan bahwa kelanjutan tugas berjalan pada fungsi asli orkestrator SynchronizationContext.

Catatan

Durable Task Framework mencoba mendeteksi penggunaan rangkaian non-orkestrator secara tidak sengaja dalam fungsi orkestrator. Jika menemukan pelanggaran, kerangka kerja membuang pengecualian NonDeterministicOrchestrationException. Namun, perilaku deteksi ini tidak akan menangkap semua pelanggaran, dan Anda tidak boleh bergantung padanya.

Penerapan versi

Orkestrasi yang tahan lama mungkin berjalan terus menerus selama berhari-hari, berbulan-bulan, bertahun-tahun, atau bahkan selamanya. Pembaruan kode apa pun yang dibuat untuk aplikasi Durable Functions yang memengaruhi orkestrasi yang belum selesai dapat merusak perilaku pemutaran ulang orkestrasi. Itu sebabnya penting untuk merencanakan dengan hati-hati saat membuat pembaruan kode. Untuk deskripsi lebih rinci tentang cara membuat versi kode Anda, lihat artikel penerapan versi.

Tugas yang tahan lama

Catatan

Bagian ini menjelaskan detail implementasi internal dari Kerangka Kerja Tugas yang Tahan Lama. Anda dapat menggunakan fungsi tahan lama tanpa mengetahui informasi ini. Hal ini dimaksudkan hanya untuk membantu Anda memahami perilaku pemutaran ulang.

Tugas yang dapat dengan aman menunggu dalam fungsi orkestrator kadang-kadang disebut sebagai tugas yang tahan lama. Kerangka Kerja Tugas yang Tahan Lama membuat dan mengelola tugas-tugas ini. Contohnya adalah tugas yang dikembalikan oleh CallActivityAsync, WaitForExternalEvent, dan fungsi CreateTimer dalam orkestrator .NET.

Tugas-tugas tahan lama ini dikelola secara internal oleh beberapa objek TaskCompletionSource di .NET. Selama pemutaran ulang, tugas-tugas ini dibuat sebagai bagian dari eksekusi kode orkestrator. Mereka selesai sebagai dispatcher menghitung peristiwa riwayat yang sesuai.

Tugas dijalankan secara sinkron menggunakan satu alur hingga semua riwayat diputar ulang. Tugas tahan lama yang belum selesai pada akhir pemutaran ulang riwayat memiliki tindakan yang tepat yang dilakukan. Misalnya, pesan mungkin diwariskan untuk memanggil fungsi aktivitas.

Deskripsi perilaku runtime bagian ini akan membantu Anda memahami mengapa fungsi orkestrator tidak dapat menggunakan await atau yield dalam tugas yang tidak tahan lama. Ada dua alasan: alur dispatcher tidak dapat menunggu tugas sampai selesai, dan setiap panggilan balik oleh tugas itu mungkin berpotensi merusak status pelacakan fungsi orkestrator. Beberapa pemeriksaan runtime diberlakukan untuk membantu mendeteksi pelanggaran ini.

Untuk mempelajari lebih lanjut tentang cara Kerangka Kerja Tugas Tahan Lama menjalankan fungsi orkestrator, lihat kode sumber Tugas Tahan Lama di GitHub. Khususmya, lihat TaskOrchestrationExecutor.cs dan TaskOrchestrationContext.cs.

Langkah berikutnya

Pelajari cara memanggil sub-orkestrasi

Pelajari cara menangani penerapan versi