DataWorks:Buat, publikasikan, dan panggil API (Cloud-native API Gateway)

1. Buat instans gateway

Instans gateway adalah mesin yang memproses permintaan API.

1. Masuk ke Konsol Cloud-native API Gateway. Di panel navigasi kiri, klik Instance.

2. Di bilah navigasi atas, pilih wilayah.

   Penting

   Wilayah harus sama dengan wilayah ruang kerja DataWorks Anda.

3. Di halaman Instance, klik Create Instance.

4. Di halaman pembelian, konfigurasikan parameter berikut:

   • Commodity Type: Pilih Pay-as-you-go atau Subscription. Untuk pengujian, Anda dapat memilih Pay-As-You-Go.

   • Gateway Name: Masukkan nama kustom agar mudah diidentifikasi, misalnya dataservice-prod.

   • Gateway Specification: Untuk pengujian, Anda dapat memilih spesifikasi single-node. Untuk lingkungan produksi, kami menyarankan menggunakan spesifikasi gateway multi-node untuk memastikan SLA (service-level agreement) yang tinggi.

   • Network Type: Pilih Public atau Public + Private untuk akses internet publik. Biaya dikenakan untuk traffic jaringan publik.

   • VPC: Pilih VPC.

     Penting

     Untuk memastikan konektivitas jaringan, kami sangat menyarankan memilih VPC yang sama dengan Serverless resource group. Jika VPC berbeda, Anda harus membuat layanan backend secara manual nanti.

   • Zone Selection: Pilih Auto-assign atau tetapkan instans secara manual ke zona ketersediaan dan vSwitch yang berbeda.

   • Resource Group: Pilih resource group sesuai strategi manajemen resource Anda.

5. Klik Buy Now dan selesaikan pembayaran. Pembuatan instans memerlukan waktu sekitar 1 hingga 5 menit. Saat status instans berubah menjadi Running, pembuatan instans selesai.

Untuk informasi lebih lanjut, lihat Buat instans gateway.

2. Tambahkan nama domain

Nama domain adalah titik masuk publik untuk API Anda.

1. Di panel navigasi kiri Konsol Cloud-native API Gateway, pilih Domain Name. Pastikan wilayah yang dipilih di bilah navigasi atas sama dengan wilayah instans gateway Anda.

2. Klik Add Domain Name dan konfigurasikan informasi berikut:

   • Domain Name: Masukkan nama domain Anda sendiri, misalnya api.example.com. Nama domain mandiri yang digunakan di wilayah Tiongkok daratan harus memiliki Pendaftaran ICP.

   • Protocol: Kami menyarankan memilih HTTPS untuk mengamankan transmisi data. Jika Anda memilih HTTPS, Anda harus memilih Sertifikat SSL yang sudah ada.

   • Other configurations: Kami menyarankan mengaktifkan Force HTTPS dan Enable HTTP/2 serta menentukan TLS Version sesuai kebutuhan keamanan Anda.

Untuk informasi lebih lanjut, lihat Buat nama domain.

3. Buat REST API

REST API adalah wadah logis yang digunakan untuk mengelola sekelompok API yang memiliki Base Path yang sama. Alur kerja di DataWorks di-bind ke REST API.

1. Di panel navigasi kiri Konsol Cloud-native API Gateway, klik API. Pastikan wilayah yang benar dipilih di bilah navigasi atas.

2. Klik Create API. Di halaman Create API, klik Create pada kartu REST API.

3. Di panel Create REST API, konfigurasikan parameter berikut:

   • API Name: Masukkan nama untuk koleksi API Anda. Nama harus unik secara global di wilayah saat ini. Contoh: dataservice-user-api.

   • Base Path: base path API, yang merupakan bagian dari URL. Misalnya, Anda dapat mengatur parameter ini ke /v1. Jalur akses akhir akan menjadi protocol://domain/BasePath/APIPath.

   • Version Management: Aktifkan fitur ini sesuai kebutuhan.

Untuk informasi lebih lanjut, lihat Buat REST API dan tambahkan antarmuka.

1. Buat alur kerja

Alur kerja digunakan untuk mengelompokkan sejumlah API terkait dan meng-bind-nya ke REST API di API Gateway.

1. Buka Konsol DataWorks. Di panel navigasi kiri, pilih Data Services > Service Development.

2. Klik ikon new, lalu pilih Create Workflow.

