通讯录同步开发指南

本指导适用于开发者将企业通讯录数据同步到WeLink用户管理。

准备：

  1. 调用通讯录接口都需要在应用开发——接口权限中打开“通讯录同步”接口权限。
  2. 开通接口白名单（目前暂需联系对口支持的华为同事去开通）。

开发步骤建议：

  1. 先同步部门再同步人员
  2. 选择一个部门同步，先调用部门同步接口，再调用状态查询接口确保调用成功
  3. 调用部门人员同步接口同步人员，再调用状态查询接口确保调用成功
  4. 间隔3s调用一次接口
  5. 扩大部门范围，先手动同步不开户（通过管理后台手动开户）
  6. 将手动同步改成自动同步

名词解释

  • userId： WeLink生成用户唯一标识。（userId后续将改为随机字符，请勿使用英文名作为生成userId规则）
  • deptCode： WeLink中创建部门时生成部门编码标识
  • corpUserId： 企业用户唯一标识，用户的工号或者可以指向用户唯一身份的标识
  • corpDeptCode：企业部门唯一标识
  • corpParentCode：企业部门唯一标识，相对于当前部门的上级部门标识
  • userNameEn：用户英文名，没有英文名可取拼音如zhangsan
  • valid：1表示存在，0表示删除。如果要删除该用户或者部门则指定为“0”
  • isOpenAccount: 1表示开户，用户将收到开户短信。0表示不开户，需要管理员手动未用户开户，可批量选择。

字段映射说明：

映射

1. 同步部门

部门的层级关系说明：

部门层级

部门同步接口：查看文档

https://open.welink.huaweicloud.com/api/contact/v2/departments/bulk

以财经部门同步数据为例：

{
     "corpParentCode": "Z201",
     "corpDeptCode": "Z301",
     "deptLevel": "4"
     ...
}

要点说明

  • 先创建一层部门，然后再挂靠一层部门各级子部门
  • 一层部门的corpParentCode为0
  • 完成部门同步后开始往部门中挂靠人员信息
  • 人员信息的核心字段corpDeptCode必需在WeLink系统中已经维护，否则人员挂靠不成功

同步接口为异步接口，接口仅返回当前请求是否成功，并不返回业务结果，此时可调用查询状态接口查询同步部门状态：

  • 当部门同步成功，对应的接口状态码为47119
  • 状态码为其他值同步失败，根据对应状态码查找失败原因

2. 同步人员

人员同步接口：查看文档

https://open.welink.huaweicloud.com/api/contact/v1/users/bulk

以财经部门同步人员数据为例：

{
  "corpDeptCode": "Z301",
  "corpUserId": "l00224455", // 员工唯一标识
  ...// 手机号、邮箱
}

要点说明

  • 完成部门同步后开始往部门中挂靠人员信息
  • 人员信息的核心字段corpDeptCode必需在WeLink系统中已经维护，否则人员挂靠不成功
  • isOpenAccount：0； 默认不开户
  • valid字段：0；表示删户

同步接口为异步接口，接口仅返回当前请求是否成功，并不返回业务结果，此时可调用查询状态接口查询同步人员状态：

  • 当isOpenAccount是0时，即只同步不开户，对应的接口状态码为47107
  • 当isOpenAccount是1时，同步变开户，对应的接口状态码为47109
  • 状态码为其他值同步失败，根据对应状态码查找失败原因

3. 同步周期和同步方式

  • 基于常见场景封装方法：如新建部门、新建用户、将用户添加到部门、变更用户到新部门、删除用户、删除部门、更新用户、更新部门
// 例如组织架构调整，调用封装方法
def main():
  ...
  createNewDept(deptInfo) // 新建部门
  changeUserToNewDept(userList, corpDeptCode) // 变更人员到新部门
  deleteDept(corpDeptCode) // 删除部门
  ...
  • 每3s调用一次接口，1小时可同步12000人
  • 后续改为增量同步
  • 先手动验证，再验证自动

4. 常见问题说明

  • Q: 体验阶段已经手动创建了一些部门，如何获取该部门的corpDeptCode？A: 手动创建的时候，部门ID字段为空，如果要做同步，请手动填充该字段。
  • Q: WeLink中公司名称是什么含义，一层组织怎么挂靠到公司下？A: WeLink默认公司的corpDeptCode为0，用户在同步一层部门时，请指定该部门的corpParentCode为0。
  • Q: 更改部门或者人员数据用什么接口？A: 也是使用上述的接口，该接口通过corpUserId来标识用户，修改时修改字段值再次同步即可，如需删除用户或者部门则指定Valid字段位0。
  • Q: 英文名作用是啥？没有该字段怎么办？A: 用户切换英文版后通讯录中用户将显示英文名，当前英文名还用来生成用户id，建议通过“中文转拼音”的方式或者从“用户邮箱”中提取用户英文名。
  • Q: 部门架构发生变更，该如何切换？A: 比如要删除一个旧的部门新建新的部门，同时要做人员调整。规则建议：先创建新的部门，然后变更人员的corpDeptCode到该部门，再删除旧部门。
  • Q: 调用接口时报501？ A: 请确认是否已经申请对应的API权限
  • Q: 调用接口时出现Authtication Fail. A: 联系华为人员添加白名单

结果。 ""

    无结果。 ""