外掛設計

附註：

本功能需要有程式碼能力，若不會程式碼建議使用 0 程式碼方案解決(使用市場外掛或送出需求)

簡介

Jodoo 開放平台以外掛為載體，允許使用者在多個功能場景中，透過可插拔的自訂程式碼邏輯，實現一些客製化需求。外掛可以被分發，外掛的使用者無需關注程式碼等技術細節。

建立外掛後，系統會自動為您在外掛內建立一個函數。一個外掛可以包含一個或多個函數。每個函數主要包含三個屬性: 程式碼、請求參數聲明（以下簡稱入參聲明)和返回參數聲明（以下簡稱出參聲明）。

透過請求參數聲明定義外掛使用者需要向您的函數傳遞哪些參數，透過返回參數聲明定義您將為使用者輸出哪些結果，並最終編寫程式碼來實現從參數到結果的轉換或其他自訂邏輯。

以一個翻譯外掛為例，您可以定義使用者輸入一個文字，您透過編寫程式碼，以調用第三方 API 的方式將使用者的文字翻譯為日語並將結果返回給使用者。使用者可以將該結果回填到表單的其他欄位。

1. 外掛設計頁面及各部分功能見下表：

2. 設計頁面中的相關配置項，在前台使用外掛時對應如下：

新增函數

外掛新建完成後，需要新增對應的函數。外掛中的函數分為以下兩種類型，在「外掛設計」頁面中，點擊左下角的「新增函數」，您可根據自己的需求選擇不同的函數進行建立：

附註：

1. 前端擴展與後端函數均包含：請求參數、返回參數、程式碼部分。請求參數和返回參數規則一致，程式碼部分各自支援的方法見下文【程式碼編輯】。

2. 單個自建外掛內的函數數量上限為 30 個。

參數設計

外掛有四種類型的參數可以配置，四者都非必須，按場景所需新增即可：

通用參數

通用參數是使用外掛時要配置的參數針對整個外掛的參數。通常是在啟用外掛前，對外掛進行的配置。

如，對接第三方平台需要配置的 API Key 等參數均可以在通用參數中設定。

附註：

1. 根據參數需要填寫的內容選擇欄位，通用參數僅支援基礎欄位的設定：文字、數字、日期時間、下拉單選。

2. 通用參數內的欄位數量上限為 128 個。

請求參數

請求參數是在不同位置（比如前端事件/智慧助手）中使用外掛時，外掛使用者需要提供的內容。比如：調用Jodoo 部門 API 時，需要使用者提供部門資訊。

在設計請求參數時，可以選擇不同類型的欄位。不同的欄位類型影響外掛使用者在配置外掛時的輸入方式，以及您在程式碼中取得到的值的類型。

舉例，您在入參聲明中新增了一個「部門選擇」類型的參數，那麼您的使用者在配置外掛時，將只能在界面上選擇部門類型的值，或引用表單資料中支援轉換為該類型的欄位，比如「部門單選」/「部門多選」。

附註：

1. 請求參數不同類型對於表單欄位儲存格式的支援，可以查看 【相關資訊】 瞭解。

2. 單個請求參數內欄位上限數量為 128 個。

3. 請求參數中，提示內容欄位長度上限為 4096。

返回參數

返回參數是指外掛執行完成後，返回給外掛使用者的內容。外掛使用者可以選擇需要的內容回填至表單中，或傳遞給其他外掛的其他函數。比如：調用部門 API 後，將會返回部門下成員資訊，可以將成員資訊定義成返回參數。

附註：

單個返回參數內欄位上限數量為 128 個。

2. 參數類型可選擇 any、object[]。

預設為 any，適用於請求參數與返回參數一對一的情況。

object[]，適用於請求參數與返回參數一對多的情況，返回資訊為陣列，比如透過部門查詢部門下成員時，可能有多個成員。

若設定了參數類型為 object[]，則可透過點擊列表頭前的「+ 號」按鈕，向下新增一行，作為子節點，如下所示。子節點的含義為陣列內的具體元素，比如：返回多個成員，每個成員資訊包含成員暱稱、成員編號等。

3. 返回參數在前端事件外掛中，配置效果如下所示：

表單校驗提示資訊

表單檢視下配置通用參數、請求參數和返回參數時，支援對輸入內容進行格式提示和即時校驗，以降低輸入錯誤的可能性，便於開發者校驗修改表單配置，提高開發效率。效果如下圖所示：

程式碼編輯

參數設計確定後，您就需要為函數編寫程式碼來實現其功能。

您的程式碼將被包裹於對應編程語言的一個函數之中，在程式碼中可以根據需要，透過 triggerConf 這一全局變數來取得定義的請求參數值，透過 return 關鍵字來返回最終的結果。

