DataWorks:Pengujian, penerbitan, dan manajemen versi API

Uji API dalam pengembangan

Anda dapat menguji API dalam pengembangan di halaman Service Development, yaitu lingkungan pengujian. Sebelum menguji API, Anda harus terlebih dahulu membuatnya dalam mode wizard atau mode skrip, atau mendaftarkan layanan yang sudah ada sebagai API.

Prosedur:

1. Masuk ke Konsol DataWorks. Di wilayah target, klik Data Analysis and Service > DataService Studio di panel navigasi kiri. Pilih ruang kerja dari daftar drop-down dan klik Go to DataService Studio.

2. Dari daftar API di sebelah kiri, klik ganda nama API yang ingin diuji untuk membuka halaman editnya.

3. Di halaman edit API, temukan dan klik tombol Test untuk membuka kotak dialog Test APIs.

4. Di panel kiri kotak dialog, masukkan nilai uji untuk setiap parameter permintaan.

5. Klik Start Test untuk memicu pemanggilan API.

Lihat hasil pengujian:

Setelah pengujian selesai, Anda dapat melihat informasi berikut di panel kanan kotak dialog:

• Request Details: Menampilkan informasi permintaan lengkap untuk pemanggilan API, termasuk path permintaan, header, dan body. Hal ini membantu Anda memverifikasi bahwa struktur permintaan sudah benar.

• Response Details: Menampilkan data respons dari API, yaitu hasil kueri aktual. Anda dapat membandingkan konten respons dengan hasil yang diharapkan untuk memastikan logika API sudah benar.

• Response Duration: Menampilkan waktu respons end-to-end untuk permintaan API. Anda dapat menggunakan informasi ini untuk mengevaluasi performa API. Jika latensi tinggi, pertimbangkan untuk mengoptimalkan logika kueri atau konfigurasi sumber data.

Jika pengujian gagal, tinjau pesan kesalahan yang dikembalikan, lakukan perubahan yang diperlukan, lalu uji kembali API tersebut.

Uji API yang telah diterbitkan

Anda dapat menguji API yang telah diterbitkan di halaman Service Management, yang berfungsi sebagai lingkungan produksi. Hal ini memungkinkan Anda memverifikasi perilaku API di lingkungan produksi. Sebelum melakukan pengujian ini, Anda harus menerbitkan API terlebih dahulu.

Prosedur:

1. Di halaman Data Services, klik Service Management di bilah navigasi atas.

2. Di panel navigasi kiri, klik Test APIs.

3. Dari daftar drop-down, pilih API yang ingin diuji dan pastikan nilai telah dikonfigurasi untuk semua parameter permintaan.

4. Klik Start Test dan lihat Request Details dan Response Details di panel kanan.

Catatan:

• Halaman Test APIs hanya menyediakan fungsi pengujian online. Anda tidak dapat menggunakan halaman ini untuk memperbarui contoh respons normal API.

• Jika API dikonfigurasi dengan Pagination for Return Results, apakah data yang dikembalikan diurutkan bergantung pada sumber data dasarnya. Untuk memastikan pengurutan, Anda dapat mengonfigurasi Sort field untuk API dalam mode wizard atau menambahkan klausa ORDER BY ke kode SQL dalam mode skrip.

Interpretasi dan optimasi hasil pengujian

Hasil pengujian API yang lengkap terdiri dari tiga bagian. Memahami setiap bagian membantu Anda mengidentifikasi masalah dengan cepat:

Jika hasil pengujian sudah sesuai harapan, Anda dapat menerbitkan API ke API Gateway.

Prasyarat

Sebelum menerbitkan API, pastikan persyaratan berikut terpenuhi:

• API Gateway diaktifkan: Buka Konsol API Gateway untuk mengaktifkan layanan tersebut.

  Penting

  Karena keterbatasan arsitektur jaringan antara DataWorks dan API Gateway, saat Anda membeli instans API Gateway, hanya instans khusus yang didukung untuk Instance Type. Instans integrasi VPC belum didukung.

• Grup API dibuat: Saat API diterbitkan, API tersebut di-deploy ke grup API Gateway yang terkait dengan Proses Bisnisnya. Pastikan Proses Bisnis tersebut telah dikaitkan dengan grup API Gateway yang benar. Anda dapat memverifikasi nama grup dengan mengklik kanan Workflow dan memilih Change.

Proses penerbitan

Proses penerbitan API mengikuti tiga langkah: Submit → Approve → Publish.

Langkah 1: Kirim API

1. Buka halaman Data Services. Di daftar API pada halaman Service Development, klik ganda nama API yang ingin diterbitkan untuk membuka halaman editnya.

2. Di pojok kanan atas, klik Submission.

3. Submission yang berhasil secara otomatis menghasilkan versi API, seperti V1 atau V2. Anda dapat melihat status versi ini di panel Version yang muncul di sebelah kanan.

Langkah 2: Ajukan permintaan penerbitan dan tunggu persetujuan

1. Di panel Version di sebelah kanan, temukan versi API yang ingin diterbitkan dan klik Publish.

