文档

自定义渠道

更新时间:

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

新建自定义渠道

  1. 登录Quick BI控制台

  2. 在Quick BI产品首页,按照下图指引,进入新建自定义渠道页面。

    image.png

  3. 新建自定义渠道对话框,配置以下参数。

    image.png

    参数

    描述

    名称

    输入自定义渠道名称。

    推送地址

    输入目标自定义渠道的接口地址,用于接收信息的推送。

    设置的接口地址必须支持POST请求方式。

    请求添加密钥

    输入目标自定义渠道的加签密钥,用于对请求进行验签。

    您可以手动输入密钥,或者单击自动生成密钥,自动生成密钥并填入Quick BI中。

    业务方需要对收到的内容进行验签处理,详细请参见附:外部系统接收与验签方式

  4. 单击保存并测试

    保存成功后,您可以在机器人渠道列表中,看到新创建的自定义渠道。image.png

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

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

  1. 在Quick BI首页,按照下图指引,进入指标监控页面。

    image

  2. 在创建订阅任务时,接收方式选择自定义渠道,可以在接收渠道里看到创建的自定义渠道。

    image

    详情请参见创建订阅任务

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

    {
        "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结构。
            "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
            "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"
                    }
                ]
            }
        }
    }

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

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

  1. 在Quick BI首页,按照下图指引,进入指标监控页面。

    image.png

  2. 监控告警设置对话框,当告警方式选择自定义渠道时,可以在自定义渠道中看到新创建的自定义渠道。

    image.png详情请参见配置监控告警

  3. 监控告警推送到自定义渠道的消息格式如下:

    {
        "reason":"price(求和)大于0",   # 告警原因
        "metricName":"线图-mysql",    # 维度名称
        "checkTime":1705398660000,   # 触发时间
        "value2":"0",                # 规则阈值
        "value1":"707033.66",        # 监控值
        "dimValueMap":{            # 维度组合值
    
        },
        "monitorName":"线图-mysql",   # 告警名称
        "reportUrl":"https://quickbi.aliyun-inc.com/",  # 报表的链接地址
        "dashboardName":"监控告警-全用例2"          # 报表名称
    }

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

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

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

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

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

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

  1. 在配置管理页面,按照下图指引,新建自定义渠道。image.png

  2. 在协同配置页面,按照下图指引,启用自定义审批渠道。

    image.png

    此时,用户申请Quick BI的资源权限时,自定义渠道也能收到申请通知。

  3. Quick BI审批,推送到自定义渠道的消息格式如下:

    
    
    {
        "authPointsValue":3,    # 权限点。1:查看 2:导出  3:查看+ 导出  4:编辑(写) 
        "resourceId":"b8b5392b-bb44-4bd8-8f63-0e9642787e8d",   # 申请权限资源ID
        "resourceName":"首屏20个组件(移动端8个首屏)",     # 报表资源名称
        "approverId":"e52b777a1dde4bfb94f91e18128bcfb0",  # 审批人UID
        "roleId":0,
        "applyReason":"123123",        # 申请理由
        "applicantName":"Gartner_demo",  # 申请人昵称
        "gmtCreate":1705399339000,
        "approverName":"批量导入_225706",  # 审批人昵称
        "expireDate":1708077734000,       # 权限有效期限
        "workspaceName":"性能报告测评空间",  # 空间名称
        "applicantId":"e9a40c524ef8471faefbd",   # 申请人UID
        "applicationId":"b31c8cf5-aa31-42f7-927a-da3cb2feefd4",  # 审批ID
        "resourceType":"dashboard"   # 资源类型
    }

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

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

  • 请求头

    X-TaskId,即任务ID,用户可以使用该ID唯一确认1次任务请求,可以进行重复性校验(即进行重复过滤)或者在出现异常时提供给Quick BI业务人员进行问题定位。

  • 请求参数

    • timestamp:时间戳

    • nonce:随机串

    • sign:验签信息

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

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

其中,token的值为创建时生成的请求添加密钥,业务接收方需要校验生成的sign是否与预期一致。