Buat dan konfigurasi sumber data API - Quick BI

Topik ini menjelaskan cara membuat sumber data API.

Prasyarat

Anda telah membuat antarmuka API.

Batasan

Fitur sumber data API tidak didukung di situs internasional (alibabacloud.com).
Hanya Edisi Profesional yang mendukung pembuatan sumber data API.
Ketika metode koneksi sumber data API adalah mode koneksi langsung, volume data yang dikembalikan oleh setiap permintaan harus memenuhi kondisi berikut: tidak lebih dari 10 MB, tidak lebih dari 100 kolom, dan tidak lebih dari 1.000 baris.

Entri Fitur

Anda dapat mengakses halaman pembuatan sumber data API melalui salah satu dari dua metode berikut:

Pergi ke halaman pembuatan sumber data dari entri pembuatan sumber data, dan pilih sumber data API.
Anda juga dapat Tambahkan Sumber Data API pada antarmuka manajemen sumber data API.

Prosedur

Membuat sumber data API baru terutama melibatkan tiga langkah: membangun koneksi API, menguraikan hasil permintaan, dan pengaturan sinkronisasi data.

Langkah 1: Membangun Koneksi API

Pada langkah ini, Anda perlu mengonfigurasi informasi autentikasi dasar, metode koneksi, dan pengaturan parameter untuk koneksi API. Instruksi spesifik adalah sebagai berikut:

Konfigurasikan informasi untuk setiap item di bawah Autentikasi Dasar.

Nama Parameter	Deskripsi
Connection Name	Nama kustom antarmuka API yang ditampilkan dalam daftar sumber data Quick BI. Nama dapat terdiri dari karakter Cina, angka, huruf, garis bawah (_), atau tanda hubung (-).
Interface Address	Masukkan alamat permintaan antarmuka API.
Request Type	Pilih tipe permintaan antarmuka API. Dua jenis didukung: GET dan POST. Defaultnya adalah GET. GET: Biasanya digunakan untuk meminta sumber daya di server. Ini adalah perilaku pengambilan data dan tidak dapat mengubah data di server. POST: Biasanya digunakan untuk mengirimkan data ke server, seperti mengirimkan formulir. Ini dapat mengubah data di server.

Pilih Metode koneksi. Anda dapat memilih antara Ekstrak atau Koneksi Langsung.
- Ekstrak: Mendukung pembaruan data manual atau terjadwal secara berkala. Cocok untuk skenario dengan kebutuhan data real-time rendah.
- Koneksi Langsung: Mendukung koneksi langsung ke API untuk pembaruan data real-time. Cocok untuk skenario dengan volume data kecil dan kebutuhan real-time tinggi.
  Metode koneksi langsung mendukung pengaktifan Cache Jangka Pendek, dengan opsi waktu cache 5 menit, 10 menit, atau 30 menit. Setelah diaktifkan, ini dapat menghindari permintaan berulang dalam periode tertentu, melindungi kinerja akses layanan API sumber dan menghemat biaya panggilan layanan API.
  Catatan
  Dalam mode koneksi langsung, volume data yang dikembalikan oleh setiap permintaan harus memenuhi kondisi berikut: tidak lebih dari 10 MB, tidak lebih dari 100 kolom, dan tidak lebih dari 1.000 baris.

(Opsional) Konfigurasikan data yang perlu dilewatkan sebagai parameter di Pengaturan Parameter. Anda dapat memutuskan apakah akan mengonfigurasi ini berdasarkan kebutuhan Anda.