2. Ikuti petunjuk di layar untuk memasukkan alasan permintaan, lalu klik Requested Permissions untuk mengirimkan permintaan penerbitan.

3. Jika proses persetujuan dikonfigurasi untuk ruang kerja, permintaan penerbitan harus ditinjau di Pusat Persetujuan DataWorks. Pemberi persetujuan dapat melihat detail permintaan dan memprosesnya di halaman Approval Center > To Be Processed.

4. Setelah disetujui, status API di panel Version berubah dari To Be Requested menjadi Can Be Published.

Langkah 3: Terbitkan API

1. Setelah permintaan disetujui, di halaman edit API, klik Version di panel navigasi kanan. Temukan versi API dengan status Can Be Published.

2. Klik tombol Publish dan tunggu hingga sistem menunjukkan bahwa penerbitan berhasil.

3. Setelah API diterbitkan, DataWorks men-deploy-nya ke grup API Gateway yang terkait dengan Proses Bisnis API tersebut.

Verifikasi penerbitan

Setelah diterbitkan, Anda dapat memverifikasi dan mengelola API dengan cara berikut:

• Tampilan di API Gateway: Masuk ke Konsol API Gateway. Di panel navigasi kiri, pilih Manage APIs > Service List untuk melihat informasi API yang telah dipublikasikan. Anda juga dapat mengonfigurasi kebijakan seperti pembatasan kecepatan dan kontrol akses.

• Pemanggilan dari aplikasi: Jika API ditujukan untuk aplikasi Anda sendiri, Anda perlu membuat aplikasi di API Gateway, memberi otorisasi aplikasi untuk mengakses API, lalu memanggilnya menggunakan signature terenkripsi dengan AppKey dan AppSecret. API Gateway juga menyediakan SDK untuk bahasa pemrograman utama guna membantu Anda mengintegrasikan API ke dalam aplikasi dengan cepat. Untuk informasi lebih lanjut, lihat Contoh pemanggilan API. Untuk integrasi SDK, lihat Unduh dan gunakan SDK.

• Perubahan protokol: Untuk API yang telah diterbitkan, buka tab Service Management > Published APIs. Di kolom Actions untuk API tersebut, pilih More > Change Protocol untuk mengubah protokol aksesnya, misalnya dari HTTP ke HTTPS. Perubahan protokol berlaku segera. Namun, jika Anda menghapus protokol aslinya, pemanggilan API menggunakan protokol tersebut akan gagal. Lakukan dengan hati-hati.

Daftarkan di Alibaba Cloud Marketplace (opsional)

Alibaba Cloud Marketplace mencakup berbagai kategori luas dan dapat membantu Anda mencapai monetisasi data.

Setelah API yang dibuat atau didaftarkan di DataService Studio diterbitkan ke API Gateway, Anda dapat mendaftarkannya di Alibaba Cloud Marketplace untuk dijual. Hal ini membantu perusahaan mencapai monetisasi data dan menyelesaikan proses komersialisasinya.

Persyaratan:

• Hanya akun perusahaan yang dapat bergabung dengan Alibaba Cloud Marketplace.

• Sebelum mendaftarkan API, Anda harus bergabung dengan Alibaba Cloud Marketplace sebagai ISV. Untuk informasi lebih lanjut tentang prosesnya, lihat Proses onboarding Alibaba Cloud Marketplace.

Prosedur:

1. Buka portal ISV Alibaba Cloud.

2. Di panel navigasi kiri, klik Commodity > Commodity Manager.

3. Klik Create Product.

4. Di halaman Access Information, konfigurasikan parameter sesuai panduan, seperti nama produk, strategi penetapan harga, dan pengikatan API, untuk menyelesaikan proses pendaftaran.

Lihat riwayat versi

1. Masuk ke Konsol DataWorks. Di wilayah target, klik Data Analysis and Service > DataService Studio di panel navigasi kiri. Pilih ruang kerja dari daftar drop-down dan klik Go to DataService Studio.

2. Di daftar API pada halaman Service Development, klik ganda nama API yang ingin dilihat untuk membuka halaman editnya.

3. Klik tombol Version di sisi kanan halaman untuk membuka panel versi dan melihat informasi serta detail versi. Panel ini menampilkan semua informasi versi historis untuk API saat ini, termasuk:

   Catatan

   Kolom Actions untuk setiap versi menyediakan tautan API Details. Anda dapat mengkliknya untuk melihat informasi konfigurasi lengkap untuk versi tersebut, termasuk parameter permintaan, parameter respons, dan konfigurasi sumber data.

   Bidang	Deskripsi
   API ID	Pengenal unik untuk API saat ini.
   Version	Nomor versi, yang bertambah setiap kali submission (V1, V2, V3...).
   Submitted By	Pengguna yang melakukan submission versi ini.
   Submitted At	Waktu submission versi ini, akurat hingga detik.
   Status	Publish (Versi live saat ini) Can Be Published (versi yang telah diuji dan diajukan) Batch Synchronization (Versi historis)

Bandingkan versi

Saat API telah mengalami beberapa iterasi, Anda mungkin perlu membandingkan versi berbeda untuk memahami perubahan spesifiknya.

Prosedur:

1. Di panel Version, pilih dua versi yang ingin dibandingkan.

2. Klik tombol Compare di bagian bawah panel.

3. Di kotak dialog History Version Contrast yang muncul, lihat perbedaan antara kedua versi tersebut.

Detail perbandingan:

• API mode wizard: Perbandingan menunjukkan perbedaan pada parameter permintaan dan respons, termasuk perubahan pada nama parameter, tipe, dan apakah parameter tersebut wajib diisi.

• API mode skrip: Perbandingan menunjukkan perbedaan teks pada skrip SQL, menyorot baris kode yang ditambahkan, dihapus, dan dimodifikasi.

Fitur perbandingan versi sangat berguna dalam skenario kolaboratif, membantu pemeriksa memahami secara cepat rincian setiap perubahan.

Rollback versi

Jika versi baru menyebabkan masalah atau tidak sesuai harapan, Anda dapat dengan cepat melakukan rollback API ke versi stabil sebelumnya.

Prosedur:

1. Di panel Version, temukan versi historis target.

2. Di kolom Actions untuk versi tersebut, klik Roll Back.

3. Di kotak dialog Confirm that you want to roll back the current version, klik Confirm.

Strategi manajemen versi

Kebiasaan manajemen versi yang baik dapat secara signifikan mengurangi risiko insiden online:

• Lacak perubahan: Saat melakukan submission perubahan, jelaskan secara jelas modifikasi dan alasannya dalam catatan submission. Hal ini membantu anggota tim memahami konteks di balik perubahan tersebut dengan menggunakan perbandingan versi.

• Validasi canary: Untuk perubahan besar, kami sarankan Anda melakukan validasi menyeluruh di lingkungan pengujian sebelum menerbitkan ke lingkungan produksi.

• Rollback cepat: Jika ditemukan masalah online, prioritaskan penggunaan fitur rollback versi untuk memulihkan layanan sebelum menyelidiki akar penyebabnya. Melakukan rollback versi lebih cepat daripada memodifikasi dan menerbitkan ulang, sehingga meminimalkan dampak bisnis.

• Pembersihan rutin: Kami sarankan Anda segera membatalkan penerbitan dan menghapus API yang tidak lagi digunakan untuk mengurangi kompleksitas manajemen dan potensi risiko keamanan.

Alur kerja kolaboratif

Dalam skenario kolaborasi tim, kami sarankan alur kerja berikut:

1. Developer membuat dan mengonfigurasi API di halaman Service Development.

2. Developer melakukan pengujian di lingkungan pengembangan untuk memastikan fungsionalitasnya benar.

3. Developer melakukan submission API, menghasilkan versi baru dan memulai permintaan penerbitan.

4. Pemberi persetujuan meninjau permintaan penerbitan di Pusat Persetujuan DataWorks dan dapat menggunakan fitur perbandingan versi untuk melihat perubahannya.

5. Setelah disetujui, developer melakukan operasi penerbitan akhir.

6. Insinyur operasi melakukan pengujian online dan pemantauan API yang telah diterbitkan di halaman Service Management.

7. Jika ditemukan masalah, layanan segera dipulihkan dengan melakukan rollback versi, atau API dibatalkan penerbitannya untuk diperbaiki.

Dengan mengikuti proses ini, tim dapat mengelola seluruh siklus hidup API secara efisien sekaligus memastikan kualitas rilis.

Batasan contoh respons

Halaman edit API memungkinkan Anda menetapkan Normal Response Example, yang digunakan untuk menampilkan struktur data respons yang diharapkan dalam dokumentasi API. Perhatikan batasan berikut:

• Tidak ada sinkronisasi otomatis: Respons dari pengujian API tidak secara otomatis memperbarui contoh respons normal API. Anda harus mengedit atau menempelkan contoh respons secara manual di halaman edit API.

• Batas ukuran: Contoh respons normal memiliki batas karakter. Jika data contoh terlalu besar, misalnya berisi ratusan catatan, penyimpanan mungkin gagal. Kami sarankan Anda hanya menyertakan 2 hingga 3 catatan khas sebagai contoh.

• Perubahan berlaku setelah penerbitan: Setelah memodifikasi contoh respons normal, Anda harus melakukan submission ulang dan menerbitkan API agar perubahan berlaku di dokumentasi API Gateway.

Penanganan perubahan skema sumber data

Saat skema tabel sumber data yang terkait dengan API berubah, seperti penambahan, penghapusan, atau modifikasi tipe bidang, API yang telah diterbitkan tidak secara otomatis mendeteksi perubahan tersebut. Kegagalan menangani perubahan ini dapat menyebabkan masalah berikut:

Prosedur:

1. Buka halaman edit API dan modifikasi konfigurasi API agar mencerminkan perubahan skema.

   1. Mode wizard: Pilih ulang tabel, dan sistem akan secara otomatis memperbarui daftar bidang.

   2. Mode skrip: Modifikasi secara manual nama bidang atau tabel dalam pernyataan SQL.

2. Setelah menyimpan konfigurasi, uji kembali API untuk memverifikasi perubahan.

3. Lakukan submission dan terbitkan ulang API.