在編程語言選擇處（上圖 1）選擇您熟悉的編程語言，在程式碼編輯器（上圖 2）中編寫函數程式碼。在您的程式碼中，可以引用您在入參聲明中定義的參數，參數列表和值的類型可以參考右側的（上圖 3）中的提示。

後端函數-範例程式碼及說明

Python 3.6

# 可以引用一些第三方庫.
import json
import requests
# 可以透過讀取預定義的全局變數中的屬性來取得您定義的參數.
# agentConf 含義是通用參數, 其結構為一個字典(dict), key 為您在入參範本中為控件定義的 ID, 值為使用者指定的配置值.
# triggerConf 含義是請求參數, 其結構為一個字典(dict), key 為您在入參範本中為控件定義的 ID, 值為使用者指定的配置值或表單欄位的值.
api_key = str(agentConf.get('apiKey'))
dept_no = triggerConf.get('deptNo')
# 您需要對輸入參數的類型, 格式做校驗, 以增強函數邏輯的健壯性.
# 如下方對可能拿到的不同值格式進行處理，保證最終dept_no的準確性，具體值格式見本文「5.1 triggerConf (請求參數）結構」
try:
    if isinstance(dept_no, str):
        dept_no = json.loads(dept_no)
    if isinstance(dept_no, list):
        dept_no = dept_no[0] if 0 < len(dept_no) else None
    if isinstance(dept_no, dict):
        dept_no = dept_no.get('dept_no')
    if dept_no is None:
        dept_no = 1
    dept_no = int(dept_no)
except:
    raise ValueError('部門編號格式錯誤')
# 可以利用第三方庫和請求參數, 在服務端環境中調用相關API並取得結果.
url = ' https://api.jodoo.com/api/v5/corp/department/user/list'
payload = {'dept_no': dept_no}
headers = {'Authorization': 'Bearer ' + api_key}
response = requests.post(url, json=payload, headers=headers)
if 300 <= response.status_code < 500:
    # 對特定結果主動拋錯, 定義拋錯文案.
    body = response.json()
    code = body.get('code', -1)
    message = body.get('message', '未知錯誤')
    message = '參數錯誤(%s): %s' % (code, message)
    raise ValueError(message)
# 對結果進行處理, 定義返回參數值.
# 您需要返回一個dict, dict的key和返回參數ID一一對應. 若返回為陣列, 則對應出參需設定為object[]類型.
body = response.json()
users = [{'name': user.get('name'), 'username': user.get(
    'username')} for user in body.get('users', [])]
count = len(users)
return {
    "users": users,
    "count": count
}
# 可引用的全局變數, 支援的第三方庫, 請求參數資料儲存格式, 見本文「相關資訊」.

Node.js 12

