DataWorks:Buat API dalam mode skrip

1. Pilih tabel

Klik ganda API untuk membuka halaman editnya. Di bagian Table, konfigurasikan parameter seperti Data Source Type, Data Source Name, dan Data Source Environment.

Parameter yang diperlukan bergantung pada jenis sumber data. Lihat antarmuka pengguna untuk detailnya.

2. Tulis kueri SQL

Di bagian Edit Query SQL, masukkan pernyataan kueri SQL.

• Jika Anda memilih mode Basic SQL, hanya sintaks SQL dasar yang didukung.

  SELECT
  name,
  addr AS address,
  SUM(num) as total_num
  FROM
  table_name
  WHERE
  user_id =${uid}

  Catatan

  Bidang dalam klausa SELECT menentukan parameter respons API. Parameter dalam klausa WHERE menentukan parameter permintaan API. Gunakan format ${} untuk mengidentifikasi parameter permintaan.

  Ikuti aturan berikut saat menulis pernyataan SQL:

  • Kueri satu tabel, kueri join multi-tabel, dan kueri bersarang dalam sumber data yang sama didukung.

  • Hal-hal berikut tidak didukung:

    • Beberapa pernyataan SQL.

    • Komentar.

    • Pernyataan non-SELECT, seperti INSERT, UPDATE, dan DELETE.

    • Pernyataan SELECT *. Anda harus secara eksplisit menentukan kolom yang akan dikueri.

    • Jangan membungkus variabel ${param} dalam tanda kutip. Misalnya, '${id}' dan 'abc${xyz}123' tidak didukung. Untuk melakukan hal ini, gunakan fungsi concat('abc', ${xyz}, '123').

    • Parameter opsional.

  • Jika nama kolom dalam klausa SELECT diawali dengan nama tabel (misalnya, t.name), Anda harus menentukan alias untuk parameter respons (misalnya, t.name as name).

  • Jika Anda menggunakan fungsi agregat (seperti min, max, sum, atau count), Anda harus menentukan alias untuk parameter respons. Contohnya, sum(num) as total_num.

  • Variabel ${param} dalam pernyataan SQL, termasuk yang berada dalam string, akan diganti dengan parameter permintaan. Ketika variabel ${param} diawali dengan backslash (\), variabel tersebut diperlakukan sebagai string literal.

• Jika Anda memilih mode Advanced SQL, tag MyBatis didukung.

  SELECT id, name, create_name
  FROM t_parameter
  <where>
  <if test="'list!=null'">
      id in (
          <foreach collection="list" open="(" close=")" separator="," item="id_num">
              ${id_num}
          </foreach>
      )
  </if>
  </where>

  Tag MyBatis yang didukung dalam Advanced SQL adalah if, choose, when, otherwise, trim, foreach, dan where. Anda dapat menggunakan tag-tag ini untuk menerapkan logika kueri kompleks, seperti pemeriksaan nilai null, traversal multi-nilai, kueri tabel dinamis, pengurutan dinamis, dan agregasi. Untuk contoh kode dalam skenario umum, lihat Contoh Advanced SQL (sintaks MyBatis).

  Saat menggunakan karakter khusus dalam tag MyBatis, Anda harus melakukan escape karakter tersebut. Tabel berikut mencantumkan karakter escape umum.

  Karakter khusus	Karakter escape	Deskripsi
  >	>	Lebih besar dari
  >=	>=	Lebih besar dari atau sama dengan
  <	&lt;	Kurang dari
  <=	&lt;=	Kurang dari atau sama dengan
  &	&amp;	Dan
  '	&apos;	Tanda kutip tunggal
  "	&quot;	Tanda kutip ganda

3. Konfigurasikan parameter permintaan

Di panel kanan halaman edit API, klik Request Parameters dan konfigurasikan parameter tersebut.

Jika Anda menggunakan mode Advanced SQL, tambahkan secara manual semua parameter permintaan dari skrip SQL ke daftar. Hal ini memastikan dokumentasi API secara akurat mencerminkan parameter yang diperlukan.

4. Konfigurasikan parameter respons

Di panel kanan halaman edit API, klik Response Parameters dan konfigurasikan parameter tersebut.

1. Konfigurasikan parameter respons.

   Jika Anda menggunakan mode Advanced SQL, tambahkan secara manual semua parameter respons dari skrip SQL ke daftar. Hal ini memastikan dokumentasi API secara akurat mencerminkan data yang dikembalikan.

   Parameter	Deskripsi
   Parameter Name	Nama parameter respons. Nama dapat memiliki panjang hingga 64 karakter, harus dimulai dengan huruf, dan dapat berisi huruf, angka, garis bawah (_), dan tanda hubung (-).
   Parameter Type	Tipe data yang didukung adalah STRING, INT, LONG, FLOAT, Double, dan Boolean.
   Sample Value	Nilai contoh untuk parameter respons.
   Description	Deskripsi singkat tentang parameter respons.

