如何配置使用自定义渠道 - 智能商业分析 Quick BI

机器人渠道用于管理企业推送的各个渠道，方便与企业联系。为了多渠道为企业发送告警信息和审批通知，Quick BI新增推送消息的渠道，您可以根据需要配置接收消息的外部端口，测试连通后，推送消息将发送至您配置的外部端口中。本文为您介绍如何配置自定义渠道。

新建自定义渠道

登录Quick BI控制台。
在Quick BI产品首页，按照下图指引，进入新建自定义渠道页面。

在新建自定义渠道对话框，配置以下参数。

参数	描述
名称	输入自定义渠道名称。
推送地址	输入目标自定义渠道的接口地址，用于接收信息的推送。设置的接口地址必须支持`POST`请求方式。
请求添加密钥	输入目标自定义渠道的加签密钥，用于对请求进行验签。您可以手动输入密钥，或者单击自动生成密钥，自动生成密钥并填入Quick BI中。业务方需要对收到的内容进行验签处理。

单击保存并测试。
保存成功后，您可以在机器人渠道列表中，看到新创建的自定义渠道。

接收订阅时启动并配置自定义渠道

创建订阅时，您可以在配置告警方式的自定义渠道中，添加新创建的自定义渠道。

在Quick BI首页，按照下图指引，进入订阅管理页面。
在创建订阅任务时，接收方式选择自定义渠道，可以在接收渠道里看到创建的自定义渠道。
详情请参见创建订阅任务。

订阅推送到自定义渠道的消息格式如下：

{
    "schema":"1.0",
    "header":{
        "organizationId":"b5fb3d10xx",  # 所属组织ID
        "eventId":"bc679418-9e7xx",      # 事件唯一ID
        "createTime":"1705398011696",
        "eventType":"SUBSCRIBE"  # 事件类型，订阅；通过该字段，判断业务逻辑
    },
    "event":{
        "createTime":"1705397830000",
        "customParams":"{\"param\":\"this is a test\"}",   # 订阅中，自定义参数。JSON格式，key结构。
        "customReceiveGroups"："xxx",   # 自定义接收群组
        "customReceiveUsers":[   # 自定义收件人。
            {
                "nick":"张三",     # 昵称
                "accountId":"cQUPAaY81L", # Quick BI中保存的三方账号ID
                "accountType":4,   # 账号类型.
                "userId":"053da9"   # Quick BI userId
            }
        ],
        "worksInfo":{              # 报表相关信息
            "components":[        # 组件信息
                {
                    "componentId":"123", 
                    "componentName":"交叉表",
                    "componentType":4
                }
            ],
            "worksId":"0458e831-0250-486",   # 报表ID
            "worksName":"排行榜",             # 报表名称
            "worksType":"PAGE",
            "workspaceName":"李四资源包导入",    # 所属空间名称
            "workspaceId":"3e60ee7f-a99f-4231-913",   # 所属空间ID
            "worksUrl":"https://baidu.com/xxxx"       # 报表的预览地址
 
        },
        "subscribeId":"73a1d0b2420",          # 订阅ID
        "taskId": "4899407788885930938",      # 订阅任务ID
        "ownerId":"fec0741443204",            # 订阅任务owner
        "title":"自定义webhook推送渠道",        # 订阅任务标题
        "subject":"自定义",                     # 订阅任务的标题。
        "content":{         # 订阅任务文本
            "head":"<p style=\";\">自定义webhook推送渠道</p>",   
            "tail":"<p style=\";\">自定义webhook推送渠道</p>"
        },
        "snapshot":{       
            "images":[           # 截图附件
                {
                    "name":"2467699471858258259-1.jpeg",
                    "url":"https://qbi-dev.cn-shanghai.aliyuncs.com/xxxx"
                }
            ],
            "pdfs":[            # PDF附件
                {
                    "name":"2467699471858258259-1.pdf",
                    "url":"https://qbi-dev.cn-shanghai.aliyuncs.com/xxxx"
                }
            ],
            "excels":[          # excel附件
                {
                    "name":"2467699471858258259-1.xlsx",
                    "url":"https://qbi-dev.cn-shanghai.aliyuncs.com/xxxx"
                }
            ]
        }
    }
}

接收告警时启动并配置自定义渠道

监控指标时，您可以在配置告警方式的自定义渠道中，添加新创建的自定义渠道。

在Quick BI首页，按照下图指引，进入指标监控页面。
在监控告警设置对话框，当告警方式选择自定义渠道时，可以在自定义渠道中看到新创建的自定义渠道。
详情请参见配置监控告警。

在填报任务下发中配置自定义渠道

在配置数据填报的填报任务下发时选择自定义渠道。

填报任务下发推送到自定义渠道的消息格式如下

{
 "deadlineTime": "2024-07-26 20:00:00", #填报截止时间
 "taskUrl": "https://bi.aliyun.com/xxx", #填报链接
 "taskTitle": "填报任务名称", #填报任务名称
 "sendTime": "2024-07-04 19:19:20", #填报任务下发时间
 "dashboardName": "王五的填报" #报表名称
}

