表單和資料 API
簡介
表單和資料API包括表單API和資料API：
API類型 | API文件 | API說明 |
表單API | 表單API | 可以取得指定表單的欄位/欄位資訊。 |
資料API | 查詢單筆資料API | 按照指定資料 ID 取得表單中的資料。 |
查詢多條資料API | 該API的返回資料，始終按照資料 ID 正序排列。 | |
新建單筆資料API | 按照指定資料 ID 取得表單中的資料。 | |
新建多條資料API | 建立多條資料API最多支援 100 條資料。 | |
修改單筆資料API | 按照指定資料 ID 修改表單中的資料。 | |
修改多條資料API | 批次更新多條資料，最多支援修改 100 條資料。 | |
刪除單筆資料API | 按照指定資料 ID 從表單中刪除資料。 |
開發前，請仔細閱讀開發指南。
欄位名
表單欄位一旦新增，會以 _widget_ 為前綴的固定欄位 ID 來表示欄位，無論修改欄位的任何資訊都不會變更欄位ID。
每個欄位都對應著一個欄位別名。使用者可以自己設定欄位別名。如果設定了別名，則在之後所有的 API 中，欄位所對應的欄位名都將以欄位別名作為實際欄位名；如果沒有設定別名，則欄位將採用欄位 ID 作為實際欄位名。
欄位別名在「擴展功能 > 資料推播 > 設定欄位別名」處進行設定。如下圖所示：
欄位與資料類型對照表
表單欄位
欄位名稱 | 欄位類型 | 資料類型 | 資料樣例 | 備註 |
單行文字 | text | String | “張三” | / |
多行文字 | textarea | String | “我愛 Jodoo” | |
流水號 | sn | String | “00001” | |
數字 | number | Number | 10 | |
日期時間 | datetime | String | “2018-01-01T10:10:10.000Z” | UTC 統一時間格式的字串 |
單選 | radiogroup | String | “一年級” | |
複選 | checkboxgroup | Array | [“選項1”,“選項2”] | |
下拉單選 | combo | String | “女” | |
下拉複選框 | combocheck | Array | [“選項1”,“選項2”] | |
圖片 | image | Array | [ { "name": "image1.png", "size": 262144, "mime": "image/png", "url": "https://files.jodoo.com/cqbrmcwhxm" }, { "name": "image2.png", "size": 262100, "mime": "image/png", "url": "https://files.jodoo.com/cqbrywmwh" } ] | 資料中包含的 url 為圖片連結，15 天內有效 |
附件 | upload | Array | [ { "name": "產品說明文件.pdf", "size": 524288, "mime": "application/pdf", "url": "https://files.jodoo.com/ojiwvfeyt" }， [ { "name": "開發架構文件.pdf", "size": 524288, "mime": "application/pdf", "url": "https://files.jodoo.com/mst" } ] | 資料中包含的 url 為附件連結，15 天內有效 |
子表單 | subform | Array | [ { "_id":"5b237548b22ab14884086cc0", "_widget_1529400746031"：...... }, { "_id":"5b237548b22ab14884086cc1", "_widget_1529400746031"：...... } ] | _id 為子表單資料 ID，由服務端生成 |
關聯資料 | linkdata | JSON | { "id": "5b237548b22ab14884086cc0", } | id 表示所關聯資料的 ID |
手寫簽名 | signature | JSON | { "name": "signature_1238921857.png", "size": 1024, "mime": "image/png", "url": "https://files.jodoo.com/ojiwsdf" } | 資料中包含的 url 為手寫簽名的圖片連結，15 天內有效 |
成員單選 | user | JSON | { "name": "Jodoo", "username": " "status": 1, "type": 0, "departments": [1, 3], } | 成員資訊中 username 表示通訊錄的成員編號（企業內唯一），name 表示使用者暱稱 status 對應的邏輯: -1 離職 0 未加入 1 已加入 |
成員多選 | usergroup | Array | [ { "name": "Jodoo", "username": "Jodoo", "status": 1, "type": 0, "departments": [1, 3], } ] | status 對應的邏輯: -1 離職 0 未加入 1 已加入 |
部門單選 | dept | JSON | { "name": "經理部", "dept_no": 1, "type": 0, "parent_no": 2, "status": 1, } | 部門資訊中 dept_no 表示通訊錄的部門編號（企業內唯一），name 表示部門名稱 |
部門多選 | deptgroup | Array | [ { "name": "經理部", "dept_no": 1, "type": 0, "parent_no": 2, "status": 1, } ] | / |
系統欄位
查詢到的資料內容中，除了表單欄位以外，還有一些系統欄位。如下表：
系統欄位 | 欄位名 | 資料類型 | 資料樣例 | 備註 |
應用Id | appId | String | “5b237267b22ab14884086c49” | 全局唯一性ID |
表單Id | entryId | String | “5b237267b22ab14884086cc9” | appId+entryId保證表單ID的唯一性 |
資料ID | _id | String | “5b237267b22ab14884086c50” | 資料全局唯一性ID |
連結參數 | ext | String | “廣州” | - |
送出時間 | createTime | String | “2018-01-01T10:10:10.000Z” | - |
送出人 | creator | JSON | { "name": "Jodoo", "username": "Jodoo", "status": 1, "type": 0, "departments": [1, 3], } | status 對應的邏輯: -1 離職 0 未加入 1 已加入 |
修改時間 | updateTime | String | “2018-01-01T10:10:10.000Z” | - |
修改人 | updater | JSON | { "name": "Jodoo", "username": "Jodoo", "status": 1, "type": 0, "departments": [1, 3], "integrate_id": "Jodoo" } | status 對應的邏輯: -1 離職 0 未加入 1 已加入 |
刪除人 | deleter | JSON | { "name": "Jodoo", "username": "Jodoon", "status": 1, "type": 0, "departments": [1, 3], "integrate_id": "Jodoo" } | status 對應的邏輯: -1 離職 0 未加入 1 已加入 |
流程狀態 *僅流程表單 | flowState | 0 | 該欄位僅流程表單支援。2表示流程手動結束；1表示流程流轉完成；0表示流程進行中。 | - |
時間格式限制
透過 API 寫入資料時，支援的時間格式如下：
支援格式 | 範例 |
ISO日期格式 |
|
毫秒時間戳 |
|
rfc 3339 yyyy-MM-dd HH:mm:ss yyyy-MM-dd |
|
不允許的輸入會轉為空值傳入。
不支援的格式範例：
null,// 無輸入, 也就是空日期
undefined,
'',
'Thu, 04 Jun 2020 13:54:52 +0800',// IETF日期格式: 不支援(原先支援)
'2021/10/10 10:10:10',// 不支援(原先支援)
["2021-03-19 23:10:00"],// 不支援(原先支援)
'Mar 31 10:10:43 UTC+0800 2012',// 不支援
'2020-06-04T14:41:54,767135400+08:00',//不支援
'~',' ',// 不支援API 操作關聯關係
功能 | create | update | delete | batch_create | batch_update |
資料工廠延時計算 | 觸發 | 觸發 | 觸發 | 觸發 | 觸發 |
資料訊息推播 | 觸發 | 觸發 | 不觸發 | 觸發 | 觸發 |
觸發彙總表 | 觸發 | 觸發 | 觸發 | 觸發 | 觸發 |
資料操作日誌 | 記錄 | 記錄 | 記錄 | 記錄 | 記錄 |
webhook 資料推播 | 不觸發 | 不觸發 | 不觸發 | 不觸發 | 不觸發 |
智慧助手 | 可觸發 | 可觸發 | 可觸發 | 不觸發 | 不觸發 |
重複值校驗 | 不校驗 | 不校驗 | - | 不校驗 | 不校驗 |
表單校驗 | 不校驗 | 不校驗 | - | 不校驗 | 不校驗 |
必填校驗 | 不校驗 | 不校驗 | - | 不校驗 | 不校驗 |
流程節點校驗 | 不校驗 | 不校驗 | - | 不校驗 | 不校驗 |
觸發流程 | 可觸發 | 不觸發 | - | 可觸發 | 不觸發 |
彙總表校驗 | 校驗 | 校驗 | 觸發 | 不校驗 | 不校驗 |
欄位聯動、公式 | 不觸發 | 不觸發 | - | 不觸發 | 不觸發 |
表單推播通知 | 觸發 | 觸發 | - | 不觸發 | 不觸發 |
注意事項
所有API路徑中的 app_id 和 entry_id 分別表示應用 ID 和該應用內的表單 ID，因此 app_id+entry_id 表示全局唯一的表單ID。