API 同步_云效(Apsara Devops)-阿里云帮助中心

适用版本

专属版

API 同步支持云效站点通过集成企业提供的用户数据接口，同步企业内的用户和组织架构信息。

站点管理员可以在站点管理-第三方集成中添加和管理 API 同步，请确保 API 按照此文档中的规范提供，云效会按照配置的 URL 执行企业组织架构和用户的同步。

配置 API 同步

步骤一配置数据请求地址

支持 http、https 接口请求的 URL，请保证 URL 的准确性和接口的连通性，配置后等待接口连通性检查通过后，单击下一步。

说明

请求接口只支持 http 和 https 协议的 GET 请求；
由于此处只提供了 URL，未提供接口鉴权的额外配置方式，请自行在提供的URL中增加鉴权参数对接口调用鉴权。
如需支持分页，请在 URL 中增加第一页的分页参数，保证数据的完整性，如：?page_number=0&page_size=10，其中page_number为页码，page_size为每页用户条数。

企业接口返回数据说明

需要按照以下内容定义接口返回数据：

其中departments为users用户列表中包含的所有部门的信息，返回结果如需分页，按照用户数量进行分页，且必须保证父部门提前返回。

名称	类型	必填	描述
用户字段
user_id	string	是	用户唯一标识，全局唯一
name	string	是	用户姓名
user_name	string	是	用户登录账号名称，全局唯一
nick_name	string	否	用户昵称
staff_id	string	否	用户工号，全局唯一
email	string	是	用户邮箱，全局唯一
status	string	否	用户状态，离职状态为 leave，系统将会把状态为 leave 的用户在云效中删除
department_ids	array	是	字符串数组，包含用户所在的部门唯一标识
部门字段
department_id	string	是	部门唯一标识
name	string	是	部门名称
parent_id	string	是	父部门的唯一标识，用于生成组织架构
分页字段
next_page_number	int	否	如需要分页请将最后一页返回页码设为-1，保证分页调用的结束

示例响应结果：

{
  "users": [
    {
      "user_id": "yx12346xxx",
      "name": "周x",
      "user_name": "zhouxxx",
      "nick_name": "x外",
      "staff_id": "004xx5",
      "email": "zhouxxx@alibaba-inc.com",
      "department_ids": [
        "16xxx2"
      ]
    }
  ],
  "departments": [
    {
      "department_id": "009xxx",
      "name": "阿xxx-阿xxx群-阿xxx部",
      "parent_id": "19xxx5"
    }
  ],
  "next_page_number": 1
}

步骤二配置账号绑定与属性映射

目前提供种 4 种账号识别和绑定方式：

自动绑定邮箱相同的账号：按照同步策略，自动将云效、企业用户数据接口中邮箱账号相同的用户绑定在一起；
自动绑定登录账号相同的账号：按照同步策略，自动将云效、企业用户数据接口中登录账号相同的用户绑定在一起；
自动绑定手机号相同的账号：按照同步策略，自动将云效、企业用户数据接口中手机号相同的用户绑定在一起；
自动绑定工号相同的账号：按照同步策略，自动将云效、企业用户数据接口中工号相同的用户绑定在一起。

无论选择哪一种账号识别和绑定方式，均需要保证其对应的属性字段的唯一性和存在性，因为云效将按照选择的方式进行账号的一一匹配，如下图为选择自动绑定登录账号相同的账号的绑定过程：

云效将按照下图中字段映射关系，自动将企业内用户信息与云效中的用户信息，按照同步策略进行映射同步，目前暂不支持修改字段映射关系，确认后单击下一步。

配置和确认完成后，单击下一步。

步骤三开启用户和组织同步

当云效上未开启其他第三方的用户和组织同步功能时，可以开启用户和组织同步功能，支持配置同步时机、用户差异处理、组织差异处理的规则。

数据同步时机：默认为手动同步，并支持手动同步、定时同步的切换；
- 手动同步：需要站点管理员在有数据变更后，手动在 API 同步集成详情页面单击执行手动同步按钮完成用户和组织同步。
  提示：每次手动同步操作尽量间隔 1 个小时。
- 定时同步：配置同步的时机和规则按每天（某刻）、每周（某天某刻）、每月（某天某刻）、每隔一定时间进行同步，如果设置为定时同步，建议保存配置后完成一次手动同步，以保证数据可以及时同步至云效。
用户差异处理：默认忽略云效上多余的账号且为在同步范围内的上游账号创建云效账号并绑定，可根据诉求修改；
- 已有云效账号未匹配到上游账号-忽略：当已有云效账号未匹配到上游账号时，不删除云效上的多余账号；
- 已有云效账号未匹配到上游账号-删除云效账号：当已有云效账号未匹配到上游账号时，删除云效上的账号；
- 已有上游账号未匹配到云效账号-忽略：当已有上游账号未匹配到云效账号时，不在云效上创建新账号；
- 已有上游账号未匹配到云效账号-新建云效账号并绑定：当已有上游账号未匹配到云效账号时，会按照账号绑定和属性映射规则在云效上创建新账号，并与上游账号绑定；
组织差异处理：默认忽略云效上多余的部门节点且为在同步范围内的上游部门节点创建云效部门并绑定，可根据诉求修改；
- 已有云效部门未匹配到上游部门-忽略：当已有云效部门未匹配到上游部门时，不删除云效上的部门节点；
- 已有云效部门未匹配到上游部门-删除云效部门：当已有云效部门未匹配到上游部门时，删除云效上的部门节点；
- 已有上游部门未匹配到云效部门-忽略：当已有上游部门未匹配到云效部门时，不在云效上创建部门节点；
- 已有上游部门未匹配到云效部门-创建云效部门并绑定：当已有上游部门未匹配到云效部门时，会在云效上创建部门节点，并将两方部门节点进行绑定；

如果不开启用户和组织同步的情况下保存 API 同步集成配置，后续可以在 API 同步集成详情页面中开启。

当完成所有配置后，单击保存配置按钮即可完成 API 同步集成的配置。

查看用户和组织同步结果

在开启用户和组织同步的情况下，打开 API 同步集成详情页面，可以查看最新同步结果：未执行同步、同步成功、同步失败、部分同步成功。

关闭用户和组织同步

在 API 同步集成详情页中，已经开启用户和组织同步的情况下，可点击修改服务配置，在打开的修改配置的抽屉中可以关闭用户和组织同步，关闭后：

不解除云效账号与上游账号的绑定关系；
不再执行上游系统的用户和组织同步。

移除 API 同步集成

在 API 同步集成详情页中，可单击移除集成按钮，二次确认后即可移除 API 同步集成，移除集成后：

解除云效账号和上游账号的绑定关系；
已同步的用户和组织架构不会受到影响。