3. Di kotak dialog Create Workflow, konfigurasikan parameter berikut:

   • Workflow Name: Masukkan nama kustom yang unik dalam ruang kerja, misalnya User Query Service. Panjang nama harus 4 hingga 50 karakter.

   • Gateway Type: Pilih Cloud-native API Gateway.

   • REST API: Dari daftar drop-down, pilih REST API yang telah Anda buat di Langkah 1, misalnya dataservice-user-api. Jika API tidak muncul, klik tombol Refresh.

     Penting

     Setelah alur kerja di-bind ke REST API, binding tersebut tidak dapat diubah. Pilih REST API dengan hati-hati.

2. Hasilkan API dalam mode wizard

1. Di halaman Service Development, arahkan kursor ke ikon new lalu klik Create API > Generate API.

2. Di kotak dialog Generate API, pilih Wizard Mode dan konfigurasikan informasi dasar tentang API:

   • Location: Pilih Workflow (User Query Service) yang telah Anda buat pada langkah sebelumnya.

   • API Name: Masukkan nama untuk API, misalnya Query user by user ID.

   • APIPath: Jalur spesifik API, misalnya /user/info. Ini digabungkan dengan Base Path untuk membentuk jalur URL lengkap. Jalur API harus dimulai dengan garis miring (/) dan tidak boleh melebihi 200 karakter.

   • Request Method: Pilih GET atau POST. Jika Anda menggunakan metode GET, parameter permintaan harus ditempatkan di query string.

   • Response Type: Pilih JSON.

3. Klik Create untuk membuka halaman pengeditan API berbasis GUI.

   Catatan

   Untuk membuat API dalam mode skrip, lihat Hasilkan API dalam mode skrip.

3. Konfigurasikan API

Di halaman pengeditan API, ikuti alur kerja Select Table > Select Parameters > Configure Parameters untuk mendefinisikan logika inti API.

1. Pilih tabel (sumber data dan tabel)

   Di area Select Table di sisi kiri halaman, konfigurasikan parameter berikut:

   • Data Source Type: Pilih MaxCompute (ODPS).

   • Data Source Name: Pilih sumber data yang telah Anda konfigurasikan dalam prasyarat.

   • Data Table Name: Pilih tabel user_info.

   • Jika Anda menggunakan sumber data MaxCompute, Anda harus mengonfigurasi Acceleration Method untuk meningkatkan performa.

2. Pilih parameter (permintaan dan respons)

   Setelah memilih tabel, bidang-bidangnya akan muncul di bagian Select Parameters.

   • Konfigurasi parameter permintaan: Centang kotak untuk bidang user_id, lalu centang kotak Set as Req Param.

   • Konfigurasi parameter respons: Centang kotak untuk bidang user_id dan user_name, lalu centang kotak Set as Resp Param.

3. Konfigurasi detail parameter permintaan Di tab Request Parameters di sisi kanan, tentukan Sample Value untuk parameter user_id, misalnya 10001. Hal ini menyederhanakan pengujian selanjutnya.

   Praktik terbaik: Tetapkan bidang indeks sebagai parameter permintaan untuk mengoptimalkan performa kueri.

4. Konfigurasi kelompok resource layanan dan lingkungan

   Di bagian Service Resource Group di sisi kanan, konfigurasikan parameter berikut:

   • Resource Group Type: Anda harus memilih Exclusive Resource Group for Data Service dan memilih kelompok resource yang di-bind ke ruang kerja saat ini dari daftar drop-down.

   • Environment Configuration:

     • Timeout: Waktu maksimum yang ditunggu Cloud-native API Gateway untuk respons dari DataWorks, misalnya 3 detik.

     • Maximum Number of Data Records for a Single Request: Jumlah maksimum catatan yang dikembalikan oleh satu panggilan API, misalnya 2000 catatan.

5. Konfigurasi otentikasi keamanan

   Konfigurasikan pengaturan di bagian otentikasi keamanan di sisi kanan. Setelah mengaktifkan otentikasi konsumen, Anda dapat memilih salah satu dari tiga jenis otentikasi berikut.

   Catatan

   Untuk setiap ruang kerja, DataWorks secara otomatis membuat konsumen dengan nama yang sama dengan ruang kerja di Cloud-native API Gateway. Anda tidak perlu membuat konsumen secara manual.

   Metode	Deskripsi	Kasus penggunaan
   API key	Klien menambahkan kredensial ke permintaan dengan cara tertentu, dan gateway memverifikasi validitas serta izinnya. Metode ini berlaku untuk operasi non-sensitif dan kurang aman dibandingkan otentikasi JWT dan Pasangan Kunci Akses. Anda harus mengelola dan melindungi kredensial Anda dengan baik.	Cocok untuk integrasi ringan, cepat, dan skenario dengan persyaratan keamanan umum.
   JWT	Token Web JSON (JWT) adalah standar untuk mentransmisikan informasi secara aman antara klien dan server. JWT menggunakan signature HMAC, RSA, atau ECDSA untuk memastikan informasi dapat diverifikasi dan tepercaya. Otentikasi JWT dapat digunakan di gateway untuk menerapkan verifikasi identitas dan kontrol akses.	Cocok untuk sistem terdistribusi dan skenario Single Sign-On (SSO).
   HMAC	Ini adalah metode otentikasi signature berbasis Pasangan Kunci Akses yang menggunakan algoritma HMAC. Saat memanggil API, klien harus menggunakan kunci tanda tangan untuk menghitung signature dari konten permintaan dan mengirimkannya ke server untuk verifikasi.	Cocok untuk skenario yang memerlukan integritas data tinggi dan perlindungan terhadap perubahan data.

