DataWorks:Panggil API

Prasyarat

Sebelum memanggil API apa pun dari DataService Studio, Anda harus memenuhi tiga prasyarat berikut:

Anda dapat mengibaratkan hubungan antara ketiga elemen ini sebagai berikut: API adalah "pintu", aplikasi adalah "kartu identitas", dan otorisasi adalah "izin masuk". Anda hanya dapat melewati pintu tersebut jika menunjukkan kartu identitas yang valid dan izin masuk yang sesuai.

Buat aplikasi (identitas aplikasi)

Aplikasi berfungsi sebagai wadah untuk kredensial yang digunakan saat memanggil API. Setiap aplikasi memiliki serangkaian informasi autentikasi independen (AppKey, AppSecret, dan AppCode), yang setara dengan akun dan kata sandi untuk aplikasi tersebut.

Aplikasi default yang dibuat secara otomatis

Saat pertama kali mempublikasikan API di DataWorks, sistem secara otomatis membuat aplikasi dengan nama yang sama dengan ruang kerja di API Gateway. Semua API dalam ruang kerja tersebut kemudian secara otomatis diotorisasi untuk aplikasi default ini. Artinya:

• Anggota dalam ruang kerja yang sama dapat langsung menggunakan kredensial aplikasi default untuk memanggil API di ruang kerja tersebut.

• Anda dapat melihat kredensial autentikasi untuk aplikasi default pada halaman Call APIs di konsol DataService Studio.

Buat aplikasi secara manual

Jika perlu mengisolasi traffic atau membedakan izin untuk pemanggil yang berbeda, Anda dapat membuat aplikasi baru secara manual di konsol API Gateway:

1. Login ke Konsol API Gateway.

2. Di panel navigasi sebelah kiri, pilih Application Management.

3. Klik Create App, lalu masukkan nama dan deskripsi untuk aplikasi tersebut.

4. Setelah aplikasi dibuat, sistem akan menghasilkan AppKey, AppSecret, dan AppCode untuknya.

Proses otorisasi

Otorisasi adalah proses pemberian izin kepada aplikasi untuk memanggil API tertentu. Hanya aplikasi yang telah diotorisasi yang dapat menggunakan kredensialnya untuk berhasil memanggil API tersebut.

Otorisasi akun lain

Saat perlu membuat API tersedia untuk ruang kerja di bawah akun Alibaba Cloud lain, Anda harus melakukan otorisasi lintas akun (cross-account authorization):

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

2. Di halaman Data Services, klik Service Management di bilah menu atas untuk membuka halaman Manage APIs.

3. Di tab Published APIs, temukan API target dan klik Authorization di kolom Tindakan.

4. Di kotak dialog API authorization, konfigurasikan parameter berikut:

   

   Parameter	Deskripsi
   API Name	Nama API yang akan diotorisasi. Parameter ini tidak dapat diubah.
   Alibaba Cloud account ID to authorize	ID akun Alibaba Cloud yang memerlukan izin untuk memanggil API ini. Anda dapat menemukan ID akun Anda di halaman .
   Authorized Workspace	Pilih nama ruang kerja di bawah akun Alibaba Cloud target.
   Authorization Validity Period	Pilih periode validitas otorisasi (diuraikan pada bagian berikut).

5. Klik Confirm untuk menyelesaikan otorisasi.

Periode validitas otorisasi

Periode validitas otorisasi menentukan rentang waktu pihak yang diotorisasi dapat memanggil API:

Lihat status otorisasi

Di halaman Manage APIs, Anda dapat melihat status otorisasi dari dua sudut pandang:

Lihat API yang diotorisasi untuk Anda panggil

Klik tab Authorized to Use untuk melihat daftar semua API yang telah diotorisasi oleh akun lain agar Anda dapat memanggilnya. Di halaman ini, Anda dapat:

• Klik Test untuk menguji API yang diotorisasi secara online. Untuk informasi lebih lanjut, lihat Uji API.

• Klik Delete untuk secara sukarela melepaskan otorisasi memanggil API tersebut.

Lihat API yang telah Anda otorisasi untuk orang lain

Klik tab Authorize Others to Use untuk melihat daftar API yang telah Anda otorisasi untuk ruang kerja lain. Di halaman ini, Anda dapat:

• Klik Test untuk menguji API yang diotorisasi secara online.

• Klik Manage untuk membatalkan atau mengubah otorisasi untuk ruang kerja tertentu.

Tiga skenario otorisasi

Granularitas otorisasi API bervariasi berdasarkan ukuran tim dan kebutuhan manajemen keamanan. Tiga skenario berikut mencakup strategi otorisasi paling umum.