Nama Parameter	Deskripsi
Common Parameters	Parameter setelah alamat permintaan adalah parameter umum, dalam format `url?key1=value1&key2=value2`. Anda dapat mengklik Add Parameter untuk melewatkan parameter melalui parameter umum. Misalnya, untuk antarmuka API dengan volume data besar, Anda dapat meminta melalui halaman dengan menyediakan parameter dinamis `${PageIndex}` .Untuk informasi rinci tentang parameter, lihat Pengenalan Parameter.
Header Parameters	Parameter yang disimpan di Header adalah parameter header. Biasanya, nilai konstan dilewatkan melalui Header. Anda dapat menambahkan (①), menghapus (②), dan memodifikasi (③) parameter header secara manual. Untuk informasi rinci tentang parameter, lihat Pengenalan Parameter.
Request Body	Ketika Tipe Permintaan di Autentikasi Dasar adalah POST, Anda dapat mempertahankan informasi badan permintaan dalam pengaturan parameter. Badan permintaan biasanya digunakan untuk membawa data yang perlu dikirim pengguna ke server. Anda perlu menulis konten dan format spesifiknya sesuai dengan isi bidang API saat ini. Quick BI mendukung dua format badan permintaan: JSON dan x-www-form-urlencoded. JSON: Memproses struktur data kompleks, cocok untuk skenario di mana data mencakup objek bersarang atau larik. x-www-form-urlencoded: Memproses data pasangan kunci-nilai sederhana, cocok untuk skenario pengiriman formulir sederhana.
Authorization Verification	Anda dapat memilih tanpa verifikasi otorisasi, atau pilih Basic Authentication atau Digest Authentication. Untuk informasi spesifik, lihat HTTP autentikasi 01 autentikasi dasar dan autentikasi digest.
Pre-request	Jika Anda perlu melakukan beberapa pekerjaan persiapan atau langkah verifikasi sebelum meminta API, misalnya, jika Anda perlu mendapatkan Token melalui antarmuka otentikasi untuk berhasil memanggil API saat ini, Anda dapat mengatur permintaan awal untuk API saat ini. Setelah pengaturan, sistem akan mengeksekusi "pre-requests" yang telah ditambahkan secara berurutan sebelum memanggil API utama. Sistem juga mendukung penyimpanan hasil respons dari permintaan ini sebagai parameter dinamis, yang dapat dirujuk di header parameter API utama, parameter umum, badan permintaan, atau pre-requests lainnya untuk mencapai pengambilan parameter dinamis. Untuk contoh penggunaan pre-requests, lihat Operation Example. Catatan Maksimal 3 permintaan awal didukung.

Klik Uji koneksi, dan setelah berhasil, lanjutkan ke Langkah berikutnya.

Langkah 2: Menguraikan Hasil Permintaan

Di area Struktur Data di bawah bagian Menguraikan Hasil Permintaan, semua bidang yang dikembalikan oleh permintaan API saat ini akan ditampilkan. Anda dapat memilih bidang sesuai kebutuhan dan memodifikasi tipe bidangnya.

Catatan

Dalam mode ekstrak, hanya parameter yang dipilih yang akan disinkronkan ke sistem Quick BI.
Saat memilih bidang, mereka harus berada pada level yang sama, jika tidak penguraian akan gagal.
Anda dapat melihat nilai bidang yang dipilih di area Pratinjau Data.

Langkah 3: Pengaturan Sinkronisasi Data

Di bagian Pengaturan Sinkronisasi Data, atur siklus pembaruan untuk sumber data API.

Klik kotak pilihan Siklus Pembaruan, dan dalam daftar dropdown, pilih siklus pembaruan untuk sumber data API. Anda dapat memilih pembaruan manual atau pembaruan terjadwal.
Catatan
Siklus pembaruan hanya perlu dikonfigurasi ketika metode koneksi dalam pengaturan koneksi adalah ekstrak.
- Pilih Pembaruan Manual, dan sinkronisasi data hanya akan terjadi ketika dipicu secara manual.
- Pilih Pembaruan Terjadwal dan konfigurasikan frekuensi pembaruan (harian atau per jam), dan sinkronisasi data akan terjadi pada waktu yang dijadwalkan setiap hari.
Klik Selesai untuk membuat sumber data API. Setelah berhasil, Anda dapat melihat sumber data yang Anda buat di antarmuka manajemen sumber data API.
Anda dapat mengedit sumber data API dengan mengklik ikon di sebelah kanan sumber data API.
Catatan
Metode koneksi tidak dapat diedit.