2. Di bagian Advanced Settings, tentukan apakah akan mengaktifkan Pagination for Return Results.

   • Jika Anda tidak mengaktifkan Pagination for Return Results, API secara default mengembalikan maksimal 2.000 catatan.

   • Aktifkan Pagination for Return Results jika API kemungkinan mengembalikan lebih dari 2.000 hasil. Setelah diaktifkan, Anda dapat membuka halaman Resource Group for DataService Studio di panel navigasi kanan untuk mengatur jumlah maksimum entri per halaman berdasarkan jenis kelompok sumber daya.

   Catatan

   Jika Pagination for Return Results diaktifkan di tab Response Parameters pada halaman edit API, dan Anda menggunakan pernyataan SQL dengan klausa LIMIT di bagian Edit Query SQL, klausa LIMIT akan diabaikan, dan jumlah hasil yang dikembalikan ditentukan oleh pengaturan Pagination for Return Results.

   Setelah Anda mengaktifkan pagination, parameter umum berikut akan ditambahkan secara otomatis:

   • Parameter permintaan umum

     • returnTotalNum: menentukan apakah akan mengembalikan jumlah total catatan data dalam satu permintaan.

     • pageNum: nomor halaman saat ini.

     • pageSize: jumlah entri per halaman.

   • Parameter respons umum

     • pageNum: nomor halaman saat ini.

     • pageSize: jumlah entri per halaman.

     • totalNum: jumlah total catatan.

   Catatan

   API dapat tidak memiliki parameter permintaan, tetapi dalam kasus tersebut, Anda harus mengaktifkan Pagination for Return Results.

5. Konfigurasikan filter

Jika Anda perlu melakukan pra-pemrosesan parameter permintaan atau pasca-pemrosesan hasil kueri, klik Filter di panel navigasi sisi kanan pada halaman pengeditan API. Pilih Use Pre-filter atau Use Post-filter sesuai kebutuhan. Selanjutnya, pilih Function Type, lalu pilih satu atau beberapa fungsi dari daftar drop-down pra-filter atau pasca-filter. Fungsi-fungsi tersebut dieksekusi sesuai urutan penambahannya. Setelah konfigurasi selesai, klik Preview Responses Returned by API Operation untuk memverifikasi apakah hasilnya sesuai ekspektasi. Untuk informasi selengkapnya tentang cara membuat dan menggunakan filter, lihat Membuat fungsi Aviator dan Membuat fungsi Python.

6. Konfigurasikan kelompok sumber daya layanan

1. Di panel navigasi kanan halaman edit API, klik Resource Group for DataService Studio. Di bagian Resource Group Type, konfigurasikan jenis kelompok sumber daya yang akan digunakan saat memanggil API.

   Anda dapat memilih Exclusive Resource Group for DataService Studio atau Shared Resource Group for DataService Studio. Untuk Exclusive Resource Group for DataService Studio, Anda dapat memilih nama kelompok sumber daya target dari daftar. Shared Resource Group for DataService Studio dikelola secara otomatis oleh DataWorks dan tidak dapat dipilih berdasarkan nama.

   Catatan

   • Jika nama kelompok sumber daya target tidak ada dalam daftar, buka halaman Resource Groups, temukan kelompok sumber daya tersebut, lalu klik Associate Workspace di kolom Operation.

   • Jika kelompok sumber daya target ada dalam daftar tetapi tidak dapat dipilih, buka halaman Resource Groups, temukan kelompok sumber daya tersebut, lalu di kolom Operation, klik > Manage Quota . Atur secara manual Occupied CUs (untuk kelompok sumber daya bayar sesuai penggunaan) atau Minimum CUs (untuk kelompok sumber daya langganan) untuk tujuan Data Services.

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

   • Waktu timeout maksimum bergantung pada jenis kelompok sumber daya layanan DataWorks dan instans API Gateway yang dipilih:

     • instans API Gateway bersama: hingga 30.000 ms untuk Shared Resource Group for DataService Studio, dan hingga 30.000 ms untuk Exclusive Resource Group for DataService Studio.

     • instans API Gateway khusus: hingga 30.000 ms untuk Shared Resource Group for DataService Studio, dan hingga 90.000 ms untuk Exclusive Resource Group for DataService Studio.

     Catatan

     Waktu respons API bergantung pada waktu eksekusi SQL-nya. Untuk mencegah kegagalan permintaan, atur Timeout API ke nilai yang lebih besar daripada waktu eksekusi yang diharapkan.

   • Jumlah maksimum entri per halaman bergantung pada jenis kelompok sumber daya layanan yang dipilih:

     • Jika Anda memilih Shared Resource Group for DataService Studio, jumlah maksimum catatan data per halaman dengan pagination diaktifkan adalah 2.000.

     • Jika Anda memilih Exclusive Resource Group for DataService Studio, jumlah maksimum catatan data per halaman dengan pagination diaktifkan adalah 10.000.

     Catatan

     Tidak ada batas atas jumlah total hasil yang dapat dikembalikan oleh API.

7. Simpan dan kirim

Klik ikon Save di bilah alat. Setelah Anda menyimpan API, kelompok sumber daya yang dipilih akan digunakan untuk pengujian.