Panduan lengkap pemanggilan API

Panduan ini menuntun developer melalui seluruh proses pemanggilan API DingTalk Open Platform, mulai dari membuat aplikasi hingga panggilan API yang berhasil. Panduan ini mencakup langkah-langkah utama, contoh kode, hal-hal yang perlu diperhatikan, dan metode debugging untuk membantu developer memulai dengan cepat dan memanggil API dengan sukses.

Contoh ini berbasis aplikasi internal dan menunjukkan cara mengambil detail pengguna dari Kontak dengan memanggil API. Pendekatan yang sama berlaku untuk tipe aplikasi lainnya.

Prasyarat

Konsep dasar: Pahami konsep dasar DingTalk Open Platform dan dokumentasi setiap modul produk. Lihat dokumentasi konsep dasar untuk detailnya.
Batas laju API: Pahami batas laju API. Lihat dokumentasi frekuensi pemanggilan API dan batas laju untuk detailnya.
Izin developer: Miliki izin Sub Admin dan developer di Developer Backend. Anda juga dapat masuk ke DingTalk Developer untuk mendaftar dan mengaktifkan pengguna baru.
Peroleh UserId pengguna: Masuk ke DingTalk Admin Console dan lihat UserId di bawah Contacts > User management. Lihat dokumentasi konsep dasar untuk detailnya.

Langkah 1: Buat aplikasi DingTalk

Buka Developer Backend dan klik App Development > DingTalk App > Create app.

Masukkan informasi aplikasi dan klik Save.

Bidang	Wajib	Deskripsi
Nama aplikasi	Ya	Masukkan nama aplikasi. Panjang minimum adalah 2 karakter.
Deskripsi aplikasi	Ya	Jelaskan secara singkat produk atau layanan yang disediakan aplikasi. Panjang minimum adalah 4 karakter.
Ikon aplikasi	Tidak	Unggah ikon aplikasi. Ikon harus dalam format JPG atau PNG, minimal 240 px * 240 px, dengan rasio aspek 1:1, tanpa sudut membulat, dan tidak lebih besar dari 2 MB.

Buka halaman detail aplikasi dan lihat kredensial serta informasi dasar aplikasi di bawah Basic information > Credential and basic information.
Simpan Client ID dan Client Secret aplikasi untuk pemanggilan API berikutnya.

Catatan

Untuk detail cara memperoleh Client ID dan Client Secret, lihat dokumentasi konsep dasar. Simpan dengan aman setelah Anda memperolehnya untuk mencegah kebocoran.

Langkah 2: Konfigurasikan izin

Temukan izin yang diperlukan: Menurut dokumentasi API, pemanggilan API detail pengguna memerlukan izin Read user information.
Tambah izin: Buka Developer Backend, temukan aplikasi yang Anda buat, buka halaman detail aplikasi, cari Read user information di bawah Kelola izin, dan klik Apply now.

Langkah 3: Peroleh Access Token

Sebelum memperoleh Access Token, tentukan apakah API memerlukan izin standar atau izin sensitif. Keduanya memiliki metode perolehan yang berbeda.

API izin standar

Panggil API untuk memperoleh Token

Buka halaman API Obtain the access token of an internal app dan klik tombol API Debug di sebelah kanan untuk membuka alat debugging sisi server.
Di alat debugging, ganti nilai appkey (ganti dengan Client ID yang Anda peroleh sebelumnya) dan appSecret (ganti dengan Client Secret yang Anda peroleh sebelumnya), lalu klik Debug.

Penting

Anda harus masuk untuk menggunakan konsol debugging sisi server dan harus mengikat aplikasi yang sesuai. Anda juga dapat menyalin kode di bawah ini dan menggunakan perintah cURL. Ganti nilai appkey (dengan Client ID yang Anda peroleh sebelumnya) dan appSecret (dengan Client Secret yang Anda peroleh sebelumnya), lalu kirim permintaan secara langsung. Contoh:

curl -X POST 'https://api.dingtalk.io/v1.0/oauth2/accessToken' \
  -H 'Content-Type: application/json' \
  -d '{
    "appKey": "Ganti dengan Client ID yang Anda peroleh sebelumnya",
    "appSecret": "Ganti dengan Client Secret yang Anda peroleh sebelumnya"
  }'

Parsing respons

Setelah panggilan berhasil, sebuah nilai access token akan dibuat, seperti ditunjukkan di bawah ini:

{
  "accessToken" : "fw8ef8we8f76e6f7s8dxxxx", # Kredensial inti
  "expireIn" : 7200 # Masa berlaku (2 jam)
}

Cache dan muat ulang

Simpan access_token dalam cache di database atau memori dan siapkan pembaruan terjadwal (10 menit sebelum kedaluwarsa).
Hindari memanggil API Token terlalu sering, karena dapat memicu batas laju.

API izin sensitif

Untuk mengaktifkan berbagi data dan pemanggilan fitur lintas organisasi, aplikasi pihak ketiga harus melalui proses otorisasi yang ketat. Aplikasi perlu memperoleh izin penggunaan dan izin akses data pengguna dari organisasi target melalui otorisasi tingkat organisasi maupun tingkat pengguna.

Ajukan izin API

Ajukan izin API sesuai dokumentasi Use sensitive permissions.

Integrasikan suite otorisasi

Setelah mengajukan izin sensitif, integrasikan suite otorisasi. Ketika pengguna menerima otorisasi pada prompt, sebuah authCode akan dikembalikan. Kemudian panggil API Obtain user token untuk menukarnya dengan access_token tingkat pengguna.

Langkah 4: Panggil API detail pengguna

API izin standar