Skenario 1: Satu ruang kerja, satu aplikasi bersama

Deskripsi skenario: Semua anggota ruang kerja DataWorks tunggal menggunakan aplikasi default yang sama untuk memanggil API.

Kapan digunakan: Tim kecil dengan tingkat kepercayaan tinggi di antara anggota; tidak perlu membedakan sumber traffic dari anggota berbeda; memulai cepat dengan konfigurasi minimal.

Cara kerja: Saat API dipublikasikan, DataWorks secara otomatis membuat aplikasi dengan nama yang sama dengan ruang kerja dan memberikan otorisasi untuk semua API dalam ruang kerja tersebut. Semua anggota ruang kerja berbagi AppKey, AppSecret, dan AppCode yang sama.

Kelebihan: Tidak perlu konfigurasi dan siap digunakan langsung. Kekurangan: Anda tidak dapat melacak panggilan ke anggota individu, dan kebocoran kredensial memengaruhi seluruh ruang kerja.

Skenario 2: Satu aplikasi per pengguna RAM

Deskripsi skenario: Setiap pengguna RAM (sub-akun) di perusahaan membuat aplikasi terpisah di API Gateway dan menerima otorisasi individu untuk memanggil API.

Kapan digunakan: Anda perlu melacak aktivitas panggilan API setiap pengguna secara akurat, menerapkan kebijakan pembatasan kecepatan berbeda untuk pengguna berbeda, atau memenuhi persyaratan keamanan dan kepatuhan tinggi yang mewajibkan "satu kredensial per orang".

Cara kerja: Setiap pengguna RAM login ke konsol API Gateway untuk membuat aplikasi sendiri. Administrator API memberikan otorisasi ke aplikasi setiap pengguna. Setiap pengguna kemudian memanggil API menggunakan kredensial aplikasi miliknya sendiri.

Kelebihan: Aktivitas panggilan dapat dilacak hingga pengguna individu, memberikan isolasi keamanan yang kuat. Dampak kebocoran kredensial minimal. Kekurangan: Overhead manajemen lebih tinggi karena setiap pengguna baru memerlukan pembuatan aplikasi dan konfigurasi otorisasi.

Skenario 3: Satu aplikasi per grup pengguna

Deskripsi skenario: Beberapa pengguna RAM dikelompokkan berdasarkan fungsi bisnis atau tim, dan anggota setiap grup berbagi satu aplikasi untuk memanggil API.

Kapan digunakan: Tim besar yang diorganisir berdasarkan departemen atau proyek; perlu membedakan traffic dari lini bisnis berbeda tetapi bukan dari individu; keseimbangan antara biaya manajemen dan keamanan.

Cara kerja: Aplikasi dibuat untuk setiap grup bisnis. Administrator API memberikan otorisasi API ke aplikasi setiap grup. Anggota dalam grup berbagi kredensial aplikasi grup mereka.

Kelebihan: Menawarkan tingkat granularitas manajemen moderat, memungkinkan diferensiasi tingkat bisnis tanpa overhead administratif berlebihan. Kekurangan: Tidak ada diferensiasi lebih lanjut di antara anggota dalam grup yang sama.

Perbandingan skenario

Membedakan jenis kredensial

DataService Studio melibatkan tiga jenis kredensial autentikasi yang berbeda. Penting untuk memahami tujuan, sumber, dan kasus penggunaannya yang berbeda agar tidak bingung:

Intinya: AccessKey digunakan untuk menghubungkan ke sumber data, AppKey digunakan untuk memanggil API, dan RAM digunakan untuk mengakses konsol. Masing-masing memiliki tujuan berbeda dan tidak dapat saling menggantikan.

Kebingungan umum 1: "Saya mendapat error 403 saat memanggil API, padahal saya memiliki izin administrator RAM." — Izin RAM mengontrol akses ke konsol DataWorks, bukan kemampuan memanggil API. Izin panggilan API dikontrol oleh otorisasi aplikasi. Bahkan jika Anda administrator RAM, Anda tetap memerlukan AppKey dan AppSecret dari aplikasi yang diotorisasi untuk memanggil API.

Kebingungan umum 2: "Apakah AccessKey untuk konfigurasi sumber data sama dengan AppKey untuk panggilan API?" — Tidak. AccessKey digunakan oleh backend DataService Studio untuk menghubungkan ke sumber data, sedangkan AppKey digunakan oleh pemanggil untuk memanggil API. Keduanya sepenuhnya independen.

