DataWorks:Buat API dari sumber data (API Gateway)

Perbandingan mode

Memilih mode

• Gunakan wizard mode: untuk kueri sederhana pada satu tabel data, seperti penyaringan berdasarkan kesamaan, pencocokan kabur, atau rentang. Mode ini menyediakan antarmuka visual tanpa kode untuk konfigurasi API.

• Gunakan script mode: untuk kueri lanjutan, seperti JOIN multi-tabel, subkueri bersarang, agregasi, atau kondisi dinamis dengan parameter opsional.

1. Pilih sumber data dan tabel

Klik ganda API untuk membuka halaman editnya. Di area Table, konfigurasikan parameter seperti Data Source Type, Data Source Name, dan Data Source Environment. Parameter konfigurasi bervariasi tergantung jenis sumber data. Lihat UI untuk parameter spesifiknya.

2. Definisikan logika kueri

Anda mendefinisikan logika kueri secara berbeda di wizard mode dan script mode.

3. Konfigurasikan parameter permintaan

Klik Request Parameters di panel kanan halaman edit API untuk mengonfigurasi parameter.

4. Konfigurasikan parameter respons dan paginasi

Klik Response Parameters di panel kanan halaman edit API untuk mengonfigurasi nama parameter, jenis parameter, nilai contoh, dan deskripsi. Dalam mode Advanced SQL, Anda harus menambahkan semua parameter respons secara manual berdasarkan skrip SQL Anda.

Di area Advanced Settings, tentukan apakah akan mengaktifkan Pagination for Return Results:

• Nonaktif: API mengembalikan maksimal 2.000 catatan secara default.

• Aktif: Anda dapat mengatur jumlah maksimum catatan per halaman di halaman Resource Group for DataService Studio berdasarkan jenis kelompok sumber daya.

Saat paginasi diaktifkan, sistem secara otomatis menambahkan parameter umum berikut:

• Parameter permintaan umum: returnTotalNum (apakah mengembalikan jumlah total catatan), pageNum (nomor halaman saat ini), dan pageSize (jumlah catatan per halaman).

• Parameter respons umum: pageNum, pageSize, dan totalNum (jumlah total catatan).

5. Konfigurasikan filter (opsional)

Untuk memproses awal parameter permintaan atau memproses akhir hasil kueri, klik Filter di panel navigasi sisi kanan. Pilih kotak centang Use Pre-filter atau Use Post-filter. Kemudian, pilih Function Type dan pilih fungsi. Anda dapat menambahkan beberapa fungsi, yang dieksekusi sesuai urutan penambahannya. Untuk informasi lebih lanjut tentang cara membuat dan menggunakan filter, lihat Buat fungsi Aviator dan Buat fungsi Python.

6. Konfigurasikan kelompok sumber daya layanan

Di panel navigasi sisi kanan, klik Resource Group for DataService Studio untuk mengonfigurasi jenis kelompok sumber daya untuk API.

Anda dapat menggunakan Exclusive Resource Group for DataService Studio atau Shared Resource Group for DataService Studio. Untuk kelompok sumber daya layanan eksklusif, Anda dapat memilih kelompok sumber daya target berdasarkan nama. Kelompok sumber daya layanan publik dikelola secara otomatis oleh DataWorks.

Di area Environment Configuration, Anda dapat mengatur Memory, Timeout, dan Maximum Number of Data Records for a Single Request:

• Timeout: Timeout tidak boleh melebihi 30.000 ms untuk instans API Gateway bersama, atau 90.000 ms untuk kelompok sumber daya layanan eksklusif yang menggunakan instans API Gateway khusus.

  Catatan

  Waktu respons API bergantung pada waktu eksekusi SQL. Atur nilai timeout cukup tinggi untuk mengakomodasi hal ini dan mencegah kegagalan permintaan akibat timeout.

• Jumlah maksimum catatan per halaman: Maksimal 2.000 untuk kelompok sumber daya layanan publik dan maksimal 10.000 untuk kelompok sumber daya layanan eksklusif. Jumlah total hasil yang dapat dikembalikan API tidak dibatasi.

Contoh 1: Mengontrol urutan pengurutan

Nilai var menentukan urutan pengurutan.

select col01,col02
from table_name
<choose>
    <when test='var == 1'>
    order by col01
    </when>
    <when test='var == 2'>
    order by col02
    </when>
    <when test='var == 3'>
    order by col01,col02
    </when>
    <when test='var == 4'>
    order by col02,col01
    </when>
</choose>

Parameter permintaan: var (Jenis: INT, Wajib). Parameter respons: col01, col02.

Contoh 2: Kueri tabel berbeda

Nilai berbeda dari var menentukan tabel mana yang akan dikueri.

select col01
from
<choose>
 <when test='var == 1'>
 table_name01
 </when>
 <when test='var == 2'>
 table_name02
 </when>
</choose>

Contoh 3: Klausa WHERE dinamis

Kondisi kueri dihasilkan secara dinamis berdasarkan apakah koleksi list kosong. Jika list tidak null, kondisi kueri yang mencakup nilai bidang area dihasilkan.

SELECT area_id, area, amount
FROM table_name
<where>
	<if test='list!=null'>
	area in
		<foreach collection="list" open="(" close=")" separator="," item="area">
		#{area}
		</foreach>
	</if>
</where>

Parameter permintaan: list (Jenis: STRING_LIST, Wajib, Contoh: Beijing,Hangzhou). Parameter respons: area_id, area, dan amount.

Parameter opsional dalam wizard mode

Mengimplementasikan parameter opsional dalam wizard mode sangat mudah. Setelah memilih uid dan gender sebagai parameter permintaan di area Select Parameters, buka panel Request Parameters di sebelah kanan dan kosongkan kotak centang Required untuk parameter gender.

• Dipilih: Anda harus memberikan nilai untuk parameter saat memanggil API. Jika tidak, akan muncul exception validasi parameter.

• Dikosongkan: Anda dapat memilih apakah akan memberikan nilai untuk parameter. Jika tidak memberikan nilai, parameter tidak termasuk sebagai kondisi kueri.

Contoh Pemanggilan:

• Skenario 1: Nilai diberikan untuk uid dan gender. Sistem menjalankan kueri berikut:

  SELECT uid, gender, age_range, zodiac
  FROM ods_user_info_d
  WHERE uid = 0016359810821
  AND gender = 'Female';

• Skenario 2: Nilai diberikan untuk uid, tetapi tidak ada nilai untuk gender. Sistem menjalankan kueri berikut:

  SELECT uid, gender, age_range, zodiac
  FROM ods_user_info_d
  WHERE uid = 0016359810821;

Parameter opsional dalam script mode

Dalam mode advanced SQL, gunakan tag MyBatis <if> untuk mengimplementasikan logika kondisional:

SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
<where>
    <if test='gender!=null'>
    gender = ${gender}
    </if>
    and uid = ${uid}
</where>

• Tag <where> secara otomatis menangani kata kunci WHERE dan menghapus awalan AND atau OR yang berlebihan.

• Tag <if test='gender!=null'> menambahkan kondisi ke kueri hanya jika Anda memberikan nilai non-null untuk parameter gender.

• Setelah mengonfigurasi pernyataan SQL, tambahkan secara manual parameter uid dan gender di panel Request Parameters di sebelah kanan, dan kosongkan kotak centang Required untuk parameter gender.

Perilakunya sama seperti di wizard mode: kondisi gender diterapkan saat nilai diberikan, dan diabaikan saat dihilangkan.

Konfigurasi parameter opsional