Untuk mengambil detail pengguna, panggil API Query user details. Anda dapat menggunakan DingTalk SDK atau mengirim permintaan HTTP secara langsung. Pilih metode yang sesuai dengan kebutuhan Anda.

Opsi 1: Gunakan DingTalk SDK (direkomendasikan)

Sebelum menggunakan DingTalk SDK, pelajari perbedaan dalam Server API, lalu unduh versi SDK yang sesuai. Lihat dokumentasi perbedaan Server API untuk detailnya.

Instal SDK (contoh Python)
pip install dingtalk-sdk

Contoh kode

# -*- coding: utf-8 -*-
import dingtalk.api

req=dingtalk.api.OapiV2UserGetRequest("https://api.dingtalk.io/topapi/v2/user/get")

req.userid="zhangsan"  # Ganti dengan ID pengguna yang sebenarnya
req.language="zh_CN"
try:
	resp= req.getResponse(access_token)
	print(resp)
except Exception,e:
	print(e)

Opsi 2: Kirim permintaan HTTP secara langsung

curl -i 'https://api.dingtalk.io/topapi/v2/user/get' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -d '{"userid":"Ganti dengan ID pengguna yang sebenarnya","language":"zh_CN"}'

Respons berhasil

Jika respons berisi "errcode":"0" dan "errmsg":"ok", panggilan berhasil.

{
        "errcode":"0",
        "result":{
                "extension":"{\"Hobby\":\"Travel\",\"Age\":\"24\"}",
                "unionid":"z21HjQliSzpw0YWxxxxx",
                "boss":"true",
                "role_list":{
                        "group_name":"Position",
                        "name":"Director",
                        "id":"100"
                },
                "exclusive_account":false,
                "manager_userid":"manager240",
                "admin":"true",
                "remark":"Remark",
                "title":"Technical Director",
                "hired_date":"1597573616828",
                "userid":"zhangsan",
                "work_place":"Future Park",
                "dept_order_list":{
                        "dept_id":"2",
                        "order":"1"
                },
                "real_authed":"true",
                "dept_id_list":"[2,3,4]",
                "job_number":"4",
                "email":"test@xxx.com",
                "leader_in_dept":{
                        "leader":"true",
                        "dept_id":"2"
                },
                "mobile":"13800138000",
                "active":"true",
                "org_email":"test@xxx.com",
                "telephone":"010-86123456-2345",
                "avatar":"xxx",
                "hide_mobile":"false",
                "senior":"true",
                "name":"John",
                "union_emp_ext":{
                        "union_emp_map_list":{
                                "userid":"5000",
                                "corp_id":"dingxxx"
                        },
                        "userid":"500",
                        "corp_id":"dingxxx"
                },
                "state_code":"86"
        },
        "errmsg":"ok"
}

Penanganan error

Izin tidak memadai: Periksa apakah izin Read user information telah diajukan.
Pengguna tidak ada: Pastikan userid valid dan bebas dari kesalahan ketik.
Token kedaluwarsa: Muat ulang access_token dan coba lagi. Pastikan access_token valid dan bebas dari kesalahan ketik.

API izin sensitif

Setelah menukar authCode dengan access_token tingkat pengguna, panggil Retrieve user profile from Contacts untuk memperoleh nama, unionId, dan informasi lain pengguna. Jika API mengembalikan 200, panggilan berhasil. Responsnya adalah sebagai berikut:

{
  "nick" : "zhangsan",
  "avatarUrl" : "https://xxx",
  "mobile" : "150xxxx9144",
  "openId" : "123",
  "unionId" : "z21HjQliSzpw0Yxxxx",
  "email" : "zhangsan@example.com",
  "stateCode" : "86"
}

Panduan pemanggilan API

Autentikasi & otorisasi

Kontak

Kalender

Konferensi

AI Table

Dokumen & file

IM

Prasyarat

Langkah 1: Buat aplikasi DingTalk

Catatan

Langkah 2: Konfigurasikan izin

Langkah 3: Peroleh Access Token

API izin standar

Panggil API untuk memperoleh Token

Penting

Parsing respons

Cache dan muat ulang

API izin sensitif

Ajukan izin API

Integrasikan suite otorisasi

Langkah 4: Panggil API detail pengguna

API izin standar

Opsi 1: Gunakan DingTalk SDK (direkomendasikan)

Opsi 2: Kirim permintaan HTTP secara langsung

Respons berhasil

Penanganan error

API izin sensitif

​Prasyarat

​Langkah 1: Buat aplikasi DingTalk

​Catatan

​Langkah 2: Konfigurasikan izin

​Langkah 3: Peroleh Access Token

​API izin standar

​Panggil API untuk memperoleh Token

​Penting

​Parsing respons

​Cache dan muat ulang

​API izin sensitif

​Ajukan izin API

​Integrasikan suite otorisasi

​Langkah 4: Panggil API detail pengguna

​API izin standar

​Opsi 1: Gunakan DingTalk SDK (direkomendasikan)

​Opsi 2: Kirim permintaan HTTP secara langsung

​Respons berhasil

​Penanganan error

​API izin sensitif

Prasyarat

Langkah 1: Buat aplikasi DingTalk

Catatan

Langkah 2: Konfigurasikan izin

Langkah 3: Peroleh Access Token

API izin standar

Panggil API untuk memperoleh Token

Penting

Parsing respons

Cache dan muat ulang

API izin sensitif

Ajukan izin API

Integrasikan suite otorisasi

Langkah 4: Panggil API detail pengguna

API izin standar

Opsi 1: Gunakan DingTalk SDK (direkomendasikan)

Opsi 2: Kirim permintaan HTTP secara langsung

Respons berhasil

Penanganan error

API izin sensitif