DataWorks:Manajemen templat skrip

Langkah 1: Definisikan templat skrip

Pengembang komponen dapat menggunakan antarmuka Snippets di DataStudio untuk mendefinisikan body prosedur serta parameter input dan output untuk logika umum. Dengan menulis prosedur pemrosesan SQL abstrak, Anda dapat memproses tabel input tertentu yang diteruskan sebagai parameter input untuk menghasilkan tabel output bernilai bisnis, yaitu parameter output. Format parameter input dan output dalam kode adalah @@{parameter_name}.

1. Di area Workspace SQL Script Templates, klik ikon dan pilih New SQL Script Template. Anda juga dapat memilih Create Directory terlebih dahulu untuk mengatur templat skrip Anda. Kemudian, klik kanan direktori tersebut dan pilih New SQL Script Template.

   Catatan

   • Templat skrip yang dibuat oleh anggota ruang kerja saat ini muncul di bawah Workspace Component Management.

   • Setelah templat skrip dipublikasikan, templat tersebut muncul di bawah Public SQL Script Templates.

2. Konfigurasikan templat skrip.

   1. Konfigurasikan body prosedur.

      Body prosedur berisi logika implementasi templat skrip. Anda menulis proses SQL abstrak dan menggunakan format @@{parameter_name} untuk parameter input dan output. Desain ini memungkinkan templat memproses tabel input berbeda dan menghasilkan output yang sesuai. Saat Anda menggunakan templat skrip nanti, Anda dapat mengonfigurasi parameter input dan output yang berbeda untuk menghasilkan kode SQL yang benar dan dapat dijalankan dari templat tersebut.

   2. Konfigurasikan parameter input.

      Di sisi kanan editor templat skrip, klik Parameters. Lalu, klik ikon di samping Input Parameters untuk mendefinisikan parameter input untuk body prosedur. Jenis parameter yang didukung adalah Table dan String.

      Catatan

      Anda juga dapat mengklik Parse I/O Parameters di bagian atas halaman editor untuk secara otomatis mengidentifikasi parameter input dan output dari kode. Kemudian, Anda dapat mengonfigurasi parameter tersebut.

      Table

      Kasus penggunaan

      Gunakan jenis ini untuk parameter yang merepresentasikan tabel input dengan skema yang telah ditentukan, di mana logika pemrosesannya konsisten.

      Parameter

      • Parameter utama: Parameter Definition.

      • Deskripsi: Parameter ini menjelaskan skema yang diharapkan dari tabel input, termasuk nama bidang, tipe data, dan komentar. Ini membantu pengguna menyediakan tabel input dengan skema yang kompatibel, mencegah error waktu proses akibat ketidaksesuaian jumlah bidang atau tipe data.

        Catatan

        Definisi ini hanya untuk referensi dan memberikan petunjuk konfigurasi. Tidak ada pemeriksaan waktu proses yang dilakukan berdasarkan definisi ini.

      • Contoh:

        Format yang direkomendasikan untuk definisi parameter adalah sebagai berikut:

        Field1_Name Field1_Type Field1_Comment 
        Field2_Name Field2_Type Field2_Comment 
        ...
        FieldN_Name FieldN_Type FieldN_Comment

        Contoh:

        area_id STRING 'Area ID' 
        city_id STRING 'City ID' 
        order_amt DOUBLE 'Order Amount' 

      String

      Kasus penggunaan

      Gunakan jenis ini saat Anda perlu mengontrol nilai parameter input menggunakan variabel, seperti kondisi filter atau nilai limit.

      Parameter

      • Parameter utama: Default Value.

      • Deskripsi: Jenis ini memungkinkan Anda menetapkan nilai default yang digunakan saat templat skrip direferensikan.

      • Contoh:

        • Skenario 1: Tabel output templat skrip perlu menampilkan N kota teratas berdasarkan penjualan di setiap wilayah. Anda dapat menetapkan N sebagai parameter input bertipe String untuk mengontrol nilainya.

        • Skenario 2: Tabel output templat skrip perlu menampilkan total penjualan suatu provinsi. Anda dapat menetapkan string provinsi sebagai parameter input untuk mengambil data penjualan provinsi yang berbeda.

   3. Konfigurasikan parameter output.

      Definisikan parameter output untuk body prosedur, yang merepresentasikan tabel output akhir dari templat skrip. Untuk kejelasan, tentukan skema tabel output dalam konfigurasi parameter output sebagai referensi bagi pengguna lain.

      Di sisi kanan editor templat skrip, klik Parameters. Lalu, klik ikon di samping Output Parameters untuk mendefinisikan parameter output untuk body prosedur.

      Catatan

      Anda juga dapat mengklik Parse I/O Parameters di bagian atas halaman editor untuk secara otomatis mengidentifikasi parameter input dan output dari kode. Kemudian, Anda dapat mengonfigurasi parameter tersebut.

      • Parameter utama: Parameter Definition.

      • Deskripsi: Parameter ini menjelaskan skema tabel output dalam format teks, termasuk informasi seperti nama bidang, tipe data, dan komentar. Ini memberi tahu pengguna bahwa tabel output yang mereka konfigurasikan harus memiliki jumlah bidang yang sama dan tipe data yang kompatibel seperti yang didefinisikan di sini. Hal ini membantu mencegah error waktu proses akibat ketidaksesuaian antara tabel output yang dikonfigurasi dan skema output yang didefinisikan.

        Catatan

        Definisi ini hanya untuk referensi dan memberikan petunjuk konfigurasi. Tidak ada pemeriksaan waktu proses yang dilakukan berdasarkan definisi ini.

      • Contoh:

        Format yang direkomendasikan untuk definisi parameter adalah sebagai berikut:

        Field1_Name Field1_Type Field1_Comment 
        Field2_Name Field2_Type Field2_Comment 
        ...
        FieldN_Name FieldN_Type FieldN_Comment

        Selain itu, Anda dapat menambahkan bidang ringkasan ke definisi parameter output berdasarkan hasil pemrosesan yang Anda perlukan, seperti rank atau total pendapatan. Contoh:

        area_id STRING 'Area ID' 
        city_id STRING 'City ID' 
        order_amt DOUBLE 'Order Amount'
        rank BIGINT 'Rank'

