|
SmartBI通过集成至钉钉实现消息、报表推送和预警等功能，并将钉钉中的机构信息和用户信息做用户同步，利用内置的用户/机构/角色同步功能将钉钉通讯录中的部门和同步到bi中来。
1、部署扩展包
注：本扩展包设计集成与钉钉通讯录用户同步功能只适用于V11-20260212后版本，旧版本不适用。
所需钉钉扩展包：钉钉扩展包，扩展包部署方式详细说明参考Wiki链接：扩展包部署 。
2、钉钉集成配置
钉钉的集成配置已有标准文档，具体可查看此文档进行配置：钉钉集成
3、钉钉通讯录机构和用户同步SmartBI
需要通过钉钉中的机构信息和用户信息做用户同步，将钉钉中的机构和用户同步到bi中来。
3.1、创建机构数据模型
进入数据准备-创建数据模型，新建java查询，首先新建部门j的ava查询：
选择类名为自定义，自定义类名：smartbi.dingding.query.DingTalkDepartmentListJavaQuery，最后点击获取默认配置后保存。
因为从通讯录同步过来的机构是从每个用户中的机构信息同步过来的，可能会存在重复、需要自定义机构ID、不需要的列和排序等，可以在数据模型中将java查询右键转换为ETL高级查询进行数据处理，bi中需要的字段为：机构ID、机构名称，其他可选具体可见机构同步计划中的字段列表。
处理完成后保存，抽取并可设置计划任务定时抽取。
3.2、创建用户数据模型
同理6.1的内容创建用户数据模型：
选择类名为自定义，自定义类名：smartbi.dingding.query.DingTalkUserListJavaQuery，最后点击获取默认配置后保存。并将java查询根据实际需求可转换为ETL高级查询进行数据处理。
bi中需要的字段为：用户ID、用户名称、所属机构ID、密码、是否强制修改密码、用户是否启用，其他可选的字段详见用户同步计划中的字段。
处理完成后保存，抽取并可设置计划任务定时抽取。
如若是没有ETL功能，则可以考虑创建好java查询后在数据模型中新建计算列，此处计算列是用clickhouse的语法，例如下图：
1、通过计算列新增【用户是否启用】字段：
2、通过计算列新增【是否强制修改密码】字段：
添加好用户同步需要的字段之后保存，并设置计划任务定时抽取：
3.3、创建用户与机构同步计划
进入运维设置-机构/用户/角色同步计划模块，创建用户同步计划，建议是将用户和机构的同步分开设置，先进行机构的同步再进行用户的同步。因为一般钉钉都有接口流量的限制，如果设置到一个计划中容易导致触发限制。
创建机构同步：
若数据模型中位进行机构号的排序，第一次执行时，机构列表会出现很多归到未父机构组下，因为同步是顺序从上到下执行同步的，有些子机构早于父机构入库造成此现象，只需要再点击同步后即可更新为正常。
创建用户同步：
4、集成与同步中易出现的问题
4.1、触发钉钉流控
用户日志中可查看同步情况，以及出现接口流量限制时的日志情况：
扩展包中已设置了单个同步时避免出现流控的限制：触发限制后休眠一秒后再执行。但多个同步同时执行时，或者同步时打开运维设置-钉钉管理-用户管理中的匹配时，还是会触发流控导致无法正常同步。
所以此情况建议将机构、用户同步计划分时执行，保证同一时间只有一个计划执行。并再同步执行完成后再进行钉钉管理的用户匹配。
4.2、钉钉中单点登录跳转网页登录后，一直在登录界面无法进入主页。
注：此问题是针对设置了钉钉网关、且集群情况下产生的，若不涉及可忽略。
可发现日志中实际钉钉用户已经匹配上完成了单点登录跳转，但随后就一直显示尚未登录或会话超时。
首先一般是多节点才会出现此情况，可以先确认bi侧代理是怎么做的，代理地址访问是否会出现会话紊乱，比如用niginx做的负载均衡并再nginx上设置了会话保持，正常负载地址访问没有问题，确认后可再确认钉钉侧的问题。
可以先查看单点登录跳转后的bi地址，若形如下图域名，不是实际的负载地址。此是因为钉钉是通过企业代理或内网穿透机制访问的bi界面，简单来说就是应用部署在内网，在外部想要访问bi只能通过钉钉单点登录跳转至这个地址登录。
钉钉的ztna-dingtalk.com是一个统一的零信任接入网关域名。当企业在钉钉后台配置了“应用代理”或“内网应用发布”功能后，钉钉会为每个内部系统生成一个唯一的子域名，格式如下：
<应用标识>-<随机字符串>.ztna-dingtalk.com
故钉钉的实现流程：
- 用户在钉钉客户端点击某个“内网应用”入口；
- 钉钉服务端验证用户身份和权限；
- 钉钉动态生成一个带临时令牌的代理URL（即这个长域名）；
- 用户浏览器访问该URL → 请求被路由到钉钉的ZTNA网关；
- 网关根据令牌解析出目标内网地址，并建立安全隧道转发请求；
- 内网服务器响应 → 经网关加密返回给用户。
所以此问题就是出在钉钉的零信任网关与Nginx 会话保持策略之间的冲突，nginx配置的策略失效，导致产生了会话紊乱。故推荐的解决方案是通过部署一个Redis会话缓存服务来实现会话保持，此操作具体可查看：安装SmartBI-Redis会话缓存服务。
| 