Kebingungan umum 3: Apa yang harus saya masukkan untuk "account ID" di halaman otorisasi? — Halaman otorisasi memerlukan ID akun Alibaba Cloud (string numerik), bukan username RAM atau email login. Untuk menemukan ID akun Anda, login ke halaman Account Management dan periksa pengaturan keamanan.

Metode autentikasi

API Gateway mendukung dua metode autentikasi. Secara default, DataService Studio menambahkan "Alibaba Cloud App Authentication" ke API dalam ruang kerja. Pemanggil dapat memilih metode autentikasi tertentu berdasarkan kebutuhan keamanannya.

Autentikasi sederhana (AppCode)

Pemanggil hanya perlu menambahkan AppCode ke header permintaan HTTP untuk menyelesaikan autentikasi. Tidak diperlukan perhitungan signature.

Contoh permintaan:

GET /api/v1/users?name=test HTTP/1.1
Host: your-api-endpoint.cn-shanghai.alicloudapi.com
Authorization: APPCODE 3f963a8e1cd7492bbd8a5e2e5e4c****

Autentikasi signature (AppKey + AppSecret)

Pemanggil harus menggunakan AppSecret untuk menghitung signature HMAC-SHA256 untuk konten permintaan dan menambahkan AppKey serta nilai signature ke header permintaan. Saat API Gateway menerima permintaan, sistem akan menghitung ulang signature menggunakan AppSecret yang sama dan membandingkannya dengan signature yang diterima untuk memverifikasi identitas pemanggil.

Contoh permintaan (hanya header):

X-Ca-Key: 12345678
X-Ca-Signature: BASE64_ENCODED_SIGNATURE
X-Ca-Timestamp: 1741593600000
X-Ca-Nonce: unique-uuid-string
X-Ca-Signature-Headers: X-Ca-Key,X-Ca-Nonce,X-Ca-Timestamp

Perbandingan metode

Algoritma signature

Autentikasi signature berbasis algoritma HMAC-SHA256. Proses intinya sebagai berikut:

Proses signature

1. Buat string yang akan ditandatangani: Gabungkan metode HTTP (misalnya, GET atau POST), header Accept, Content-MD5 (nilai MD5 dari badan permintaan), Content-Type, Date, header kustom yang akan ditandatangani (X-Ca-*, diurutkan secara alfabetis), dan URL yang dinormalisasi (path + parameter kueri yang diurutkan).

2. Hitung signature menggunakan HMAC-SHA256: Signature = Base64(HMAC-SHA256(AppSecret, StringToSign))

3. Tambahkan informasi signature ke header permintaan: Ini mencakup X-Ca-Key (AppKey), X-Ca-Signature (signature), X-Ca-Timestamp (timestamp tingkat milidetik), X-Ca-Nonce (UUID untuk mencegah serangan replay), dan X-Ca-Signature-Headers (daftar header yang termasuk dalam signature).

Pertimbangan penting

Perhatikan detail berikut saat mengimplementasikan algoritma signature untuk menghindari kesalahan umum:

• Pengurutan parameter: Parameter kueri URL dan header yang termasuk dalam signature harus diurutkan secara alfabetis berdasarkan kunci (dalam urutan ASCII).

• Encoding URL: Karakter khusus dalam nilai parameter, seperti spasi atau karakter non-ASCII, harus di-URL-encode.

• Karakter baris baru: Gunakan karakter line feed (\n, LF) untuk memisahkan baris dalam string yang akan ditandatangani. Jangan gunakan kombinasi carriage return dan line feed (\r\n, CRLF).

• Penanganan nilai kosong: Jika permintaan tidak memiliki badan, nilai Content-MD5 adalah string kosong (bukan null). Jika header seperti Accept tidak ada, gunakan string kosong untuknya juga.

• Precision timestamp: X-Ca-Timestamp harus berupa timestamp tingkat milidetik. Selisih waktu antara klien dan server tidak boleh melebihi 15 menit.

• Keunikan nonce: UUID unik harus dihasilkan sebagai X-Ca-Nonce untuk setiap permintaan. Menggunakan kembali nonce akan memicu mekanisme pencegahan serangan replay.

Lihat kredensial autentikasi

Setelah membuat aplikasi dan memberikan otorisasi, Anda perlu mendapatkan AppKey, AppSecret, atau AppCode untuk melakukan panggilan API. DataService Studio menyediakan cara mudah untuk melihat kredensial ini.

Lihat kredensial di konsol DataService Studio

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

2. Di halaman DataService Studio, klik Service Management di bilah menu atas.

3. Di panel navigasi sebelah kiri, klik Call APIs.

