Pengembangan Skrip / Konsep Dasar

Dalam DataFlux Func, terdapat beberapa konsep khusus yang hanya ada di DataFlux Func. Dokumen ini akan menjelaskan konsep-konsep tersebut.

1. Kumpulan Skrip, Skrip, dan Fungsi

Kumpulan Skrip, Skrip, dan Fungsi dapat dibuat di "Pengembangan / Pustaka Skrip", dan merupakan konsep inti dari DataFlux Func. ID ditentukan langsung oleh pengguna saat membuat / menulis kode.

"Kumpulan Skrip" adalah kumpulan dari beberapa Skrip, ID ditentukan langsung oleh pengguna saat pembuatan, dan hanya dapat berisi Skrip.
"Skrip" adalah skrip Python itu sendiri, yang pasti termasuk dalam suatu Kumpulan Skrip, ID ditentukan langsung oleh pengguna saat pembuatan.
"Fungsi" secara khusus merujuk pada fungsi tingkat teratas yang didekorasi oleh dekorator @DFF.API(...), yang dapat digunakan sebagai fungsi entry point oleh API Fungsi, Tugas Terjadwal, dan lain-lain.

Kumpulan Skrip bukan folder

Kumpulan Skrip mirip dengan folder, tetapi "folder" ini tidak ada hubungannya dengan folder dalam pemrograman Python pada umumnya

Saat melakukan pemrograman di DataFlux Func, ID Kumpulan Skrip, Skrip, dan Fungsi banyak digunakan, dan ID-ID ini memiliki keterkaitan erat.

Hubungan Antara ID Kumpulan Skrip, Skrip, dan Fungsi

Menurut hierarki Kumpulan Skrip, Skrip, dan Fungsi, ID dari konsep tingkat bawah pasti mengandung ID dari konsep tingkat atas.

Misalkan ada sebuah Kumpulan Skrip dengan ID demo, maka semua Skrip yang termasuk dalam Kumpulan Skrip ini pasti dimulai dengan demo__ (garis bawah ganda).

Selanjutnya misalkan di bawah Kumpulan Skrip ini ada Skrip dengan ID demo__test, yang berisi fungsi def hello(...), maka ID fungsi tersebut adalah demo__test.hello.

Tabel contoh ID adalah sebagai berikut:

Konsep	Contoh ID
Kumpulan Skrip	`demo`
Skrip	`demo__test`
Fungsi	`demo__test.hello`

Referensi Silang dalam Kode

Dalam Skrip DataFlux Func, diperbolehkan untuk mereferensikan Skrip lain untuk mewujudkan penggunaan ulang kode.

Misalkan ada Skrip demo__script_a, yang berisi fungsi func_a(). Maka, untuk mereferensikan fungsi ini di Skrip demo__script_b, dapat menggunakan cara berikut:

demo__script_a
def func_a():
    pass

demo__script_b
import demo__script_b

def test():
    return demo__script_b.func_a()

Pernyataan as di Python juga dapat digunakan:

demo__script_b
import demo__script_b as b

def test():
    return b.func_a()

Juga dapat menggunakan pernyataan from ... import untuk hanya mengimpor fungsi yang diperlukan:

demo__script_b
from demo__script_b import func_a

def test():
    return func_a()

Untuk referensi antar Skrip yang termasuk dalam Kumpulan Skrip yang sama, ID Kumpulan Skrip dapat diabaikan, dinyatakan dengan bentuk singkat yang diawali dengan __ (garis bawah ganda):

demo__script_b
from __script_b import func_a

def test():
    return func_a()

Gunakan Bentuk Singkat Sebisa Mungkin

Referensi timbal balik di dalam Kumpulan Skrip harus menggunakan bentuk singkat sebisa mungkin (yaitu dengan mengabaikan ID Kumpulan Skrip dan diawali dengan __).

Dengan cara ini, setelah seluruh Kumpulan Skrip dikloning dan ID Kumpulan Skrip berubah, kode di dalam Kumpulan Skrip baru hasil kloning tetap dapat mereferensikan Skrip di dalam Kumpulan Skrip ini dengan benar.

2. Konektor

Konektor dapat dibuat di "Pengembangan / Konektor", merupakan alat yang disediakan oleh DataFlux Func untuk menghubungkan sistem eksternal, ID ditentukan langsung oleh pengguna saat pembuatan.

Sebenarnya, menulis kode Python di DataFlux Func tidak jauh berbeda dengan Python asli. Pengembang sepenuhnya dapat mengabaikan Konektor dan menghubungkan sistem eksternal sendiri dalam kode.

