AI 助理
备案控制台
文档
产品文档
输入文档关键字查找
首页

（独立部署）开通钉钉微应用

更新时间：
一键部署
产品详情
相关技术圈
我的收藏

Quick BI支持钉钉集成，包括钉钉微应用、钉钉通讯录同步、订阅告警消息推送钉钉、钉钉OA审批等能力。本文为您介绍Quick BI独立部署客户如何配置钉钉企业内应用以及如何进行钉钉接口授权，主要内容包括钉钉内部应用创建、接口开通和基础配置等。

前提条件

  • 您的钉钉账号，具有您所在钉钉企业的钉钉开发者后台开发权限。

  • 您企业下的私有化部署的Quick BI服务，能够访问公网钉钉服务。

    # 钉钉公网服务域名有两个：oapi.dingtalk.com和api.dingtalk.com
# 通过ping的方式，判断您机器的网络是否能通钉钉的公网服务。
ping oapi.dingtalk.com
ping api.dingtalk.com

  • 仅适用于公网SaaS版钉钉，并不适用私有化部署钉钉。

创建钉钉企业内应用

创建应用

在开放平台里进入开发者后台后，选择对应的组织并进入后，选择企业内部应用->钉钉应用，按照下图所示步骤创建应用。

image

参数名称

参数描述

示例

应用名称

必填。名称可以由中文、数字以及字母组成，长度在2-20个字符之间。

Quick BI微应用。

应用描述

必填。简要描述应用提供的产品或服务，长度不超过200个字符。

应用图标

必填。上传JPG/PNG格式、240*240px以上、1:1 、2MB 以内的无圆角图标。

image

应用权限管理

单击进入应用详情页面后，单击开发配置->权限管理。权限范围选择全部员工，接口授权按照以下表格进行开通：

image

权限一级分类

权限信息

权限点code

权限说明

个人权限

个人手机号信息

Contact.User.mobile

必须。用于钉钉登录获取用户访问凭证。

通讯录个人信息读权限

Contact.User.Read

必须。用于钉钉登录获取用户访问凭证。

调用SNS API时需要具备的基本权限

snsapi_base

默认开通

通讯录管理

企业员工手机号信息

fieldMobile

可选。用于同步钉钉通讯录

邮箱等个人信息

fieldMail

可选。用于同步钉钉通讯录

通讯录部门信息读权限

qyapi_get_department_list

必须。用于同步钉钉通讯录

成员信息读权限

qyapi_get_member

必须。用于同步钉钉通讯录

通讯录部门成员读权限

qyapi_get_department_member

必须。用于同步钉钉通讯录

OA审批

工作流实例写权限

Workflow.Instance.Write

可选。用于钉钉OA审批集成；

工作流模板读权限

Workflow.Form.Read

工作流实例读权限

Workflow.Instance.Read

考勤

调用企业API基础权限

qyapi_base

默认开通

应用管理

管理微应用的权限

qyapi_microapp_manage

必选。用于同步钉钉通讯录

获取凭证

调用OpenApp专有API时需要具备的权限

open_app_api_base

必选。用于钉钉登录获取用户访问凭证。

应用配置

  1. 应用CorpId、AgentId、AppKey、AppSecret获取

    • CorpId：您可以在开发者后台首页获取。

      image

    • AgentId、AppKey、AppSecret：进入对应应用后，您可以在基础信息->凭证与基础信息页面中进行获取。

      image

  2. 相关地址配置

    • 微应用首页地址配置

      • 您可以在应用能力目录下的添加应用能力页面中，选择网页应用并单击配置。

        image

      • 在网页应用配置页面，配置首页地址。

        image

        配置项说明如下：

        配置项

        配置说明

        填写示例

        应用首页地址

        必填。配置移动端钉钉工作台Quick BI微应用入口地址。格式：http(s)://{host}/m/home?appKey={your_appKey}&dd_orientation=auto

        其中{host}以您实际的Quick BI公网域名地址进行替换，{your_appKey}以您当前应用的appKey进行替换。

        https://quickbi-demo.aliyun.com/m/home?appKey=xxxx&dd_orientation=auto

        PC端首页地址

        必填：配置PC版钉钉工作台Quick BI微应用的入口地址。格式：http(s)://{host}/view?appKey={your_appKey}

        其中{host}以您实际的Quick BI公网域名地址进行替换，{your_appKey}以您当前应用的appKey进行替换。

        https://quickbi-demo.aliyun.com/view?appKey=xxxxx

        管理后台地址

        非必填。

    • 登录授权地址配置：您可以在开发配置目录下的分享配置中，配置回调域名，填写的地址和路径，钉钉会用作登录时回跳URL的合法地址校验。

      如果您的Quick BI服务存在多个域名，则需要将每个域名按照以下地址方式添加。

      回调地址支持两种格式，其中${host} 以您实际的Quick BI域名进行替换，如下：

      http(s)://${host}/authx/dingtalk/identity/verify