// 可以引用一些第三方庫.
const _ = require('lodash');
const axios = require('axios');
// 可以透過讀取預定義的全局變數中的屬性來取得您定義的參數.
// agentConf 含義是通用參數, 其結構為一個對象(Object), key 為您在入參範本中為控件定義的 ID, 值為使用者指定的配置值.
// triggerConf 含義是請求參數, 其結構為一個對象(Object), key 為您在入參範本中為控件定義的 ID, 值為使用者指定的配置值或表單欄位的值.
const apiKey = _.chain(agentConf).get(['apiKey']).trim().value();
let deptNo = _.get(triggerConf, ['deptNo']);
// 您需要對輸入參數的類型, 格式做校驗, 以增強函數邏輯的健壯性.
// 如下方對可能拿到的不同值格式進行處理，保證最終dept_no的準確性，具體值格式見本文「5.1 triggerConf (請求參數）結構」
try {
    if (_.isString(deptNo)) deptNo = JSON.parse(deptNo);
    if (_.isArray(deptNo)) deptNo = _.first(deptNo);
    if (_.has(deptNo, ['dept_no'])) deptNo = _.get(deptNo, ['dept_no']);
    deptNo = _.toInteger(deptNo);
} catch (e) {
    throw new Error('請輸入正確的部門編號');
}
// 可以利用第三方庫和請求參數, 在服務端環境中調用相關API並取得結果.
try {
    const response = await axios({
        method: 'post',
        url: ' https://api.jodoo.com/api/v5/corp/department/user/list',
        headers: {
            Authorization: `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        },
        data: { dept_no: deptNo }
    });
    const { data } = response;
    // 對結果進行處理, 定義返回參數值.
  	// 您需要返回一個object, object的key和返回參數ID一一對應. 若返回為陣列, 則對應出參需設定為object[]類型.
    const users = _.chain(data)
    	.get(['users'])
    	.map((it) => ({ name: it.name, username: it.username }))
    	.value();
    return { users, count: users.length };
} catch (e) {
    // 對特定結果主動拋錯, 定義拋錯文案.
    const code =
        _.get(e, ['response', 'data', 'code']) || _.get(e, ['code']) || -1;
    let message =
        _.get(e, ['response', 'data', 'msg']) ||
        _.get(e, ['message']) ||
        '未知錯誤';
    message = `參數錯誤(${code}): ${message}`;
    throw new Error(message);
}
// 可引用的全局變數, 支援的第三方庫, 請求參數資料儲存格式, 見本文「相關資訊」

前端擴展-範例程式碼及說明

// closeModal
const close = () => {
    $g.utils.closeModal();
    console.log('4s後模態框關閉');
};
const reportUrl = 'https://t6ixa9nyl6.jodoo.com/f/6005518bc9f3660006e9d764';
setTimeout(() => close(), 4000);
// GET
let response2 = await fetch(reportUrl, {method: 'GET'});
console.log(await response2.text());
// openModal
// openModal：彈窗後繼續程式碼執行，執行完結束 Worker。
// await openModal：彈窗後阻塞程式碼執行，按照開發者程式碼規定執行後續動作。
await $g.utils.openModal({
    title: '如果您對外掛有任何需求，歡迎在本表單填寫',
    url: reportUrl
});
// 調用後端函數
await $g.utils.callFunction({
    name: 'func.ID',
    data: {}
})
// 主動拋錯語法和後端函數相同

參數提示的使用

程式碼編輯器右側可展開參數提示，點擊對應參數/函數，將新增對應調用語法到程式碼編輯器中。

參數校驗提示資訊

編寫請求參數/返回參數/通用參數時，若出現程式碼錯誤，對應程式碼將用紅色波浪線標註，且當滑鼠放在對應程式碼上時，會顯示詳細的配置錯誤資訊，便於開發者校驗修改程式碼內容，提升編輯體驗。效果如下所示：

語法錯誤提示資訊

在前端函數/後端擴展的 Python 程式碼檢視下，編輯器中支援在儲存程式碼時提示語法錯誤。幫助開發者快速定位具體問題，為開發者提供更為直觀、高效的開發體驗。效果如下圖所示：

效果展示

1. 後端函數外掛配置及執行效果如下所示：

2. 前端擴展外掛配置及執行效果如下所示：

相關資訊

全局變數

您在程式碼中可以直接引用全局變數 triggerConf、agentConf、triggerContext。

agentConf (通用參數）結構

agentConf 即外掛對應的通用參數。

其結構為對應編程語言的鍵值資料結構，如 Python 的 dict 或 Node.js 的 Object。在該結構中，鍵為您在入參聲明中為變數指定的 ID，值為使用者配置或引用的資料。

triggerConf (請求參數）結構

triggerConf 即外掛函數對應的請求參數。

其結構為對應編程語言的鍵值資料結構，如 Python 的 dict 或 Node.js 的 Object。在該結構中，鍵為您在入參聲明中為變數指定的 ID，值為使用者配置或引用的資料(具體結構見下文)。

Jodoo 會根據您在入參聲明中選擇的控件類型和使用者配置該參數值的來源，在運行時嘗試為您做必要的類型轉換，以使您在外掛程式碼中能夠取到格式合理的值。但這個過程不是嚴格保證的，在複雜場景中，您可能會讀取到各種預期內或預期外類型的參數，您應當在編寫程式碼時考慮這一情況，並在不能處理相關類型時拋出合理的錯誤以指引使用者調整其配置。

舉例，您正在開發一個圖像辨識類的外掛，並在該外掛的請求參數中加入了一個文字欄位用以接受使用者的圖片附件，那麼基於不同的使用者配置，您有可能得到不同的值:

您應該結合自己外掛的功能和預期服務的使用者場景，在程式碼中妥善處理上述情況，並在不計劃支援該類型時透過拋出錯誤並附加訊息向使用者提示原因。

請求參數儲值格式

1. 儲存自訂值

當使用者在外掛配置時直接儲存「自訂值」時（如上圖），請求參數中不同控件的儲值格式如下表：

2. 儲存欄位

當使用者在Jodoo表單資料場景中使用外掛時，可儲存欄位值(如上圖)，入參聲明中各個控件的儲值格式如下表：

triggerContext 結構

triggerContext 中儲存了運行環境的基本資訊，如Jodoo的開放 API 域名等。

內置庫支援列表

Node.js

Python

以下列表裏包括可調用的內置庫和第三方庫。

可用前端擴展 API

附註：

歷史 openModal、closeModal 和 callFunction 等用法仍兼容。

注意事項

外掛在運行時有相應的限制。外掛本身的超時時間為 60 s，但是不同使用場景本身也有自己的超時時間，比如前端事件的 20 s。