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 sebelah kiri, klik Instance.

2. Pilih wilayah dari bilah navigasi atas.

   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: Pay-as-you-go dan Subscription didukung. Untuk tujuan pengujian, Anda dapat memilih pay-as-you-go.

   • Gateway Name: Masukkan nama kustom yang mudah dikenali, seperti dataservice-prod.

   • Gateway Specification: Pilih single-node untuk pengujian atau multi-node untuk kepatuhan SLA produksi.

   • Network Access Type: Pilih Public atau Public + Private untuk mengaktifkan akses Internet. Penggunaan akses publik dikenai biaya traffic.

   • VPC: Pilih VPC.

     Penting

     Kami sangat menyarankan menggunakan VPC yang sama dengan resource group serverless pada prasyarat. Jika VPC berbeda, Anda harus membuat layanan backend secara manual nanti.

   • Zone Selection: Anda dapat memilih Auto Assign atau menetapkan instans secara manual di berbagai zona dan vSwitch.

   • Resource Group: Pilih resource group berdasarkan kebijakan manajemen resource Anda.

5. Klik Buy Now dan selesaikan pembayaran. Pembuatan instans memerlukan waktu sekitar 1 hingga 5 menit. Instans siap digunakan ketika statusnya berubah menjadi Running.

Buat instans gateway.

2. Tambahkan nama domain

Jika Anda hanya perlu mengakses API dalam VPC, Anda tidak perlu mengajukan nama domain.

Nama domain berfungsi sebagai titik masuk akses publik untuk API.

1. Di panel navigasi sebelah kiri konsol Cloud-native API Gateway, klik Domain Name. Pastikan wilayah di bagian atas sesuai dengan instans gateway.

2. Klik Add Domain Name dan konfigurasikan informasi berikut:

   • Domain Name: Masukkan nama domain Anda sendiri, seperti api.example.com. Nama domain independen yang digunakan di wilayah Tiongkok harus menyelesaikan Pendaftaran ICP.

   • Protocol: Pilih HTTPS untuk transmisi data aman. Anda juga harus memilih Sertifikat SSL yang sudah ada.

   • Other Settings: Aktifkan Force HTTPS dan Enable HTTP/2, serta pilih TLS Version sesuai kebutuhan keamanan Anda.

Tambahkan nama domain.

3. Buat REST API

REST API mengelompokkan API di bawah Base Path yang sama. Workflow DataWorks diikat ke REST API.

Dibandingkan dengan legacy API Gateway, REST API setara dengan API group.

1. Di panel navigasi sebelah kiri konsol Cloud-native API Gateway, klik API. Pastikan wilayah di bagian atas sudah benar.

2. Klik Create API. Di halaman Create API, pilih Create di bawah kartu REST API.

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

   • API Name: Beri nama koleksi API Anda. Nama harus unik secara global dalam wilayah saat ini, seperti dataservice-user-api.

   • Base Path: base path API, yang merupakan bagian dari URL. Misalnya, atur ke /v1. Jalur akses akhir akan menjadi Protocol://DomainName/BasePath/APIPath.

   • Version Management: Aktifkan sesuai kebutuhan.

Buat REST API.

1. Buat workflow

Workflow mengatur API terkait dan mengaitkannya dengan REST API di API Gateway.

1. Buka konsol DataWorks. Di panel navigasi sebelah kiri, buka Data Services > Service Development.

2. Klik ikon buat di pojok kiri atas dan pilih Create Workflow.

3. Di dialog Create Workflow, konfigurasikan pengaturan berikut:

   • Workflow Name: Masukkan nama kustom yang unik dalam ruang kerja, seperti User Query Workflow. Nama harus terdiri dari 4 hingga 50 karakter.

   • Gateway Type: Pilih Cloud-native API Gateway.

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

     Penting

     Setelah workflow dikaitkan dengan REST API, pengikatan tersebut tidak dapat diubah. Lanjutkan dengan hati-hati.

2. Hasilkan API dalam mode wizard

1. Di halaman Service Development, arahkan kursor ke ikon buat di pojok kiri atas dan klik Create API > Generate API.

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

   • Location: Pilih Workflow yang dibuat pada langkah sebelumnya (User Query Workflow).

   • API Name: Masukkan nama untuk API spesifik, seperti Query User by User ID.

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

   • Request Method: Pilih GET atau POST. Saat GET dipilih, parameter permintaan hanya dapat ditempatkan di string QUERY.

   • Response Type: Pilih JSON.

3. Klik Create untuk membuka halaman pengeditan API grafis.

   Catatan

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

3. Konfigurasi API

Di halaman pengeditan API, ikuti alur Select Table > Select Parameters > Configure Parameters untuk mendefinisikan API Anda.