4. Di halaman Call APIs, Anda dapat melihat dan menyalin kredensial autentikasi berikut: AppKey (pengenal unik aplikasi), AppSecret (digunakan untuk autentikasi signature; simpan kerahasiaannya), dan AppCode (digunakan untuk autentikasi sederhana).

Lihat kredensial di konsol API Gateway: Login ke konsol API Gateway, temukan aplikasi target di App Management, dan buka halaman detailnya untuk melihat AppKey, AppSecret, dan AppCode.

Panggil API dengan SDK API Gateway

API Gateway menyediakan SDK untuk berbagai bahasa pemrograman untuk membantu Anda mengintegrasikan panggilan API dengan cepat. SDK memiliki implementasi bawaan algoritma signature, sehingga Anda tidak perlu menghitung signature secara manual. Anda hanya perlu menyediakan AppKey dan AppSecret. Untuk informasi lebih lanjut, lihat dokumentasi Panggil API dan Unduh dan Penggunaan SDK.

Bahasa SDK yang didukung

Keuntungan menggunakan SDK

Dibandingkan dengan membuat permintaan HTTP secara manual, menggunakan SDK untuk memanggil API menawarkan keuntungan berikut:

• Signing otomatis: SDK mengimplementasikan algoritma signature HMAC-SHA256, sehingga developer tidak perlu menangani detail signing.

• Retry otomatis: Beberapa SDK memiliki mekanisme retry bawaan untuk pengecualian jaringan.

• Validasi parameter: SDK memvalidasi parameter dasar sebelum mengirim permintaan.

• Optimasi kinerja: SDK biasanya menggunakan pooling koneksi dan teknologi seperti HTTP/2 untuk mengoptimalkan kinerja jaringan.

Contoh integrasi cepat (Java)

Contoh berikut menunjukkan cara menggunakan SDK Java API Gateway untuk memanggil API DataService Studio:

// 1. Tambahkan dependensi Maven
// <dependency>
//     <groupId>com.aliyun.api.gateway</groupId>
//     <artifactId>sdk-core-java</artifactId>
//     <version>LATEST_VERSION</version>
// </dependency>

// 2. Inisialisasi klien
HttpClientBuilderParams params = new HttpClientBuilderParams();
params.setAppKey("your_app_key");
params.setAppSecret("your_app_secret");

ApacheHttpClient client = new ApacheHttpClient(params);

// 3. Buat permintaan
IoTApiRequest request = new IoTApiRequest();
request.setDomain("your-api-endpoint.cn-shanghai.alicloudapi.com");
request.setPath("/api/v1/query");
request.setHttpMethod("GET");
request.putQueryParam("pageSize", "10");
request.putQueryParam("pageNum", "1");

// 4. Lakukan panggilan
ApiResponse response = client.execute(request);
System.out.println("Response: " + response.getBody());

Contoh integrasi cepat (Python)

# 1. Instal SDK
# pip install aliyun-api-gateway-sdk

# 2. Panggil API
from com.alibaba.cloudapi.sdk.client import DefaultClient
from com.alibaba.cloudapi.sdk.model import HttpClientBuilderParams

params = HttpClientBuilderParams()
params.app_key = "your_app_key"
params.app_secret = "your_app_secret"
params.host = "your-api-endpoint.cn-shanghai.alicloudapi.com"

client = DefaultClient(params)
response = client.get(
    path="/api/v1/query",
    query_params={"pageSize": "10", "pageNum": "1"},
    headers={"Accept": "application/json"}
)

print(f"Status: {response.status_code}")
print(f"Body: {response.content}")

Alur kerja end-to-end

Alur kerja end-to-end dimulai ketika developer mempublikasikan API, yang secara otomatis membuat dan mengotorisasi aplikasi default. Untuk berbagi API lintas akun, pemilik harus memberikan otorisasi secara manual. Pemanggil API kemudian mendapatkan kredensial (AppKey, AppSecret, atau AppCode) dari aplikasi dan memilih metode autentikasi. Terakhir, pemanggil menggunakan SDK atau permintaan HTTP langsung untuk memanggil API. API Gateway memvalidasi permintaan, DataService Studio mengeksekusi kueri, dan hasilnya dikembalikan ke pemanggil.

Topik terkait

• Publikasikan API: Pelajari cara mempublikasikan API ke API Gateway.

• Otorisasi API: Pelajari tentang operasi otorisasi dan cara mengelola API yang telah Anda otorisasi untuk orang lain.

• Uji API: Uji API yang telah dipublikasikan atau diotorisasi di halaman Service Management.