文档中心 > 通讯录管理

获取CorpSecret授权范围

更新时间:2018/01/03 访问次数:91336

获取CorpSecret授权范围

使用场景

钉钉已经支持企业管理员动态调整ISV开发者用到的token及可获取到的企业通讯录范围(之前token是可以获取企业全部通讯录组织架构的),在ISV开发者获取到可以访问企业通讯录接口的token后,在正式获取通讯录数据前,首先应该调用本接口,获取当前token能够读取到的通讯录部门及人员范围,再依次遍历本接口返回的部门id列表,调用通讯录接口获取每个部门及其子部门的数据。另外,在套件收到【向ISV推送授权变更消息】回调后,也需要调用本接口来同步通讯录数据。

举个例子,某企业的通讯录包含两个部门和三个员工,分别是部门A(员工甲、员工乙)和部门B(员工丙)。
以前,在企业对ISV的套件授权后,ISV可以通过/department/list接口获取部门A和部门B,再通过/user/simplelist接口获取到员工甲、员工乙及员工丙的userid,最后通过/user/get获取所有三个员工的详细信息,完成通讯录同步。

现在,在企业对ISV的套件授权时,管理员可以选择只授权一部分通讯录数据给ISV,针对本例,假如只授权了员工甲及部门B,当ISV再调用/department/list接口时,部门A和部门B的id都不再返回,会返回错误[部门不在授权范围内]。这会导致ISV无法获取管理员授予的全部数据,这时ISV应该调用本次新增的/auth/scopes接口获取管理员授予的全部数据范围,接口会返回部门B的id及员工甲的userid,然后isv再通过/department/list?id={部门B的id}获取部门B的子部门(本例中为空),通过/user/get接口获取员工甲的详细信息。

需要注意的是,如果ISV在通过企业会话发送消息时,如果接收者是未授权的员工userid或部门id,也会返回错误[员工或部门不在授权范围内]。

为了方便ISV平滑迁移,我们暂定在2017年4月10日之后新创建的套件默认采用按部门授权的策略,之前创建的套件,如需要开启,请通过工单形式提供suiteKey,由我们手动开启。需要注意的是,在正式套件开启前,一定要先建立一个测试套件,对功能完整测试后,再申请对正式套件开启。

在套件开启按部门授权功能后,企业管理员可以在如下位置进行授权范围的调整,钉钉客户端->工作TAB->管理->选择应用->设置->授权使用范围。

请求说明

Https请求方式: GET

https://oapi.dingtalk.com/auth/scopes?access_token=ACCESS_TOKEN

返回结果

{
    "errcode": 0,
    "errmsg": "created",
    "auth_user_field": ["name","email"],
    "condition_field":["contact_call"],
    "auth_org_scopes":{
	"authed_dept":[1,2,3],
	"authed_user":["user1","user"],
    }
}
参数 说明 详细
errcode 返回码
errmsg 对返回码的文本描述内容
auth_user_field 可以得到的企业用户字段 name:员工名称,email员工邮箱 具体参见user/get接口字段描述
condition_field ISV可以直接使用企业的功能字段 contact_call:isv是否可以电话联系企业管理员
authed_dept 企业授权的部门id列表 返回值为授权部门id的并集。 (设置“全部员工”时,返回授权的部门id为根部门ID,员工userid列表为空)
authed_user 企业授权的员工userid列表 返回值为授权人员id的并集。(设置“仅为管理员可见”时,返回所有的管理员id。授权的部门id列表为空)

FAQ

关于此文档暂时还没有FAQ
返回
顶部