1. Pilih tabel (sumber data dan tabel)

   Di bagian Select Table di sisi kiri halaman, konfigurasikan pengaturan berikut:

   • Data Source Type: Pilih MaxCompute(ODPS).

   • Data Source Name: Pilih sumber data yang Anda konfigurasikan pada 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, bagian Select Parameters di bawahnya mencantumkan semua kolom tabel.

   • Konfigurasi parameter permintaan: Pilih kolom user_id dan klik Set as Req Param.

   • Konfigurasi parameter respons: Pilih kolom user_id dan user_name lalu klik Set as Resp Param.

3. Konfigurasi detail parameter permintaan: Di tab Request Parameters di sisi kanan halaman, atur Sample Value untuk parameter user_id (misalnya, 10001). Hal ini membantu pengujian selanjutnya.

   Praktik terbaik: Tetapkan kolom yang diindeks sebagai parameter permintaan untuk mengoptimalkan performa kueri.

4. Konfigurasi resource group layanan dan lingkungan

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

   • Resource Group Type: Anda harus memilih Exclusive Resource Group for Data Service dan memilih resource group yang diasosiasikan dengan ruang kerja saat ini dari daftar drop-down.

   • Environment Configuration:

     • Timeout: Waktu maksimum Cloud-native API Gateway menunggu respons dari DataWorks, seperti 3 detik.

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

5. Mengonfigurasi otentikasi keamanan

   Di bagian otentikasi keamanan di sisi kanan, aktifkan otentikasi konsumen dan pilih jenis otentikasi.

   Catatan

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

   Metode autentikasi	Deskripsi	Skenario penerapan
   API Key	Klien menyertakan kredensial dalam setiap permintaan, dan gateway memverifikasi validitas serta izinnya. Cocok untuk operasi non-sensitif. Kurang aman dibanding JWT dan HMAC — lindungi kredensial dengan hati-hati.	Cocok untuk skenario integrasi ringan dan cepat dengan persyaratan keamanan moderat.
   JWT	Token Web JSON (JWT) menggunakan tanda tangan HMAC, RSA, atau ECDSA untuk mentransmisikan klaim yang dapat diverifikasi antara klien dan server, memungkinkan verifikasi identitas dan kontrol akses di gateway.	Cocok untuk sistem terdistribusi dan skenario Single Sign-On (SSO).
   HMAC	Klien menandatangani konten permintaan dengan kunci penandatanganan dan mengirimkan tanda tangan tersebut bersama permintaan untuk verifikasi server.	Cocok untuk skenario dengan persyaratan tinggi terhadap integritas data dan pencegahan perubahan data.

6. Simpan API: Setelah menyelesaikan semua konfigurasi, klik ikon Save di bilah alat atas.

1. Uji API

API harus lulus pengujian sebelum dapat dikirim.

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

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

3. Lihat Response Details di sisi kanan untuk memverifikasi apakah data sesuai ekspektasi. Response Duration dapat digunakan untuk mengevaluasi performa.

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

2. Kirim API

Setelah pengujian berhasil, kirim API untuk menghasilkan versi yang dapat diterapkan.

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

2. Setelah pengiriman, sistem menghasilkan versi API, yang terlihat di tab Version Management di sisi kanan.

3. Jika proses persetujuan dikonfigurasi untuk ruang kerja Anda, status versi API akan menjadi To Be Requested. Anda perlu mengklik Request to Publish untuk mengajukan permintaan. Setelah disetujui, status berubah menjadi Can Be Published.

   Jika tidak ada proses persetujuan yang dikonfigurasi, status versi biasanya langsung menjadi Can Be Published.

3. Terapkan API ke Cloud-native API Gateway

Terapkan API ke lingkungan produksi.

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

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

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

     Penting

     Semua API di bawah REST API yang sama berbagi nama domain yang sama. Mengubah nama domain saat penerapan akan memengaruhi nama domain yang digunakan untuk memanggil semua API di bawah REST API yang sama.

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

   • Backend Service:

     • Jika VPC instans gateway sama dengan VPC resource group 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 dipilih saat membuat instans gateway di Langkah 1 berbeda dari VPC resource group serverless. Jika VPC sama, lewati bagian ini.

       Layanan backend menjembatani konektivitas antara dua VPC berbeda untuk permintaan Data Service.

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

       2. Di panel navigasi sebelah kiri halaman detail instans, klik Service.

       3. Klik Create Service. Jika diminta, pertama-tama buat sumber di tab Source.

       4. Saat membuat layanan, konfigurasikan nama layanan dan asosiasikan dengan sumber yang telah Anda buat.

       Buat layanan backend.

Terapkan API ke beberapa instans gateway

Di panel Version, klik Publish untuk versi dengan status Can Be Published. Di dialog Publish API to Cloud-native API Gateway, pilih Gateway Instance yang berbeda untuk menerapkan API ke instans gateway yang sesuai. Anda dapat mengulangi langkah ini untuk menerapkan API yang sama di beberapa instans.

Dalam instans gateway yang sama, penerapan versi baru secara otomatis membatalkan penerapan versi sebelumnya. Versi di instans gateway berbeda bersifat independen dan dapat berada dalam status deployed secara bersamaan.

Tampilan multi-versi di manajemen layanan

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