http(s)://${host}/api/v2/organization/dingtalkInnerApp/binding

      image

Quick BI绑定钉钉应用

前提条件

您的Quick BI系统登录层已经配置了钉钉登录验证。参考：配置钉钉登录。

钉钉接口授权

在Quick BI组织管理页面，您可以按照下图步骤进入钉钉接口授权页面，将钉钉内部应用绑定到当前Quick BI组织中。

image

配置项参数说明如下：

参数名称

描述说明

名称

必填。用于备注，您可以自定义填写。

CorpId

必填。钉钉内部应用所属钉钉企业的corpId。

AgentId

必填。钉钉应用的AgentId。

Appkey

必填。钉钉应用的Appkey。

AppSecret

必填。钉钉应用的AppSecret。

钉钉接口授权成功后，支持在个人设置中通过绑定【钉钉】账号入口进行扫码绑定。

image

使用验证

添加钉钉用户

完成上述配置后，您可以在组织管理->用户成员管理中添加钉钉账号类型的用户，首次使用需要单击同步通讯录，完成后Quick BI将自动将钉钉组织中的用户同步进入系统。

image

扫码登录

添加钉钉用户完成后，在Quick BI登录页面选择钉钉登录方式，即钉钉账号类型的用户可以使用钉钉扫码进行登录。

image

微应用使用

Quick BI支持使用企业内应用在钉钉移动端进行报表访问，以钉钉账号类型添加到 Quick BI中的用户以及使用钉钉账号绑定了非钉钉账号的用户可以进入移动端直接访问报表，在工作台选择相关应用即可进入移动端查看报表：

image

您可以在个人设置中通过绑定【钉钉】账号入口进行扫码绑定具体的钉钉账号，如下图。

image

如果您当前为组织管理员身份，支持直接在用户成员管理页面对非钉钉账号类型用户进行钉钉账号的绑定操作，如下图：

image

常见问题

问题一

  • 问题描述：办公软件接入，保存钉钉配置时，报错提示：check agentId error:code:403，没有调用该接口的权限，接口权限申请参考：https://open.dingtalk.com/document/orgapp-server/add-api-permission request id: 82589EC3-B98D-7F8A-AA5F-AAB9BAB403E9。

    image..png

  • 问题原因：在保存的时候Quick BI会调用钉钉接口，校验AgentId的合法性。该报错主要由于配置的钉钉内部应用，没有相应的接口权限导致的。

  • 解决方案：

    • 登录钉钉开发者后台，选择应用开发->企业内部开发->列表页中选择对应的企业内部应用进行权限管理页面。

    • 在权限管理列表页，选择应用管理，添加管理微应用的权限（qyapi_microapp_manage）权限点，单击申请权限，添加完成即可。

      image..png

问题二

问题描述：您好，若钉钉内点击链接提示：页面加载失败！此页面因为SSL证书异常导致访问失败，请联系管理员或者服务提供商处理情况。

image.png

问题原因：是因为网络异常/证书配置异常，或证书等级过低引起的，这种报错不是钉钉做的限制，是系统内核报的错误。

请按照以下步骤操作：

1、重启网络或者重启手机。

2、可点击此处查看在线证书检测工具检测下证书链完整性/证书等级。

问题三

问题描述：Quick BI钉钉扫码绑定时报错“redirect_url的域名不在appid的安全域名内”是什么原因？image.png

问题原因：钉钉重定向链接与配置的不一致导致的。

解决方案

  1. 用未绑定钉钉的用户账号登录到Quick BI，然后在浏览器控制台中获取下settings接口中的redirect_uri信息。image.png

  2. 在钉钉开发者平台，找到对应的应用，在『分享设置』或者『安全设置』中，设置『回调域名』，按照实际域名添加。image.png

  3. 需要确保钉钉微应用中配置的URL与settings接口中返回的URL保持一致。如果不一致，需要确认是哪边配置的有问题：a: 如果是settings接口返回的不对，需要找运维同学修改后台配置来调整。b：如果是钉钉侧的配置问题，则修改钉钉的配置。

问题四

问题描述：钉钉客户端里面，点击Quick BI应用，一直在刷新，显示白页。后端日志排查，也是正常能获取到钉钉身份，显示登录正常。

问题原因：钉钉接口是https， 重定向后的地址是http，cookie无法注入。

image.png

解决方案：后台登录系统管理，看强制HTTPS是否选中。

找客户确认是否存在http访问的场景，如果不存在则打开强制https，如果存在打开会导致http的无法访问。

image.png