Namun untuk beberapa sistem eksternal yang memiliki konsep connection pool, Konektor memiliki connection pool bawaan, yang dapat menjaga koneksi selama fungsi berjalan berulang kali, menghindari pembuatan / penutupan koneksi ke sistem eksternal secara berulang.

Misalkan pengguna telah mengonfigurasi Konektor dengan ID mysql, maka kode untuk mendapatkan objek operasi Konektor ini adalah sebagai berikut:

Python
mysql = DFF.CONN('mysql')

Setiap Konektor yang berbeda memiliki metode operasi dan parameter yang berbeda, untuk detailnya silakan lihat Pengembangan Skrip / Objek Konektor DFF.CONN

3. Variabel Lingkungan

Variabel lingkungan dapat dibuat di "Pengembangan / Variabel Lingkungan", merupakan alat pembaca konfigurasi Key-Value sederhana yang disediakan oleh DataFlux Func, ID ditentukan langsung oleh pengguna saat pembuatan.

Variabel lingkungan sangat cocok digunakan untuk skenario di mana kode yang sama dijalankan di lingkungan yang berbeda.

Jika sistem yang perlu diakses oleh Skrip membedakan lingkungan pengujian / produksi, maka dengan mengatur variabel lingkungan, dapat beralih antara lingkungan pengujian / produksi tanpa mengubah kode.

Misalkan pengguna telah mengonfigurasi variabel lingkungan dengan ID api_endpoint, maka kode untuk mendapatkan nilai variabel lingkungan ini adalah sebagai berikut:

Python
api_endpoint = DFF.ENV('api_endpoint')

4. API Fungsi

API Fungsi dapat dibuat di "Manajemen / API Fungsi", merupakan cara umum untuk memanggil fungsi di DataFlux Func dari luar. Proses pemanggilan dapat dipilih sinkron atau asinkron; saat dieksekusi secara sinkron, hasil dapat dikembalikan langsung ke pemanggil setelah fungsi selesai dieksekusi.

Setelah membuat API Fungsi untuk suatu fungsi, berbagai metode pemanggilan yang berbeda didukung.

API Fungsi mendukung dua metode, GET dan POST. Transfer parameter dari kedua metode yang berbeda ini mendukung "bentuk sederhana" dan "bentuk standar" sekaligus.

Selain itu, bentuk "sederhana" dari metode POST juga mendukung unggahan file. Berikut adalah daftar dukungan fungsi dari berbagai metode pemanggilan:

Metode Pemanggilan	Mengirim Parameter `kwargs`	Tipe Parameter `kwargs`	Mengirim `options`	Unggah File	Mengirim `Body` dalam Format Apa Pun
`GET` bentuk sederhana	Didukung	Hanya string	Tidak didukung	Tidak didukung	Tidak didukung
`GET` bentuk standar	Didukung	Tipe data dalam JSON	Didukung	Tidak didukung	Tidak didukung
`POST` bentuk sederhana	Didukung	Hanya string	Tidak didukung	Didukung	Didukung
`POST` bentuk standar	Didukung	Tipe data dalam JSON	Didukung	Tidak didukung	Tidak didukung

Perbedaan metode pengiriman dapat menyebabkan batasan pada tipe parameter

Untuk metode pemanggilan yang hanya dapat mengirim parameter dalam kwargs sebagai string, Anda perlu melakukan konversi tipe parameter di dalam fungsi. Di daftar API Fungsi, Anda dapat mengklik "Contoh Pemanggilan API" untuk melihat metode pemanggilan spesifik

Misalkan ada fungsi berikut:

Python
@DFF.API('Fungsi Saya')
def my_func(x, y):
    pass

Misalkan ID "API Fungsi" yang dibuat untuk fungsi ini adalah func-api-xxxxx, parameter yang dikirim adalah x=100 (bilangan bulat), y="hello" (string).

Maka, berbagai metode pemanggilan yang berbeda adalah sebagai berikut:

Transfer Parameter Bentuk Sederhana GET

Jika parameter fungsi relatif sederhana, Anda dapat menggunakan bentuk sederhana GET untuk transfer parameter, antarmuka akan lebih intuitif.

Karena saat transfer parameter melalui URL, tidak dapat membedakan antara string "100" dan bilangan bulat 100, sehingga ketika fungsi dipanggil, parameter yang diterima semuanya adalah string. Fungsi perlu melakukan konversi tipe parameter sendiri.

Text Only
GET /api/v1/al/func-api-xxxxx/s?x=100&y=hello

Untuk memudahkan pembacaan, contoh adalah konten sebelum URLEncode; parameter URL sebenarnya perlu melalui URLEncode

Transfer Parameter Bentuk Standar GET

Dalam beberapa kasus, jika tidak dapat mengirim permintaan POST, Anda juga dapat menggunakan metode GET untuk memanggil antarmuka.