在对外审批电子流中配置自定义渠道

组织管理员可以外部审批渠道中，选择新创建的自定义渠道。

在配置管理页面，按照下图指引，新建自定义渠道。
在协同配置页面，按照下图指引，启用自定义审批渠道。
此时，用户申请Quick BI的资源权限时，自定义渠道也能收到申请通知。

Quick BI审批，推送到自定义渠道的消息格式如下：

{
    "authPointsValue":3,    # 权限点
    "resourceId":"b8b5392b-bb44-4bd8-e9642787e8d",   # 申请权限资源ID
    "resourceName":"首屏20个组件（移动端8个首屏）",     # 报表资源名称
    "approverId":"e52b777a1dde4bfb94f91e18128bcfb0",  # 审批人UID
    "roleId":0,
    "applyReason":"123123",              # 申请理由
    "extInfo": [                         # 扩展信息，当资源类型为填报入库时，此处将会显示用户提交的表单中每个控件的名称、类型以及填报信息。
      {
          "data": {                     # 控件的填报数据信息
            "63912418-e311-4573-84be-1f732ffd9f35": 20,   # 控件ID及其具体填报值
            "f9a46753-98a1-4709-9327-949c6a03af08": "测试",
            "ffe8327a-9de8-4699-a23a-097088a22d2e": "测试1"
          },
          "dataId": null,               # 数据记录ID
          "dataWithComponent": {        # 控件的具体信息
            "63912418-e311-4573-84be-1f732ffd9f35": {   # 控件ID
            "componentType": "number",  # 控件类型
            "data": 20,                 # 用户在当前控件中填报的具体值
            "label": "年龄"              # 控件名称
          },
            "f9a46753-98a1-4709-9327-949c6a03af08": {
            "componentType": "text",
            "data": "测试",
            "label": "备注"
          },
            "ffe8327a-9de8-4699-a23a-097088a22d2e": {
            "componentType": "text",
            "data": "测试1",
            "label": "姓名"
          }
        }
      }
    ],
    "resources": [                       # 菜单信息,该字段仅数据门户有    
      {
          "resourceId": "a8d78c04-df99-42c3-a0a2-dbe7350b077c",  # 菜单id
          "resourceName": "三级菜单",     # 菜单名称
          "resourceType": "0"            # 菜单类型
      }
    ],
    "applicantName":"张先生",                 # 申请人昵称
    "gmtCreate":1705399339000,               # 创建时间
    "approverName":"王女生",                  # 审批人昵称
    "expireDate":1708077734000,              # 权限有效期限
    "workspaceName":"QuickBI测评空间",        # 空间名称
    "applicantId":"e9a40c524ef8471faefbd",   # 申请人UID
    "applicationId":"b31c8cf5-aa31-42f7-927a-da3cb2feefd4",  # 审批ID
    "resourceType":"dashboard"               # 资源类型
}

备注一：菜单信息，字段resources，只有在数据门户审批才存在，展示菜单信息，

只支持以下几种类型，resources 中的 resourceType：

0：仪表板
2：电子表格
5：数据填报
6：自助取数
7：即席分析
8：数据大屏

备注二：资源类型对照（可以对大小写进行兼容）

dataProduct：数据门户
portal_menu：数据门户菜单
dashboard：仪表板
screen：数据大屏
report：电子表格
ANALYSIS：即席分析
dashboardOfflineQuery：自助取数
dataForm：数据填报
cube：数据集
datasource：数据源
dataFormInsertData：填报入库

备注三：有关各个资源的 authPointsValue 权限点说明如下：

资源类型	authPointsValue 权限点说明
数据填报	1：提交数据 9：管理自身数据 10：管理全部数据 11：编辑
数据集、数据源、数据准备	1：使用 11：编辑
数据大屏、电子表格、仪表板、自助取数	1：仅查看 2：导出 3：查看及导出 11：编辑
数据门户	数据门户权限 11：编辑菜单内容权限同上重要特殊的：数据填报的管理自身数据为3

附：外部系统接收与验签方式

实际应用时，Quick BI以POST的方式进行内容推送，并在请求中添加如下内容，用户系统接收到推送的内容后，可根据实际需要对比sign的值进行验签处理。

请求头：
X-TaskId，即任务ID，用户可以使用该ID唯一确认1次任务请求，可以进行重复性校验（即进行重复过滤）或者在出现异常时提供给Quick BI业务人员进行问题定位。
请求参数：
- timestamp：时间戳
- nonce：随机串
- sign：验签信息

上述请求参数，主要出于安全考虑，当用户系统接收时可以进行防重放和防篡改的校验。具体签名的生成方式如下：

sign = SHA256.digest(timestamp + nonce + token)

说明

其中，token的值为创建时生成的请求添加密钥，业务接收方需要校验生成的sign是否与预期一致。
由于webhook发送有30s的超时时间限制，建议webhook接口在接收到消息之后，采用异步的方式处理，避免消息重试或者被设置发送失败。此外，Quick BI对于webhook接口的返回结果内容没有特别要求，只需要返回200的HTTP状态码和任意非空文本，表示接收到即可。