如何配置使用自訂渠道 - 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狀態代碼和任意非空文本，表示接收到即可。