钉钉开发文档

角色管理

更新时间: 2019-5-23

获取角色列表

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/role/list?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
size Number 可选 20 分页大小,默认值:20,最大值200
offset Number 可选 0 分页偏移,默认值:0

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/role/list");
OapiRoleListRequest request = new OapiRoleListRequest();
request.setOffset(0L);
request.setSize(10L);

OapiRoleListResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode":0,
    "errmsg":"ok",
    "result":{
        "hasMore":false,
        "list":[
            {
                    "name":"默认",
                    "groupId":1,
                    "roles":[
                        {
                                "name":"管理员",
                                "id":1
                        }
                    ]
            }
        ]
    }
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
result
└ hasMore 是否还有更多数据
└ list
└ name 角色组名称
└ groupId 角色组id
└ roles
└ name 角色名称
└ id 角色id

获取角色下的员工列表

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/role/simplelist?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
role_id Number 必须 1203141 角色ID
size Number 可选 20 分页大小,默认值:20,最大值200
offset Number 可选 0 分页偏移,默认值:0

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/role/simplelist");
OapiRoleSimplelistRequest request = new OapiRoleSimplelistRequest();
request.setRoleId(149507736L);
request.setOffset(0L);
request.setSize(10L);

OapiRoleSimplelistResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode":0,
    "errmsg":"ok",
    "result":{
        "hasMore":false,
        "nextCursor":100,
        "list":[
            {
                    "userid":"manager7978",
                    "name":"小钉"
            }
        ]
    }
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
result
└ hasMore 是否还有更多数据
└ nextCursor 下次拉取数据的游标
└ list
└ userid 员工id
└ name 员工姓名

获取角色组

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/role/getrolegroup?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
group_id Number 必须 1 角色组的Id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/role/getrolegroup");
OapiRoleGetrolegroupRequest request = new OapiRoleGetrolegroupRequest();
request.setGroupId(149507737L);

OapiRoleGetrolegroupResponse response = client.execute(request, accessToken);

返回结果

{
    "role_group":{
        "roles":[
            {
                    "role_id":1,
                    "role_name":"出纳"
            }
        ],
        "group_name":"财务"
    },
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
role_group 角色组信息
└ roles 角色列表信息
└ role_id 角色id
└ role_name 角色名
└ group_name 角色组名

获取角色详情

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/role/getrole?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
roleId Number 必须 1 角色Id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/role/getrole");
OapiRoleGetroleRequest req = new OapiRoleGetroleRequest();
req.setRoleId(1001L);
OapiRoleGetroleResponse rsp = client.execute(req, accessToken);

返回结果

{
    "role":{
        "name":"财务",
        "groupId":1002
    },
    "errcode":0,
    "errmsg":"成功"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
role 角色信息
└ groupId 角色组id
└ name 角色名

创建角色

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/role/add_role?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
roleName String 必须 test 角色名称
groupId Number 必须 1 角色组id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/role/add_role");
OapiRoleAddroleRequest req = new OapiRoleAddroleRequest();
req.setRoleName("test");
req.setGroupId(11L);
OapiRoleAddroleResponse rsp = client.execute(req, accessToken);

返回结果

{
    "roleId":1,
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
roleId 角色id

更新角色

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/role/update_role?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
roleName String 必须 name 角色名称
roleId Number 必须 1 角色id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/role/update_role");
OapiRoleUpdateroleRequest req = new OapiRoleUpdateroleRequest();
req.setRoleId(1L);
req.setRoleName("11");
OapiRoleUpdateroleResponse rsp = client.execute(req, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容

删除角色

【注意】删除角色前,需确保角色下面的员工没有被赋予这个角色

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/role/deleterole?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
role_id Number 必须 1 角色id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/role/deleterole");
OapiRoleDeleteroleRequest request = new OapiRoleDeleteroleRequest();
request.setRoleId(149507738L);

OapiRoleDeleteroleResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容

创建角色组

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/role/add_role_group?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
name String 必须 name 角色组名称

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/role/add_role_group");
OapiRoleAddrolegroupRequest req = new OapiRoleAddrolegroupRequest();
req.setName("名称");
OapiRoleAddrolegroupResponse rsp = client.execute(req, accessToken);

返回结果

{
    "groupId":11,
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
groupId 角色组id

批量增加员工角色

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/role/addrolesforemps?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
roleIds String 必须 1,2,3,4,5 角色id list,最大列表长度:20
userIds String 必须 a,b,c,d,e 员工id list,最大列表长度:100

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/role/addrolesforemps");
OapiRoleAddrolesforempsRequest request = new OapiRoleAddrolesforempsRequest();
request.setRoleIds("149507736,149507737");
request.setUserIds("zhangsan");

OapiRoleAddrolesforempsResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容

批量删除员工角色

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/role/removerolesforemps?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
roleIds String 必须 1,2 角色标签id,最大列表长度:20
userIds String 必须 a,b 用户userId,最大列表长度:100

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/role/removerolesforemps");
OapiRoleRemoverolesforempsRequest request = new OapiRoleRemoverolesforempsRequest();
request.setRoleIds("149507736");
request.setUserIds("zhangsan");

OapiRoleRemoverolesforempsResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!