Pengenalan Parameter

Quick BI mendukung penyesuaian parameter dalam bentuk pasangan kunci-nilai di parameter umum dan parameter header sesuai dengan kebutuhan panggilan API aktual, untuk membantu integrasi sumber data API yang sukses. Pengenalan parameter adalah sebagai berikut:

Parameter tetap: Parameter dengan nilai tetap adalah parameter tetap, dalam format KeyA = ValueA, contohnya: user=myname.
Parameter variabel: Parameter dengan nilai yang berubah secara dinamis adalah parameter variabel, dalam format KeyA = ${ValueA}, contohnya: mydate=${bizdate}.
Quick BI memiliki parameter variabel bawaan yang kaya, termasuk Variabel sistem, Fungsi sistem dan parameter dinamis lainnya, yang memberikan metode penulisan parameter yang akurat dan standar sambil memungkinkan Anda menerapkan parameter variabel dengan cepat. Untuk informasi spesifik tentang parameter variabel bawaan, lihat Parameter Variabel Bawaan di bawah ini.

Parameter Variabel Bawaan

Anda dapat mengklik ikon di sebelah kanan kotak input nilai parameter untuk memilih parameter bawaan dari panel variabel yang muncul.

Variabel Sistem

Saat ini, variabel sistem yang disediakan oleh Quick BI mencakup Variabel bertipe tanggal dan Variabel bertipe paginasi. Rentang efektifnya mencakup: alamat antarmuka, parameter umum, parameter header, badan permintaan, dan permintaan awal.

Variabel bertipe tanggal

Variabel sistem bertipe tanggal terdiri dari dua bagian: parameter tanggal dasar dan offset interval waktu:

Tanggal parameter dinamis: Menyediakan offset berdasarkan tanggal bisnis.
- {yyyyMMdd} adalah tanggal bisnis, yaitu hari sebelum tanggal pembaruan data saat ini, yaitu T-1.
Jam parameter offset: Menyediakan offset berdasarkan jam.
- HH mewakili jam
- mm mewakili menit
- ss mewakili detik
- Offset jam: delta/24
Contohnya, ekspresi untuk 1 jam sebelum waktu bisnis yang ditentukan adalah: ${HH-1/24}.
Menit parameter offset: Menyediakan offset berdasarkan menit.
- HH mewakili jam
- mm mewakili menit
- ss mewakili detik
- Offset menit: delta/24/60
Contohnya, 1 menit sebelum tanggal bisnis: ${HHmmss-1/24/60}.
Detik saat ini tidak didukung.

Variabel sistem	Deskripsi variabel	Tanggal saat ini	Nilai aktual
${yyyyMMdd}	Hari sebelum tanggal pembaruan data saat ini, yaitu T-1.	2022-01-10	20220109
${yyyy-MM-dd}	Hari sebelum tanggal pembaruan data saat ini, yaitu T-1.	2022-01-10	2022-01-09
${yyyy-MM}	Ekstrak bagian tahun dan bulan dari tanggal pembaruan saat ini.	2022-01-10	2022-01
${yyyy}	Ekstrak bagian tahun dari tanggal pembaruan saat ini.	2022-01-10	2022
${yyyy/MM/dd HH:mm:ss}	Ekstrak tanggal pembaruan saat ini dan ubah ke format yyyy/MM/dd HH:mm:ss.	2022-01-10	2022/01/09 00:00:00
${HH}	Ekstrak bagian jam dari tanggal pembaruan saat ini.	2022-01-10	00
${timestamp}	Ekstrak timestamp dari permintaan saat ini, dalam detik	1725936000	2024-11-11 00:00:00

Variabel bertipe paginasi

Dalam mode ekstrak, sumber data API mendukung Pagination Requests.

Catatan

