Pengembangan Skrip / Fungsi Ekspor DFF.API

DFF.API(...) mengembalikan dekorator untuk mengekspos fungsi tingkat atas yang didekorasi ke publik, memungkinkan pemanggilan melalui Func API, Tugas Terjadwal, MCP, halaman fungsi, atau eksekusi debug.

Hanya fungsi entry yang perlu dipanggil dari luar impor Python biasa yang harus menggunakan @DFF.API(...); fungsi pembantu privat tidak perlu menambahkan dekorator ini.

Dalam Script yang sama, nama fungsi yang didekorasi harus unik; nama yang sama akan menyebabkan Script gagal dimuat.

Daftar parameter terperinci adalah sebagai berikut:

Parameter	Tipe	Wajib / Nilai Default	Deskripsi
title	str	None	Nama tampilan ekspor fungsi, terutama untuk ditampilkan di antarmuka
require_api_auth	bool	False	Memerlukan API Auth ketika Func diekspos melalui Func API
category	str	"general"	Kategori fungsi, default "general". Terutama digunakan untuk klasifikasi/penyaringan daftar fungsi
tags	list	None	Daftar tag fungsi, terutama digunakan untuk klasifikasi/penyaringan daftar fungsi
tags[#]	str	Wajib	Tag fungsi
timeout	int / referensi dinamis	None	Waktu tunggu fungsi. Satuan: detik, rentang nilai 1 ~ 3600
expires	int / referensi dinamis	None	Durasi tunggu antrean maksimum. Satuan: detik, rentang nilai 1 ~ 86400
cache_result	int	None	Durasi penyimpanan hasil cache. Satuan: detik, gunakan bilangan bulat positif, None atau 0 berarti tidak cache
queue	int / referensi dinamis	None	Nomor antrean Worker pengguna
fixed_cron_expr	str(Cron-format)	None	Memaksa penggunaan ekspresi Cron lima-bagian yang ditentukan ketika fungsi dijalankan oleh Tugas Terjadwal
fixed_delayed_cron_job	int / list[int]	None	Memaksa Tugas Terjadwal menggunakan jumlah detik penundaan eksekusi yang ditentukan
delayed_cron_job	int / list[int] / referensi dinamis	None	Jumlah detik penundaan eksekusi default yang digunakan ketika Tugas Terjadwal tidak mengonfigurasi penundaan sendiri
mcp_annotations	dict	None	Hint perilaku alat MCP standar serta ekstensi confirmationHint
integration	str	None	Integrasi bawaan, opsional signIn atau autoRun
auto_run	dict	None	Konfigurasi auto run, sekaligus mengatur integration='autoRun'
is_hidden	bool	False	Sembunyikan dari hasil penemuan Func biasa
custom	Nilai yang dapat diserialisasi JSON	None	Metadata kustom
custom_json	str(JSON)	None	Metadata kustom yang dikodekan dengan teks JSON
custom_yaml	str(YAML)	None	Metadata kustom yang dikodekan dengan teks YAML

Penjelasan rinci setiap parameter dapat dilihat di bawah ini:

Parameter title

Judul fungsi memudahkan untuk ditampilkan di berbagai antarmuka operasi / dokumen DataFlux Func.

@DFF.API('Fungsi Saya')
def my_func():
    pass

Parameter require_api_auth

Ketika Func diekspos ke publik melalui Func API, require_api_auth=True dapat diatur untuk mewajibkan pemanggil melalui autentikasi API Auth.

@DFF.API('Fungsi Saya', require_api_auth=True)
def my_func():
    pass

Setelah Func API dipublikasikan, pemanggil akan bergantung pada struktur input dan return fungsi, oleh karena itu keduanya harus dijaga tetap stabil.

Parameter category / tags

Kategori dan daftar tag dari fungsi itu sendiri tidak ikut serta dan tidak mengontrol jalannya fungsi; terutama digunakan untuk memudahkan pengelolaan klasifikasi fungsi. Keduanya dapat digunakan bersamaan atau masing-masing secara terpisah.

Saat runtime, kategori dan tag masing-masing diekspos melalui _DFF_FUNC_CATEGORY dan _DFF_FUNC_TAGS. Keduanya hanya merupakan metadata deskriptif dan tidak dapat digunakan untuk membangun identitas atau batas izin.

@DFF.API('Fungsi Saya', category='demo', tags=['tag1', 'tag2'])
def my_func():
    pass

Setelah ditentukan, daftar fungsi dapat difilter dengan menentukan parameter penyaringan, misalnya:

# Filter berdasarkan category
GET /api/v1/func-list?category=demo

# Filter berdasarkan tags (menentukan beberapa tag berarti 'mengandung semuanya')
GET /api/v1/func-list?tags=tag1,tag2

Parameter timeout

Untuk melindungi sistem, semua fungsi yang berjalan di DataFlux Func memiliki batas durasi eksekusi dan tidak diizinkan berjalan tanpa batas. Jika timeout tidak dikonfigurasi, berbagai cara pemanggilan memiliki nilai default yang berbeda.

Cara Pemanggilan	Nilai Default timeout
API Fungsi Sinkron	35
API Fungsi Asinkron	3600
Tugas Terjadwal	35

@DFF.API('Fungsi Saya', timeout=30)
def my_func():
    pass

Untuk fungsi yang dieksekusi di editor DataFlux Func, sistem akan mengabaikan konfigurasi timeout dan menetapkannya menjadi 60 detik

Danger

Nilai maksimum yang dapat dikonfigurasi untuk timeout adalah 3600 detik (yaitu 1 jam), dengan tujuan melindungi sistem. Jika tanpa pertimbangan langsung mengatur waktu timeout semua fungsi ke nilai maksimum, Anda mungkin tidak dapat mengetahui masalah dalam penulisan dan desain kode secara tepat waktu, sekaligus menyebabkan masalah seperti kemacetan antrean.

Oleh karena itu, parameter timeout harus diatur berdasarkan kebutuhan aktual; banyak permintaan API Fungsi yang memakan waktu lama dapat menyebabkan kemacetan antrean tugas, dan jika perlu, gunakan teknik cache.

Warning

Respons antarmuka HTTP yang melebihi 3 detik dapat dianggap sangat lambat; perhatikan untuk tidak mengonfigurasi waktu timeout yang terlalu panjang tanpa makna bagi fungsi.

Selain itu, browser sendiri juga memiliki batasan waktu maksimum untuk permintaan (misalnya: Chrome 4 menit), sehingga mengatur timeout yang terlalu panjang di API Fungsi juga tidak ada artinya.

Parameter expires / queue

expires digunakan untuk membatasi waktu tunggu maksimum tugas dalam antrean, dengan rentang nilai 1 ~ 86400 detik. Setelah waktu tunggu terlampaui, tugas tidak akan mulai dieksekusi; ini berbeda dengan timeout yang membatasi durasi eksekusi sebenarnya.

queue digunakan untuk menentukan nomor antrean Worker pengguna. Nomor yang tersedia bergantung pada konfigurasi Worker DataFlux Func saat ini.

Parameter cache_result

DataFlux Func memiliki penanganan cache bawaan di tingkat API. Setelah parameter cache ditentukan, ketika fungsi dan parameter yang sama persis dipanggil, sistem akan langsung mengembalikan hasil yang di-cache.

cache_result hanya boleh menggunakan bilangan bulat positif dalam detik; jika None atau 0 diberikan, cache tidak diaktifkan.

@DFF.API('Fungsi Saya', cache_result=30)
def my_func():
    pass

Setelah cache cocok, API akan langsung mengembalikan hasil, sedangkan fungsi tidak benar-benar dieksekusi

Setelah cache cocok, header permintaan HTTP yang dikembalikan akan menambahkan penanda berikut:

X-Dataflux-Func-Cache: Cached

Parameter fixed_cron_expr

Untuk beberapa fungsi yang akan digunakan untuk Tugas Terjadwal, penulis fungsi mungkin memiliki persyaratan mengenai frekuensi berjalan otomatis. Dalam hal ini, parameter ini dapat ditentukan untuk mengunci Tugas Terjadwal milik fungsi tersebut ke ekspresi Cron lima segmen yang ditentukan. Parameter ini hanya boleh digunakan jika frekuensi penjadwalan harus dikontrol oleh Script; jika tidak, seharusnya dikontrol oleh konfigurasi Tugas Terjadwal.

@DFF.API('Fungsi Saya', fixed_cron_expr='*/5 * * * *')
def my_func():
    pass

Parameter fixed_delayed_cron_job / delayed_cron_job

Untuk beberapa fungsi yang digunakan untuk Tugas Terjadwal, penulis fungsi mungkin ingin menjalankannya pada waktu yang lebih presisi (misalnya, berjalan dengan penundaan 10 detik dari basis * * * * *). fixed_delayed_cron_job akan menimpa penundaan yang dikonfigurasi oleh Tugas Terjadwal itu sendiri; delayed_cron_job hanya menjadi nilai default jika Tugas Terjadwal tidak mengonfigurasi penundaan. Keduanya dapat menerima satu angka detik atau array angka detik; jika array diberikan, fungsi akan berjalan setelah mencapai setiap penundaan yang ditentukan.

Eksekusi tertunda hanya menjamin fungsi tidak berjalan lebih awal dari waktu yang ditentukan, dan tidak menjamin fungsi segera berjalan setelah mencapai waktu yang ditentukan

Parameter ini tidak berlaku untuk kasus 'adanya Tugas Terjadwal berdurasi panjang', baik tugas berdurasi panjang tersebut terkait dengan eksekusi tertunda atau tidak

@DFF.API('Fungsi Saya', fixed_delayed_cron_job=10)
def my_func():
    '''
    Eksekusi dengan penundaan 10 detik
    '''
    pass

@DFF.API('Fungsi Saya 2', delayed_cron_job=[0, 10])
def my_func_2():
    '''
    Eksekusi dengan penundaan 0 dan 10 detik, total dieksekusi 2 kali
    '''
    pass

Referensi Dinamis

delayed_cron_job, timeout, expires, dan queue mendukung penggunaan referensi dinamis yang dikembalikan oleh metode berikut:

• DFF.ENV.ref(key, default=None)
• DFF.STORE.ref(key, scope=None, default=None)
• DFF.CACHE.ref(key, scope=None, default=None)

DFF.STORE.ref(...) dan DFF.CACHE.ref(...) menggunakan REF saat scope dihilangkan. Referensi dinamis diselesaikan saat metadata Func dikonsumsi; jika hasil penyelesaian tidak valid, referensi tersebut akan diabaikan dan tidak mengubah deklarasi dekorator.

@DFF.API(
    'Tugas Kontrol Lingkungan',
    timeout=DFF.ENV.ref('FUNC_TIMEOUT', default=35),
    queue=DFF.ENV.ref('FUNC_QUEUE', default=1),
)
def environment_controlled():
    return 'ok'

Parameter mcp_annotations

Ketika Func diekspos langsung sebagai alat MCP, perilaku alat dapat dideklarasikan melalui mcp_annotations. MCP2 list-func dan MCP3 search-func juga akan mengembalikan Hint standar yang terkandung di dalamnya melalui metadata annotations.

Hint	Tipe	Keterangan
readOnlyHint	bool	Alat tidak akan mengubah lingkungan
destructiveHint	bool	Alat yang memodifikasi lingkungan dapat menyebabkan perubahan destruktif
idempotentHint	bool	Pemanggilan berulang dengan parameter yang sama tidak menimbulkan efek tambahan
openWorldHint	bool	Alat dapat berinteraksi dengan entitas eksternal
confirmationHint	bool / str	Ekstensi DataFlux Func yang mengharuskan Agent memperoleh konfirmasi pengguna sebelum pemanggilan

Nilai dari keempat Hint standar harus berupa boolean. Hanya Hint standar yang secara eksplisit diberikan yang akan ditulis ke annotations; kamus kosong tidak akan menghasilkan annotations.

confirmationHint tidak akan ditulis ke annotations standar MCP. Jika True diberikan, teks petunjuk default berikut akan langsung ditambahkan pada baris berikutnya setelah deskripsi Func, tanpa baris kosong di antaranya:

**The AI Agent MUST obtain the user's explicit confirmation before calling this tool. The AI Agent MUST NOT call this tool without that explicit confirmation.**

Jika False diberikan, tidak ada konten yang ditambahkan; jika string diberikan, string tersebut akan ditambahkan apa adanya pada baris berikutnya sebagai pengganti petunjuk default. Ini hanyalah instruksi untuk Agent, bukan kontrol konfirmasi atau otorisasi yang ditegakkan oleh server.

@DFF.API(
    'Baca Pengguna Lokal',
    mcp_annotations={
        'readOnlyHint': True,
        'openWorldHint': False,
        'confirmationHint': True,
    },
)
def read_local_user(user_id):
    return {'user_id': user_id}

Parameter integration / auto_run / is_hidden

integration digunakan untuk mendeklarasikan integrasi bawaan, dengan nilai yang mungkin adalah signIn atau autoRun. Parameter ini hanya boleh diatur jika perilaku integrasi yang sesuai benar-benar diperlukan.

integration='signIn'

signIn adalah titik masuk login tingkat instalasi. Saat runtime, username dan password akan diteruskan ke Func; mengembalikan nilai falsy atau kosong akan menolak login, mengembalikan True akan menggunakan nama pengguna sebagai identitas eksternal, mengembalikan string atau angka akan menggunakan nilai tersebut sebagai identitas eksternal, dan saat mengembalikan kamus juga dapat menyediakan identitas, nama tampilan, dan informasi email.

Danger

Setelah login berhasil, saat ini akan membuat atau memperbarui pengguna lokal dengan peran administrator, sehingga Func ini termasuk dalam batas kepercayaan administrator. Fungsi ini hanya boleh bertanggung jawab untuk autentikasi; tidak boleh mencatat, menyimpan, mengembalikan, atau mencetak kredensial yang diteruskan, pesan kegagalan juga tidak boleh memuat isi kredensial, dan hanya boleh mengembalikan informasi pengguna minimum yang diperlukan untuk autentikasi.

Kredensial login juga termasuk parameter Func, dan dapat disimpan dalam catatan tugas atau data pemantauan mandiri tergantung pada pengaturan instalasi. Sebelum mengaktifkan integrasi login, periksa pengaturan terkait terlebih dahulu.

Parameter auto_run

auto_run digunakan untuk mengonfigurasi titik masuk auto-run, sekaligus mengatur integration='autoRun'. Mendukung nama kunci standar berikut:

Nama Kunci	Keterangan
cronExpr	Dipicu berdasarkan ekspresi Cron
onSystemLaunch	Dipicu saat sistem dimulai
onScriptPublish	Dipicu setelah Script diterbitkan

Pemicu ini tidak menyediakan parameter Func, oleh karena itu titik masuk auto-run tidak boleh memerlukan parameter posisi atau parameter kata kunci. onScriptPublish hanya akan dijalankan setelah sinkronisasi data Script yang telah dipublikasikan selesai, dan akan mengeksekusi kode yang baru dipublikasikan; jika sinkronisasi gagal, auto-run akan dilewati.

@DFF.API('Titik Masuk Auto-run', auto_run={'onSystemLaunch': True, 'onScriptPublish': True})
def auto_run_entry():
    return 'ok'

Parameter is_hidden

Menetapkan is_hidden=True dapat menyembunyikan Func dari hasil penemuan Func biasa. Parameter ini hanya boleh digunakan jika memang perlu menyembunyikan titik masuk.

Parameter custom / custom_json / custom_yaml

Ketiga parameter ini digunakan untuk mengatur metadata khusus: custom menerima nilai yang dapat diserialisasi ke JSON, custom_json menerima teks JSON, dan custom_yaml menerima teks YAML. Hanya salah satu dari parameter ini yang harus diberikan dalam satu waktu.