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 anggota departemen Kontak |
Parameter query
| Nama | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| access_token | String | Ya | be3Fxxxx | 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 API Mendapatkan daftar departemen untuk memperoleh nilai dept_id. Catatan - Hanya karyawan di departemen saat ini yang dikembalikan. Karyawan di sub-departemen tidak termasuk. - Untuk departemen root, isi dengan 1. |
| cursor | Number | Ya | 0 | Cursor untuk paginasi. Isi dengan 0 untuk panggilan pertama, lalu isi dengan nilai next_cursor yang dikembalikan pada panggilan berikutnya. |
| size | Number | Ya | 10 | Ukuran halaman. |
| order_field | String | Tidak | modify_desc | Aturan pengurutan untuk anggota departemen. Jika parameter ini tidak diisi, hasil diurutkan berdasarkan urutan kustom (custom) secara default. - 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 (berdasarkan pinyin jika tidak ditentukan). |
| contain_access_limit | Boolean | Tidak | false | Apakah mengembalikan karyawan dengan pembatasan akses: - true: Kembalikan. - false: Jangan kembalikan. |
| language | String | Tidak | zh_CN | Bahasa untuk Kontak. - zh_CN: Bahasa Mandarin (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=8d4de2xxxx49c' \
-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(10L);
req.setCursor(0L);
req.setSize(10L);
req.setOrderField("modify_desc");
req.setContainAccessLimit(false);
req.setLanguage("zh_CN");
OapiV2UserListResponse rsp = client.execute(req, access_token);
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 yang tersedia: - true: Ya. - false: Tidak. | |
| next_cursor | Number | 10 | Cursor untuk paginasi berikutnya. Catatan Jika has_more bernilai false, tidak ada lagi data paginasi. | |
| list | Object[] | Daftar informasi pengguna. | ||
| userid | String | zhangsan | userId dari pengguna. | |
| unionid | String | z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ | Identifier 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 - Untuk aplikasi internal, jika bidang ini tidak dikembalikan, periksa apakah Izin untuk mengakses nomor ponsel karyawan diaktifkan pada izin Kontak aplikasi saat ini. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. Untuk memperoleh state_code, gunakan suite otorisasi terpadu DingTalk. | |
| mobile | String | 13800138000 | Nomor ponsel. Catatan - Untuk aplikasi internal, jika bidang ini tidak dikembalikan, periksa apakah Izin untuk mengakses nomor ponsel karyawan diaktifkan pada izin Kontak aplikasi saat ini. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. Untuk memperoleh mobile, gunakan suite otorisasi terpadu DingTalk. | |
| hide_mobile | Boolean | false | Apakah nomor ponsel disembunyikan: - true: Disembunyikan. Setelah nomor ponsel disembunyikan, nomor tersebut disembunyikan pada halaman Profil, tetapi pesan DING dan panggilan bisnis DingTalk tetap dapat dikirim ke nomor tersebut. - 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 - Untuk aplikasi internal, jika bidang ini tidak dikembalikan, periksa apakah izin Email dan profil lainnya diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika bidang email memiliki nilai di panel informasi karyawan. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. | ||
| org_email | String | test@xxx.com | Email Perusahaan karyawan. Catatan - Untuk aplikasi internal, jika bidang ini tidak dikembalikan, periksa apakah izin Email dan profil lainnya diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika memiliki nilai di panel informasi karyawan. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. | |
| work_place | String | Future Park | Lokasi Kerja. Catatan - Untuk aplikasi internal, jika bidang ini tidak dikembalikan, periksa apakah izin Email dan profil lainnya diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika memiliki nilai di panel informasi karyawan. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. | |
| remark | String | Remarks | Alias. Catatan - Untuk aplikasi internal, jika bidang ini tidak dikembalikan, periksa apakah izin Email dan profil lainnya diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika memiliki nilai di panel informasi karyawan. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. | |
| dept_id_list | Number[] | [2,3,4] | Daftar ID departemen tempat karyawan berada. | |
| dept_order | Number | 1 | Urutan pengurutan karyawan dalam departemen. | |
| extension | String | {"Hobby":"Travel","Age":"24"} | Atribut tambahan. Catatan - Untuk aplikasi internal, jika bidang ini tidak dikembalikan, periksa apakah izin Email dan profil lainnya diaktifkan pada izin Kontak aplikasi saat ini. - Bidang ini hanya dikembalikan ketika memiliki nilai di panel informasi karyawan. - Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. | |
| hired_date | Number | 1597573616828 | Tanggal perekrutan, sebagai Unix timestamp dalam milidetik. Catatan Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. | |
| active | Boolean | true | Apakah DingTalk telah diaktifkan: - true: Diaktifkan. - false: Tidak diaktifkan. | |
| admin | Boolean | true | Apakah pengguna adalah admin organisasi: - true: Ya. - false: Tidak. | |
| boss | Boolean | true | Apakah pengguna adalah pimpinan (boss) organisasi: - true: Ya. - false: Tidak. | |
| leader | Boolean | true | Apakah pengguna adalah pemimpin departemen: - true: Ya. - false: Tidak. | |
| exclusive_account | Boolean | true | Apakah pengguna adalah Akun Perusahaan: - true: Ya. - false: Tidak. Catatan Parameter ini tidak dikembalikan untuk aplikasi perusahaan pihak ketiga. | |
| login_id | String | login_id3 | Nama masuk (sign-in) Akun Perusahaan di organisasi Anda. Catatan Bidang ini hanya dikembalikan untuk Akun Perusahaan DingTalk yang termasuk dalam organisasi Anda. | |
| exclusive_account_type | String | dingtalk | sso | Tipe Akun Perusahaan. - sso: Akun Perusahaan yang dibuat oleh organisasi. - dingtalk: Akun Perusahaan yang dibuat oleh DingTalk. Catatan Bidang ini hanya dikembalikan untuk Akun Perusahaan. |
| nickname | String | Name | Nama Akun Perusahaan. Catatan Bidang ini hanya dikembalikan untuk Akun Perusahaan yang dibuat oleh organisasi Anda. | |
| exclusive_account_corp_name | String | Organization Name | Nama organisasi tempat Akun Perusahaan berada. Catatan Hanya berlaku untuk Akun Perusahaan. Mengembalikan nama organisasi yang membuat Akun Perusahaan tersebut. | |
| exclusive_account_corp_id | String | corpxxx | ID organisasi tempat Akun Perusahaan berada. Catatan Hanya berlaku untuk Akun Perusahaan. Mengembalikan ID organisasi dari organisasi yang membuat Akun Perusahaan tersebut. | |
| disable_status | Boolean | true | Status dinonaktifkan Akun Perusahaan di organisasi Anda: - true: Dinonaktifkan. - false: Diaktifkan. Catatan Bidang ini hanya dikembalikan untuk Akun Perusahaan DingTalk yang termasuk dalam organisasi Anda. |
Contoh respons
{
"errcode":"0",
"result":{
"next_cursor":"10",
"has_more":"true",
"list":{
"leader":"true",
"exclusive_account_type":"dingtalk|sso",
"extension":"{\"Hobby\":\"Travel\",\"Age\":\"24\"}",
"unionid":"z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ",
"boss":"true",
"exclusive_account":"true",
"admin":"true",
"remark":"Remarks",
"title":"Technical Director",
"hired_date":"1597573616828",
"userid":"zhangsan",
"work_place":"Future Park",
"nickname":"Name",
"dept_id_list":"[2,3,4]",
"job_number":"4",
"email":"test@xxx.com",
"dept_order":"1",
"login_id":"login_id3",
"exclusive_account_corp_name":"Organization Name",
"mobile":"13800138000",
"active":"true",
"telephone":"010-86123456-2345",
"avatar":"xxx",
"hide_mobile":"false",
"exclusive_account_corp_id":"corpxxx",
"org_email":"test@xxx.com",
"name":"John",
"state_code":"86"
}
},
"errmsg":"ok"
}
Kode error
Jika error dikembalikan saat memanggil API ini, temukan solusinya di dokumen 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 not within the permission scope | Pastikan access_token memiliki izin operasi. |
| 40035 | Invalid parameter | dept_id, cursor, size, atau order_field diisi dengan tidak benar. |
| 60019 | Failed to get users from the department | Pastikan parameter terkait diisi dengan benar. |
| -1 | System busy | Coba lagi nanti. |