Secara default, maksimum 1.000 catatan per halaman dan maksimum 100 halaman didukung.
Ketika satu halaman mengembalikan lebih dari 1.000 catatan, tugas sinkronisasi saat ini akan melaporkan kesalahan dan keluar.
Baik permintaan GET maupun POST didukung. Contoh permintaan adalah sebagai berikut.

Variabel sistem	Deskripsi variabel	Contoh
${PageIndex}	Menunjukkan bahwa parameter yang ditandai adalah nomor halaman awal untuk paginasi, defaultnya adalah 1.	${PageIndex} mulai mengambil data dari halaman 1 secara default.
${PageIndex:num}	Menunjukkan bahwa parameter yang ditandai adalah nomor halaman awal untuk paginasi, dengan nomor halaman awal ditentukan sebagai num.	${PageIndex:2} akan mulai mengambil data dari halaman 2.

Fungsi Sistem

Rentang efektif fungsi sistem: alamat antarmuka, parameter umum, parameter header, badan permintaan, permintaan awal.

Fungsi sistem	Deskripsi fungsi	Contoh
BI_MD5(String data)	Mengembalikan hasil setelah enkripsi MD5	b10a8db164e0754105b7a99be72e3fe5

Parameter Dinamis

Tab Parameter Dinamis hanya menampilkan parameter dinamis yang telah dibuat di Permintaan Awal. Rentang efektif parameter dinamis: alamat antarmuka, parameter umum, parameter header, badan permintaan, permintaan awal.

Contoh Operasi

Contoh berikut mendemonstrasikan pembuatan sumber data API menggunakan API Dapatkan Data Kehadiran Pengguna DingTalk, untuk membantu Anda lebih memahami dan memulai operasi pembuatan sumber data API.

Contoh ini mengikuti tiga langkah yang dijelaskan dalam bagian Prosedur dari topik ini: membangun koneksi API, menguraikan hasil permintaan, dan pengaturan sinkronisasi data.

Langkah 1: Membangun Koneksi API

Dalam fase membangun koneksi API, konfigurasikan informasi sesuai dengan langkah-langkah berikut:

Konfigurasikan informasi Autentikasi Dasar.
- Nama Koneksi: Dalam contoh ini, kami menggunakan makna bisnis antarmuka API sebagai nama, memasukkan Dapatkan Data Kehadiran Pengguna.
- Alamat Antarmuka: Dapatkan alamat permintaan dari halaman dokumentasi API.
- Tipe Permintaan: Dapatkan tipe permintaan dari halaman dokumentasi API. Dalam contoh ini, itu adalah POST.
Konfigurasikan Metode Koneksi.
Dalam contoh ini, kami hanya perlu mendapatkan data kehadiran untuk hari saat ini, dengan kebutuhan real-time rendah, sehingga metode koneksi diatur ke Ekstrak.
Konfigurasikan Permintaan Awal.
Sebelum memanggil antarmuka Dapatkan Data Kehadiran Pengguna (selanjutnya disebut antarmuka API utama), Anda perlu mendapatkan access_token melalui antarmuka Dapatkan enterprise internal application access_token dan menyuntikkannya ke alamat permintaan antarmuka API utama untuk berhasil memanggil antarmuka API utama untuk mendapatkan data kehadiran. Oleh karena itu, dalam contoh ini, kita perlu mengonfigurasi langkah mendapatkan access_token dalam permintaan awal dan menggunakannya sebagai parameter umum untuk ditambahkan ke alamat permintaan antarmuka API utama. Operasi konfigurasi permintaan awal spesifik adalah sebagai berikut:
1. Klik Tambah Permintaan Awal di bawah tab Permintaan Awal.
2. Dalam kotak dialog Tambah Permintaan Awal, selesaikan konfigurasi berikut.
  - Nama Koneksi: Dalam contoh ini, kami memasukkan makna bisnis antarmuka autentikasi, yaitu Dapatkan enterprise internal application access_token.
  - Alamat Antarmuka: Dapatkan alamat permintaan antarmuka autentikasi melalui dokumentasi antarmuka.
  - Tipe Permintaan: Dapatkan tipe permintaan antarmuka autentikasi melalui dokumentasi antarmuka. Dalam contoh ini, itu adalah GET.
  - Parameter Umum: Menurut dokumentasi antarmuka, alamat permintaan perlu membawa parameter appkey dan appsecret, jadi tambahkan appkey dan appsecret di parameter umum dan masukkan nilai yang sesuai. Setelah selesai, parameter akan secara otomatis ditambahkan ke alamat permintaan.
  - Parameter Header: Dalam contoh ini, kami mempertahankan pengaturan default, yaitu pilih Content-Type sebagai application/json untuk memberi tahu server penerima permintaan bahwa format transmisi data adalah JSON; Connection sebagai keep-alive untuk memberi tahu server penerima permintaan bahwa permintaan saat ini memerlukan koneksi persisten.
