Langsung ke konten utama
DingTalk OpenAPI mendukung dua metode paginasi. API yang berbeda dapat menggunakan mekanisme paginasi yang berbeda. Pilih mode paginasi yang tepat berdasarkan dokumentasi API dan skenario bisnis tertentu untuk meningkatkan efisiensi pengambilan data, mengurangi beban sisi server, dan menjaga stabilitas sistem.

​
Cakupan dan izin yang berlaku

Dokumen ini berlaku untuk jenis aplikasi berikut:
  • Aplikasi internal: Aplikasi yang dikembangkan oleh sebuah organisasi hanya untuk digunakan di dalam organisasi tersebut.
  • Aplikasi perusahaan pihak ketiga: Aplikasi yang dikembangkan oleh ISV (Independent Software Vendor) dan disediakan agar dapat diinstal serta digunakan oleh berbagai organisasi.
  • Aplikasi personal pihak ketiga: Aplikasi yang dikembangkan oleh penyedia solusi untuk pengguna DingTalk individu.

​
Izin

Sebelum memanggil DingTalk OpenAPI mana pun, pastikan aplikasi memiliki izin API yang diperlukan. Di konsol DingTalk Open Platform, selesaikan langkah-langkah berikut:
  1. Buka halaman detail aplikasi yang dituju.
  2. Klik Informasi dasar > Kredensial dan informasi dasar.
  3. Di bagian “Kelola izin”, tambahkan izin API yang diperlukan (seperti “Baca kontak” atau “Dapatkan daftar acara”).
Referensi: Cara mengajukan izin API

​
Prasyarat autentikasi

Sebelum memanggil API mana pun, dapatkan access_token yang valid untuk autentikasi dan verifikasi izin.
  • Gunakan App Key / App Secret atau Client ID / Client Secret untuk mendapatkan access_token.
  • access_token biasanya berlaku selama 7.200 detik. Simpan di cache dan muat ulang secara berkala.
  • access_token yang tidak valid atau kedaluwarsa menyebabkan API mengembalikan kode error 40001 atau 40014.
Referensi: Cara memanggil API

​
Metode 1: Paginasi nextToken

Gunakan nextToken sebagai kredensial kueri untuk membaca data secara berkelanjutan. Permintaan pertama tidak memerlukan nextToken. Untuk permintaan berikutnya, salin nilai nextToken dari respons sebelumnya ke permintaan saat ini untuk mengambil batch data berikutnya.

​
Alur permintaan

  • Untuk permintaan pertama, jangan sertakan nextToken. Server mengembalikan batch data pertama beserta nilai nextToken.
  • Untuk permintaan berikutnya, sertakan nilai nextToken dari respons sebelumnya sebagai parameter kueri untuk mengambil halaman berikutnya.
  • Ketika respons tidak lagi berisi nextToken, berarti semua data telah diambil.
Contoh: GET /v1.0/edu/grades/{identifier}/classes?nextToken=bGFzdD0xMTExMExMSZdGhlcnBhcmFtPXh4eCYuLi4u&maxResults=20

​
Istilah penting

  • nextToken: Kredensial string buram (opaque) yang dibuat oleh server dan menandai posisi konteks kueri saat ini. Klien harus meneruskannya apa adanya dan tidak boleh mengurai atau memodifikasinya.
  • maxResults: Jumlah entri maksimum yang disarankan oleh klien. Ini bukan nilai pasti. Jumlah aktual yang dikembalikan dapat lebih sedikit, bergantung pada batas sisi server atau jumlah data yang tersisa.

​
Catatan

  • Parameter maxResults membatasi jumlah maksimum catatan yang dikembalikan per permintaan. Jangan melebihi 500 untuk menghindari latensi respons.
  • Paginasi mendalam dapat menurunkan performa. Kombinasikan paginasi dengan filter jendela waktu untuk mengurangi volume data.

​
Skenario yang disarankan

  • Tugas sinkronisasi data (seperti sinkronisasi kontak atau pengambilan log)
  • Ekspor set data besar
  • Skenario dengan kebutuhan integritas data yang tinggi

​
Metode 2: Paginasi pageSize

Metode ini menggunakan logika paginasi tradisional dan cocok untuk API daftar sisi front-end (seperti daftar pengguna, daftar departemen, dan formulir persetujuan). Metode ini mengontrol pemuatan data menggunakan nomor halaman dan ukuran halaman.

​
Alur permintaan

  • Untuk permintaan pertama, atur pageNumber=1 dan tentukan jumlah catatan per halaman menggunakan pageSize.
  • Untuk setiap permintaan berikutnya, tingkatkan pageNumber hingga volume data yang dikembalikan kurang dari pageSize, yang biasanya menandakan halaman terakhir.

​
Catatan

  • Mulai panggilan pertama dengan pageNumber=1 dan tingkatkan nomor halaman untuk setiap panggilan berikutnya.
  • Metode ini tidak cocok untuk pengambilan data dalam jumlah besar dengan frekuensi tinggi, karena dapat memengaruhi performa sisi server.

​
Istilah penting

  • pageNumber: Nomor halaman permintaan saat ini, dimulai dari 1.
  • pageSize: Jumlah entri yang dikembalikan per halaman. Rentang yang disarankan adalah 10 hingga 200.

​
Skenario yang disarankan

  • Integrasi dengan kontrol paginasi front-end (seperti paginasi tabel)
  • Menampilkan data statis berskala kecil
  • Penjelajahan halaman demi halaman yang dipicu oleh tindakan pengguna

​
Rekomendasi dan praktik terbaik

​
Panduan pemilihan

  • API sinkronisasi inkremental (seperti penarikan langganan peristiwa atau pengambilan log perubahan): Gunakan metode nextToken untuk memastikan data tidak berulang atau terlewat.
  • API tampilan daftar (seperti daftar karyawan atau daftar formulir persetujuan): Gunakan metode pageSize agar mudah diintegrasikan dengan komponen paginasi front-end.

​
Ringkasan praktik terbaik

  • Untuk API sinkronisasi inkremental, gunakan Metode 1: Paginasi nextToken untuk memastikan data tidak berulang atau terlewat.
  • Untuk API tampilan daftar, gunakan Metode 2: Paginasi pageSize agar mudah diintegrasikan dengan kontrol paginasi front-end.
  • Terapkan mekanisme coba-lagi otomatis pada klien. Jika permintaan gagal karena nextToken yang tidak valid, kembali ke permintaan awal dan ambil kembali datanya.
  • Hindari nilai maxResults atau pageSize yang terlalu besar. Rentang yang disarankan adalah 10 hingga 200 untuk menyeimbangkan efisiensi transmisi jaringan dan kecepatan respons.