6. Save API: Setelah Anda mengonfigurasi semua parameter, klik ikon Save di bilah alat atas.

1. Uji API

Anda harus berhasil menguji API sebelum melakukan komit.

1. Di halaman pengeditan API, klik tombol Test APIs di bilah alat.

2. Di kotak dialog Test APIs, masukkan nilai yang ada, misalnya 10001, untuk parameter permintaan user_id lalu klik Start Test.

3. Periksa Response Details di sisi kanan untuk memastikan data yang dikembalikan sesuai harapan. Response Duration menunjukkan performa.

4. Jika pengujian gagal, periksa konfigurasi sumber data, tabel, parameter, atau kelompok resource berdasarkan pesan error.

2. Commit API

Setelah pengujian berhasil, komit API untuk menghasilkan versi yang siap dipublikasikan.

1. Di halaman pengeditan API, klik tombol Submission di bilah alat.

2. Setelah mengkomit API, sistem secara otomatis menghasilkan versi. Anda dapat melihat versi tersebut di tab Version Management di sisi kanan.

3. Jika proses persetujuan dikonfigurasi untuk ruang kerja Anda, status versi API adalah To Be Requested. Anda harus mengklik Request to Publish untuk mengajukannya guna disetujui. Setelah permohonan disetujui, status berubah menjadi Can Be Published.

   Jika tidak ada proses persetujuan yang dikonfigurasi, status versi biasanya Publishable.

3. Publikasikan API ke Cloud-native API Gateway

Ini adalah langkah terakhir untuk men-deploy API ke lingkungan produksi.

1. Di tab Version di sisi kanan halaman pengeditan API, temukan versi dengan status Can Be Published lalu klik Publish di kolom Actions.

2. Di kotak dialog Publish API to Cloud-native API Gateway, konfigurasikan parameter wajib berikut:

   • Domain Name: Pilih nama domain yang telah Anda tambahkan di Langkah 1.

     Penting

     Semua API di bawah REST API yang sama berbagi nama domain yang sama. Perubahan apa pun yang dilakukan pada nama domain selama penerbitan akan memengaruhi semua API di bawah REST API yang sama.

   • Gateway Instance: Pilih instans gateway yang telah Anda buat di Langkah 1.

   • Backend Service:

     • Jika VPC instans gateway sama dengan VPC kelompok resource DataWorks, pilih Default.

     • Jika VPC berbeda, Anda harus memilih layanan backend yang dibuat di Cloud-native API Gateway.

       Buat layanan backend

       Lakukan langkah ini hanya jika VPC yang Anda pilih untuk instans gateway di Langkah 1 berbeda dari VPC Serverless resource group. Jika VPC sama, lewati bagian ini.

       Layanan backend memungkinkan permintaan dikirim ke Data Service melintasi VPC yang berbeda.

       1. Di daftar Instance di Konsol Cloud-native API Gateway, klik ID instans target.

       2. Di panel navigasi kiri halaman detail instans, pilih Service.

       3. Klik Create Service. Jika diminta, buat sumber terlebih dahulu di tab Source.

       4. Saat Create Service, konfigurasikan nama layanan dan asosiasikan dengan sumber yang telah dibuat.

       Untuk informasi lebih lanjut, lihat Buat layanan.

Publikasikan ke beberapa instans gateway

Di panel Version, temukan versi dengan status Can Be Published lalu klik Publish. Di kotak dialog Publish API to Cloud-native API Gateway, pilih Gateway Instance yang berbeda. Anda dapat mengulangi operasi ini untuk memublikasikan API yang sama ke beberapa instans gateway.

Versi ganda di Manajemen Layanan

Setelah API dipublikasikan ke beberapa instans gateway, tampilan di halaman Service Management berubah sebagai berikut.