3. Klik Uji Koneksi, dan Anda dapat melihat informasi pengembalian permintaan saat ini di modul Hasil Permintaan. Pada saat yang sama, Quick BI akan secara otomatis menguraikan bidang yang terkandung dalam hasil permintaan untuk Anda. Anda dapat memilih bidang sesuai kebutuhan di modul Parameter Dinamis untuk digunakan sebagaiparameter dinamis, dan merujuknya di API utama melalui metode ${parameter name}; atau Anda dapat mengeksekusi permintaan awal tanpa melewati parameter dinamis (yaitu tidak menyetel parameter dinamis).
  Dalam contoh ini, kita perlu melewatkan access_token yang diperoleh dalam permintaan awal sebagai parameter dinamis ke API utama, jadi kita membuat parameter dinamis access_token.
  Catatan
  Maksimal 10 parameter dinamis dapat ditambahkan.
Konfigurasikan Parameter Umum.
Dalam contoh ini, sesuai dengan persyaratan pemanggilan API utama, kita perlu merujuk parameter dinamis access_token yang dibuat dalam permintaan awal ke parameter umum API utama melalui metode ${parameter name}, jadi klik Tambah Parameter di bawah tab Parameter Umum.
Catatan
Parameter dinamis dapat dirujuk ke parameter umum, parameter header, badan permintaan API utama, atau permintaan awal lainnya. Anda dapat memilih sesuai kebutuhan dalam operasi aktual.
Masukkan nama parameter, klik ikon di kotak input nilai parameter, pilih parameter sesuai kebutuhan dari panel variabel yang muncul, lalu klik ikon untuk menyimpan konfigurasi.
Dalam contoh ini, kita perlu beralih ke tab Parameter Dinamis di panel variabel, yang menampilkan parameter dinamis yang sudah dibuat dalam alur saat ini, dan pilih ${access_token}.
Konfigurasikan Badan Permintaan.
Dalam contoh ini, tipe permintaan adalah POST, jadi kita perlu menulis badan permintaan sesuai dengan konten bidang parameter permintaan API Dapatkan enterprise internal application access_token.
- Contoh kode format JSON adalah sebagai berikut:
```
{
    "work_date": "2024-11-14",
    "userid": "user01"
}
```
- Contoh kode format x-www-form-urlencoded adalah sebagai berikut:
```
work_date=2024-11-14&userid=user01
```
Konfigurasi parameter lainnya.
Dalam contoh ini, parameter header dan verifikasi otorisasi mempertahankan pengaturan default.
Klik Uji Koneksi, dan setelah berhasil, lanjutkan ke Langkah Berikutnya.

Langkah 2: Menguraikan Hasil Permintaan

Di bagian Menguraikan Hasil Permintaan, pilih bidang yang diperlukan dan sesuaikan tipe bidangnya, lalu klik Langkah Berikutnya.

Langkah 3: Pengaturan Sinkronisasi Data

Di bagian pengaturan sinkronisasi data, atur siklus pembaruan sumber data API contoh ini ke Pembaruan Manual.
Klik Selesai untuk berhasil membuat sumber data API Dapatkan Data Kehadiran Pengguna.