3. Klik Save dan Submit.

   Setelah templat skrip dibuat, Anda dapat mereferensikannya di node templat skrip SQL untuk dengan cepat menghasilkan tabel target. Untuk informasi selengkapnya, lihat Langkah 2: Referensikan templat skrip.

4. (Opsional) Klik Publish Snippet untuk menerbitkan templat skrip yang dapat digunakan secara global ke seluruh penyewa. Templat skrip tersebut kemudian akan ditampilkan di area Public SQL Script Templates. Setelah Anda menerbitkan templat skrip, semua pengguna dalam penyewa tersebut dapat menggunakannya.

Langkah 2: Referensikan templat skrip

Anda dapat mereferensikan templat skrip dengan cara berikut.

Untuk developer templat skrip

Pengembang dapat mengedit kode templat skrip dan konfigurasi parameternya sesuai kebutuhan. Setelah menyimpan dan meng-commit perubahan, Anda membuat versi baru dari templat skrip. Anda dapat melihat detail setiap versi di tab Version.

Untuk pengguna templat skrip

Saat templat skrip yang direferensikan diperbarui, Anda dapat memilih apakah akan menggunakan versi baru tersebut di node templat skrip SQL Anda.

• Jika Anda tidak ingin menggunakan versi baru, Anda dapat terus mereferensikan versi aslinya.

• Jika Anda ingin menggunakan versi baru, pastikan apakah konfigurasi parameter baru masih valid untuk node templat skrip SQL Anda. Lakukan penyesuaian berdasarkan deskripsi versi baru tersebut, lalu commit dan terbitkan node tersebut. Proses commit dan penerbitan sama dengan node SQL biasa.

Skenario upgrade

Seorang pengembang templat skrip membuat versi V1 dari templat skrip SQL, dan seorang pengguna mereferensikannya. Kemudian, pengembang melakukan upgrade templat skrip tersebut ke versi V2. Pengguna melihat bahwa V2 tersedia, membuka templat skrip tersebut, dan membandingkan versi-versinya. Setelah mengetahui bahwa versi baru memberikan hasil bisnis yang lebih baik, pengguna memperbarui ke versi terbaru.

Clone templat skrip

Gunakan fitur clone untuk dengan cepat membuat templat skrip baru dari templat yang sudah ada. Konten yang di-clone mencakup kode templat skrip, konfigurasi parameter, dan parameter skrip dari Run Configuration.

1. Di panel kiri Workspace Component Management, klik kanan templat skrip yang ingin Anda clone dan pilih Cloning.

2. Di kotak dialog yang muncul, ubah Name dan Path templat skrip, atau pertahankan nilai default, lalu klik Confirm.

3. Setelah proses cloning selesai, Anda dapat melihat templat skrip baru di Workspace Component Management.

Kelola versi

Manajemen versi memungkinkan Anda memulihkan templat skrip ke versi historis tertentu. Fitur ini juga menyediakan kemampuan untuk melihat dan membandingkan versi, sehingga Anda dapat menganalisis perbedaan dan melakukan penyesuaian.

1. Di panel kiri Workspace Component Management, klik ganda templat skrip yang ingin Anda kelola untuk membuka halaman editornya.

2. Klik Version di sisi kanan halaman editor. Di halaman Version, Anda dapat melihat dan mengelola informasi di tab Developer Record dan Publish Record.

   • View versi:

     1. Di tab Developer Record atau Publish Record, temukan versi templat skrip yang ingin Anda lihat.

     2. Klik View di kolom Operation untuk membuka halaman detail dan melihat kode templat skrip serta konfigurasi penjadwalannya.

   • Compare versi:

     Anda dapat membandingkan versi berbeda dari templat skrip di tab Developer Record atau Publish Record. Contoh berikut menunjukkan operasi perbandingan menggunakan riwayat pengembangan.

     • Bandingkan dalam lingkungan pengembangan atau penerapan: Di tab Developer Record, pilih dua versi dan klik Select Comparison di bagian atas. Anda kemudian dapat membandingkan kode dan konfigurasi penjadwalan kedua versi tersebut.

     • Bandingkan antara lingkungan pengembangan dan penerapan:

       1. Di tab Developer Record, temukan versi tertentu dari templat skrip.

       2. Klik Compare di kolom Operation. Di halaman detail, pilih versi dari Publish Record untuk dibandingkan.

   • Restore versi:

     Anda hanya dapat memulihkan templat skrip ke versi historis dari Developer Record-nya. Di tab Developer Record, temukan versi yang dituju dan klik Restore di kolom Operation untuk mengembalikan templat skrip ke versi tersebut.