Saat transfer parameter dengan bentuk standar GET, seluruh kwargs diserialisasikan ke JSON lalu dikirim sebagai parameter URL. Karena parameter sebenarnya tetap dikirim dalam format JSON, semua tipe asli parameter akan dipertahankan. Fungsi tidak perlu lagi melakukan konversi tipe parameter.

Seperti dalam contoh ini, parameter x yang diterima fungsi adalah bilangan bulat, tidak perlu konversi tipe parameter.

Text Only
GET /api/v1/al/func-api-xxxxx?kwargs={"x":100,"y":"hello"}

Untuk memudahkan pembacaan, contoh adalah konten sebelum URLEncode; parameter URL sebenarnya perlu melalui URLEncode

Transfer Parameter Bentuk Sederhana POST

Dalam beberapa kasus, jika tidak dapat mengirim permintaan HTTP dengan body JSON, maka parameter juga dapat dikirim dengan cara yang mirip dengan Form, di mana nama setiap field adalah nama parameter.

Karena saat data dikirim melalui Form, tidak dapat membedakan antara string "100" dan bilangan bulat 100, maka ketika fungsi dipanggil, parameter yang diterima semuanya adalah string, dan fungsi perlu melakukan konversi tipe parameter sendiri.

Text Only
POST /api/v1/al/func-api-xxxxx/s
Content-Type: x-www-form-urlencoded

x=100&y=hello

Selain itu, transfer parameter dengan bentuk sederhana POST juga mendukung unggahan file (nama parameter/field harus files), perlu diproses menggunakan metode form-data/multipart.

Contoh kode HTML halaman adalah sebagai berikut:

HTML
<html>
    <body>
        <h1>Unggah File</h1>
        <input id="file" type="file" name="files" required />
        <input id="submit" type="submit" value="Unggah"/>
    </body>
    <script>
        // Alamat API Fungsi (jika halaman ini dan DataFlux Func tidak berada di domain yang sama, perlu menulis lengkap http://domain:port/api/v1/al/func-api-xxxxx/s)
        // Catatan: untuk mengunggah file harus menggunakan API Fungsi bentuk sederhana
        var API_URL = '/api/v1/al/func-api-xxxxx/s';

        document.querySelector('#submit').addEventListener('click', function(event) {
            // Setelah mengklik tombol unggah, buat objek FormData lalu kirim sebagai body permintaan
            var data = new FormData();
            data.append('x', '100');
            data.append('y', 'hello');
            data.append('files', document.querySelector('#file').files[0]);

            var xhr = new XMLHttpRequest();
            xhr.open('POST', API_URL);
            xhr.send(data);
        });
    </script>
</html>

Transfer Parameter Bentuk Standar POST

Transfer parameter dengan bentuk standar POST adalah cara pemanggilan yang paling umum. Karena parameter dikirim melalui body permintaan dalam format JSON, semua tipe asli parameter akan dipertahankan. Fungsi tidak perlu lagi melakukan konversi tipe parameter.

Seperti dalam contoh ini, parameter x yang diterima fungsi adalah bilangan bulat, tidak perlu konversi tipe parameter.

Text Only
POST /api/v1/al/func-api-xxxxx
Content-Type: application/json

{
  "kwargs": {
    "x": 100,
    "y": "hello"
  }
}

5. Tugas Terjadwal

Tugas Terjadwal dapat dibuat di "Manajemen / Tugas Terjadwal", digunakan agar DataFlux Func secara berkala memanggil fungsi secara otomatis.

Setelah Tugas Terjadwal dibuat untuk fungsi, fungsi akan dieksekusi secara terjadwal sesuai dengan ekspresi Crontab yang ditentukan, tanpa perlu dipanggil dari luar.

Justru karena itu, semua parameter dari fungsi yang dieksekusi harus sudah terpenuhi, yaitu:

Fungsi tidak memerlukan parameter input
Fungsi memerlukan parameter input, tetapi semuanya adalah parameter opsional
Fungsi memerlukan parameter wajib, dan nilai spesifiknya dikonfigurasi di Tugas Terjadwal

Membedakan Fitur Eksekusi yang Dimiliki Fungsi saat Runtime

Jika fungsi dikonfigurasi dengan "Tugas Terjadwal" dan fitur eksekusi lainnya secara bersamaan, dan ingin melakukan penanganan yang dibedakan di antara fitur eksekusi yang berbeda, dapat menilai variabel bawaan _DFF_CRONTAB untuk membedakan:

Python
@DFF.API('Fungsi Saya')
def my_func(x, y):
    result = x + y

    if _DFF_CRON_EXPR:
        # Hanya menampilkan log saat Tugas Terjadwal
        print(f'x + y = {result}')

    return