Deskripsi panggilan API
- API ini hanya mengembalikan detail pengguna dalam departemen yang ditentukan. Pengguna dalam sub-departemen tidak dikembalikan.
-
API ini dapat mengembalikan detail pengguna akun reguler maupun pengguna Akun Perusahaan dalam sebuah departemen. Karena penggunaan parameter sangat berbeda antara kedua skenario tersebut, dokumentasi dipisah berdasarkan tipe akun agar lebih jelas:
- Untuk mendapatkan detail pengguna akun reguler dalam sebuah departemen, lihat dokumen ini.
- Untuk mendapatkan detail pengguna Akun Perusahaan dalam sebuah departemen (biasanya pengguna Enterprise DingTalk), lihat Mendapatkan detail pengguna Akun Perusahaan dalam sebuah departemen.
Permintaan
| Informasi dasar | |
|---|---|
| URL HTTP | https://api.dingtalk.io/topapi/v2/user/list |
| Metode HTTP | POST |
| Tipe aplikasi yang didukung | appType-Aplikasi internal, appType-Aplikasi perusahaan pihak ketiga |
| Izin yang diperlukan | permission-qyapi_get_department_member-Izin baca untuk anggota departemen di Kontak |
Parameter kueri
| Nama | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| access_token | String | Ya | bE74xxxx | Kredensial aplikasi yang digunakan untuk memanggil API ini. - Untuk aplikasi internal, dapatkan melalui API untuk mendapatkan access_token aplikasi internal. - Untuk aplikasi perusahaan pihak ketiga, dapatkan melalui API untuk mendapatkan access_token perusahaan pihak ketiga. |
Isi permintaan
| Nama | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| dept_id | Number | Ya | 10 | ID departemen. Panggil Mendapatkan daftar departemen untuk mendapatkannya. Untuk departemen root, setel parameter ini ke 1. Catatan Hanya pengguna dalam departemen saat ini yang dikembalikan. Pengguna dalam sub-departemen tidak disertakan. |
| cursor | Number | Ya | 0 | Cursor untuk kueri berhalaman. Setel ke 0 untuk panggilan pertama, lalu gunakan nilai next_cursor yang dikembalikan oleh panggilan sebelumnya. |
| size | Number | Ya | 10 | Ukuran halaman. |
| order_field | String | Tidak | modify_desc | Aturan pengurutan untuk anggota departemen. Jika tidak ditentukan, defaultnya adalah pengurutan kustom (custom): - entry_asc: urutkan berdasarkan waktu bergabung ke departemen secara menaik. - entry_desc: urutkan berdasarkan waktu bergabung ke departemen secara menurun. - modify_asc: urutkan berdasarkan waktu modifikasi informasi departemen secara menaik. - modify_desc: urutkan berdasarkan waktu modifikasi informasi departemen secara menurun. - custom: urutkan berdasarkan urutan yang ditentukan pengguna (atau berdasarkan pinyin jika tidak ditentukan). |
| contain_access_limit | Boolean | Tidak | false | Apakah mengembalikan pengguna dengan akses terbatas: - true: kembalikan. - false: jangan kembalikan. |
| language | String | Tidak | zh_CN | Bahasa untuk Kontak: - zh_CN: Bahasa Tionghoa (default). - en_US: Bahasa Inggris. |
Contoh permintaan
curl -X POST "https://api.dingtalk.io/topapi/v2/user/list" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=834f6b00-25b8-4484-a89d-595d1f7fa0a7' \
-d 'contain_access_limit=false' \
-d 'cursor=0' \
-d 'dept_id=10' \
-d 'language=zh_CN' \
-d 'order_field=modify_desc' \
-d 'size=10'
DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/list");
OapiV2UserListRequest req = new OapiV2UserListRequest();
req.setDeptId(1L);
req.setCursor(0L);
req.setSize(10L);
req.setOrderField("modify_desc");
req.setContainAccessLimit(false);
req.setLanguage("zh_CN");
OapiV2UserListResponse rsp = client.execute(req, "");
System.out.println(rsp.getBody());
import dingtalk.api
req=dingtalk.api.OapiV2UserListRequest("https://api.dingtalk.io/topapi/v2/user/list")
req.dept_id=10
req.cursor=0
req.size=10
req.order_field="modify_desc"
req.contain_access_limit=false
req.language="zh_CN"
try:
resp= req.getResponse(access_token)
print(resp)
except Exception,e:
print(e)
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');
$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiV2UserListRequest;
$req->setDeptId("10");
$req->setCursor("0");
$req->setSize("10");
$req->setOrderField("modify_desc");
$req->setContainAccessLimit("false");
$req->setLanguage("zh_CN");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/v2/user/list");
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/list");
OapiV2UserListRequest req = new OapiV2UserListRequest();
req.DeptId = 10L;
req.Cursor = 0L;
req.Size = 10L;
req.OrderField = "modify_desc";
req.ContainAccessLimit = false;
req.Language = "zh_CN";
OapiV2UserListResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
Respons
Isi respons
| Nama | Tipe | Contoh | Deskripsi |
|---|---|---|---|
| errcode | Number | 0 | Kode pengembalian. |
| errmsg | String | ok | Deskripsi kode pengembalian. |
| result | Object | Hasil yang dikembalikan. | |
| has_more | Boolean | true | Apakah ada data lainnya: - true: ya. - false: tidak. |
| next_cursor | Number | 10 | Cursor untuk halaman berikutnya. Catatan Jika has_more bernilai false, tidak ada lagi data berhalaman. |
| list | Object[] | Daftar informasi pengguna. | |
| userid | String | zhangsan | ID pengguna. |
| unionid | String | z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ | Pengenal unik pengguna dalam cakupan akun perusahaan developer saat ini. |
| name | String | John | Nama pengguna. |
| avatar | String | xxx | URL foto profil. |
| state_code | String | 86 | Kode panggilan internasional. Catatan - Jika bidang ini tidak dikembalikan untuk aplikasi internal, periksa apakah Izin untuk mengakses nomor ponsel karyawan telah diaktifkan pada izin Kontak aplikasi saat ini. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. Untuk mendapatkan state_code, gunakan suite otorisasi terpadu DingTalk. |
| mobile | String | 13800138000 | Nomor ponsel. Catatan - Jika bidang ini tidak dikembalikan untuk aplikasi internal, periksa apakah Izin untuk mengakses nomor ponsel karyawan telah diaktifkan pada izin Kontak aplikasi saat ini. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. Untuk mendapatkan mobile, gunakan suite otorisasi terpadu DingTalk. |
| hide_mobile | Boolean | false | Apakah nomor ponsel disembunyikan: - true: disembunyikan. Saat disembunyikan, nomor ponsel disembunyikan pada halaman Profil, tetapi pengguna lain masih dapat mengirim DING atau memulai panggilan bisnis gratis DingTalk ke nomor ini. - false: tidak disembunyikan. |
| telephone | String | 010-86123456-2345 | Nomor ekstensi. Catatan Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. |
| job_number | String | 4 | ID Karyawan. |
| title | String | Technical Director | Jabatan. |
| String | test@xxx.com | Email karyawan. Catatan - Jika bidang ini tidak dikembalikan untuk aplikasi internal, periksa apakah izin Email dan informasi pribadi lainnya telah diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika memiliki nilai pada panel informasi pengguna. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. | |
| org_email | String | test@xxx.com | Email Perusahaan karyawan. Catatan - Jika bidang ini tidak dikembalikan untuk aplikasi internal, periksa apakah izin Email dan informasi pribadi lainnya telah diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika memiliki nilai pada panel informasi pengguna. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. |
| work_place | String | Future Park | Lokasi kerja. Catatan - Jika bidang ini tidak dikembalikan untuk aplikasi internal, periksa apakah izin Email dan informasi pribadi lainnya telah diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika memiliki nilai pada panel informasi pengguna. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. |
| remark | String | Remark | Alias. Catatan - Jika bidang ini tidak dikembalikan untuk aplikasi internal, periksa apakah izin Email dan informasi pribadi lainnya telah diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika memiliki nilai pada panel informasi pengguna. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. |
| dept_id_list | Number[] | [2,3,4] | Daftar ID departemen yang menjadi tempat pengguna bernaung. |
| dept_order | Number | 1 | Urutan pengguna dalam departemen. |
| extension | String | {"Hobby":"Travel","Age":"24"} | Atribut yang diperluas. Catatan - Jika bidang ini tidak dikembalikan untuk aplikasi internal, periksa apakah izin Email dan informasi pribadi lainnya telah diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika memiliki nilai pada panel informasi pengguna. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. |
| hired_date | Number | 1597573616828 | Tanggal perekrutan, dalam bentuk Unix timestamp dalam milidetik. Catatan Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. |
| active | Boolean | true | Apakah pengguna telah mengaktifkan DingTalk: - true: sudah diaktifkan. - false: belum diaktifkan. |
| admin | Boolean | true | Apakah pengguna adalah admin organisasi: - true: ya. - false: tidak. |
| boss | Boolean | true | Apakah pengguna adalah pimpinan organisasi: - true: ya. - false: tidak. |
| leader | Boolean | true | Apakah pengguna adalah pemimpin departemen: - true: ya. - false: tidak. |
| exclusive_account | Boolean | false | Apakah pengguna adalah Akun Perusahaan: - true: ya. - false: tidak. Catatan - Untuk pengenalan tentang Akun Perusahaan, lihat Ikhtisar Akun Perusahaan. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. |
Contoh isi respons
{
"errcode":"0",
"result":{
"next_cursor":"10",
"has_more":"true",
"list":{
"leader":"true",
"extension":"{\"Hobby\":\"Travel\",\"Age\":\"24\"}",
"unionid":"z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ",
"boss":"true",
"exclusive_account":"false",
"admin":"true",
"remark":"Remark",
"title":"Technical Director",
"hired_date":"1597573616828",
"userid":"zhangsan",
"work_place":"Future Park",
"dept_id_list":"[2,3,4]",
"job_number":"4",
"email":"test@xxx.com",
"dept_order":"1",
"mobile":"13800138000",
"active":"true",
"telephone":"010-86123456-2345",
"avatar":"xxx",
"hide_mobile":"false",
"org_email":"test@xxx.com",
"name":"John",
"state_code":"86"
}
},
"errmsg":"ok"
}
Kode error
Jika error dikembalikan saat Anda memanggil API ini, temukan solusinya di Kode error global berdasarkan pesan error.| Kode error (errcode) | Pesan error (errmsg) | Solusi |
|---|---|---|
| 400002 | Invalid parameter | Periksa apakah parameter telah diisi sesuai ketentuan. |
| 50004 | The department is out of the permission scope | Periksa apakah access_token memiliki izin operasi. |
| 40035 | Invalid parameter | Nilai dept_id, cursor, size, atau order_field tidak memenuhi persyaratan. |
| 60019 | Failed to get users from the department | Periksa apakah parameter terkait telah diisi dengan benar. |
| -1 | System busy | Coba lagi nanti. |