应用数据同步自动化指导文档前端

文章图片

1.概述
数据同步功能可以帮助您实现数据源之间的数据同步，适用于各系统数据整合、查询与报表分流、BI软件、实时数据仓库等多种业务场景。本文将介绍通过明道云API实现数据同步效果的具体流程，帮助您快速掌握明道云API的使用方法及数据同步管理要领。
正式开始学习之前，我们先要了解以下信息：
* 同步方案概览
介绍数据同步功能使用的API、方案概述，以及配置步骤。
* 非关系型数据类型映射关系解析
由于不同的数据库支持的数据类型不一样，数据类型无法完全对应。明道云应用本身是由零代码搭建生成的，使用MongoDB非关系型数据库来存储数据。因此，在使用API获取结果数据并写入明道云应用里时，需要进行结果解析。
目前，在明道云里有三种实现应用数据自动同步的方案：

工作表事件推送（工作流使用webhook调用对方接口实时推送推荐）
API数据抽取（动态获取工作表配置解析字段释义或界面设置字段别名）
数据库直连数据抽取（仅私有部署支持详情点击查看）
功能特性接口配置
API数据同步配置自动化方案详情请参见以下步骤：

接口基础名词释义

文章图片

基于企业授权的接口需要的Appkey，与Sign参数的传递、工作表的Appkey Sign可能不一致。所以，我们按照以下指引分别获取正确的接口和签名。
企业接口AppKey信息获取方式
进入明道云系统 - 组织管理 - 其他 - 组织密钥，获取企业授权开放接口密钥。

文章图片
工作表接口AppKey信息获取方式
参考下图，进入应用 - API开发文档，找到你需要的AppKey。

文章图片
如何获得企业接口签名？
进入明道云系统 - 组织管理 - 其他 - 组织密钥，获取企业授权开放接口密钥对信息。
获取当前 Unix 时间戳（精度为毫秒），此时间戳在调用数据接口过程中需要传递。
将密钥对当中的 AppKey、SecretKey 和此 Unix 时间戳进行按照键值对参数的方式拼接为字符串，如：AppKey=value1&SecretKey=value2&Timestamp=value3。各个参数要以&拼接。
将拼接的字符串用SHA256加密，并进行BASE64编码即可得到签名。
2.方案步骤
1）获取应用列表

简要描述：获取整个组织下的所有应用
请求URL：{Host}/v1/open/app/getByProject
请求方式：GET
参数：

文章图片

请求示例

$ {Host}/v1/open/app/getByProject?timestamp=1618837301125&pro jectId=449abe0c-e014-4836-8b60- d868c217599c&appKey=ak&sign=x&accountId=id

返回数据说明

文章图片

App 实体

文章图片

//成功 { "data": [{ "appId":"string", "name":"string", "iconUrl":"string", "color":"string" }], "error_code":1, "success": true }//失败 { "error_msg": "错误描述", "error_code": 10101, //状态码非1为失败， "success": false }

2）获取应用授权信息
简要描述：根据取应用的列表循环APPID获取应用的授权信息
请求URL：{Host}/v1/open/app/getAppAuthorize
请求方式：GET
参数：

文章图片

请求示例

$ {Host}/v1/open/app/getAppAuthorize?timestamp=1618837301125& projectId=449abe0c-e014-4836-8b60- d868c217599c&appKey=ak&sign=x&appId=id

返回数据说明

文章图片

Authorize 实体

文章图片

//成功 { "data": [{ "projectId": "string", "appId": "string", "appKey": "string", "sign": "string", "type": 1 },], "error_code":1, "success": true }//失败 { "error_msg": "错误描述", "error_code": 10101, //状态码非1为失败， "success": false }

3）获取应用信息
简要描述：获取应用的分组，工作表以及视图信息
请求URL：{Host}/v1/open/app/get
请求方式：GET
参数：

文章图片

//成功返回 { "data": { "projectId": "网络id", "appId": "应用id", "name": "应用名称", "iconUrl": "图标地址", "color": "图标颜色", "desc": "应用描述", "sections": [{ "sectionId": "应用分组id", "name": "分组名称", "items": [{ "id": "工作表id", "name": "工作表名称", "type": 0, "iconUrl": "工作表图标地址", "status": 1 }] }] }, "error_code": 1, "success": true }

4）获取工作表结构信息
简要描述：获取工作表的字段(别名)释义，程序中按别名或中文名进行报错读取
请求URL：{Host}/v2/open/worksheet/getWorksheetInfo
请求方式：POST
参数：

文章图片

//成功返回 { "data": { "worksheetId": "5dfc7f11be4eea00015b955a", "name": "汇总", "views": [ { "viewId": "视图ID", "name": "视图名称" } ], "controls": [ { //以下只列出常用字段属性信息，其他返回值可忽略 "controlId": "控件", "controlName": "控件名称", "type": 控件类型, "options": [{"key": "1","value": "选项一","index": 1,"isDeleted": false,"color": "#2196F3","score": 0.0}],//只有选项才有此字段返回 "alias":"别名", } ] }, "success": true, "error_code": 1 }

5）获取工作表数据
简要描述：分页获取工作表记录，根据上述字段别名或中文名进行本地数据库字段比对组装数据
请求URL：{Host}/v2/open/worksheet/getFilterRows
请求方式：POST
参数：

文章图片

//成功返回{ "data": { "rows": [ { "rowid": "记录ID", "ctime": "创建时间", "caid": { "accountId": "创建人id", "fullname": "创建人", "avatar": "创建人头像地址", "status": 0 }, "ownerid": { "accountId": "拥有者id", "fullname": "拥有者", "avatar": "拥有者头像地址", "status": 0 }, "utime": "最后修改时间", "控件id": "值", "控件id": "选项1", //等等...., "allowdelete": true, "关联表": "[\"3c04eb09-5e52-4dfd-8068-a2cc5a91d7c8\"]"//关联表返回是显示被关联记录的id } ], "total": 总条数, }, "success": true, "error_code": 1 }

最后，根据返回的total计算页面数，循环调用接口获取数据写入到数据库内，再定时设置下次任务触发时间。这样就实现了数据自动化同步了。
3.筛选器说明
为了满足数据查询需求，明道云对查询数据添加了筛选器对象的设计发布。它支持数据查询、关联数据条件查询等场景。

//以下是一个标准的筛选器的数据结构 [ { "controlId": "control1", "dataType": 6, "spliceType": 1, "filterType": 13, "value": "2" } ]

1）字段说明

文章图片

2）FilterTypeEnum

文章图片

3）DateRangeEnum

文章图片

4）特殊 AccountID

文章图片

【应用数据同步自动化指导文档】5）示例

//1. 时间控件：筛选类型只能为（时间是时间不是时间在范围内时间不在范围内早于晚于为空不为空）。 //1.1 时间在范围2022-02-28 00:00:00至 2022-03-03 23:59:59内： [{"controlId":"时间控件","dataType":16,"spliceType":1,"filterType":31,"dateRange":18,"dateRangeType":1,"maxValue":"2022-03-03 23:59:59","minValue":"2022-02-28 00:00:00","values":[]}] //1.2 时间是指定日期：2022-03-01 14:30:04 [{"controlId":"时间控件","dataType":16,"spliceType":1,"filterType":17,"dateRange":18,"dateRangeType":1,"value":"2022-03-01 14:30:04","values":[]}] //1.3 时间晚于本月 [{"controlId":"时间控件","dataType":16,"spliceType":1,"filterType":33,"dateRange":7,"dateRangeType":1,"values":[]}]//2. string类型控件：筛选类型只能为（包含不包含开头为结尾为是不是为空不为空） //2.1 文本包含 A字段 [{"controlId":"文本控件","dataType":2,"spliceType":1,"filterType":1,"values":["A"]}] //2.2 文本是A字段 [{"controlId":"文本控件","dataType":2,"spliceType":1,"filterType":2,"values":["A"]}]//3. 数值金额公式筛选类型只能为（= ≠ ＞＜ ≥ ≤ 在范围内不在范围内为空不为空） //3.1 在范围1-101 [{"controlId":"数值金额控件","dataType":6,"spliceType":1,"filterType":11,"maxValue":101,"minValue":1}] //3.2 数值金额公式大于1 [{"controlId":"数值金额控件","dataType":6,"spliceType":1,"filterType":13,"dateRange":0,"dateRangeType":1,"value":"1"}]//4. 单条关联表控件配置查询：筛选类型只能（关联控件是关联控件不是为空不为空） //4.1 单条关联表控件配置【是】查询 [{"controlId":"单条关联表控件","dataType":29,"spliceType":1,"filterType":24,"values":["关联表记录的id"]}]//5. 多条关联表控件配置查询筛选类型只能（包含不包含为空不为空） //5.1 多条关联表控件配置【是】查询 [{"controlId":"多条关联表控件","dataType":29,"spliceType":1,"filterType":24,"values":["关联表记录的id"]}]//6. 成员字段筛选条件只能为（是不是为空不为空） [{"controlId":"成员","dataType":26,"spliceType":1,"filterType":2,"dateRange":0,"dateRangeType":1,"values":["用户id"]}]//7. 拥有者创建者筛选条件只能为（是不是为空不为空常规用户外部用户） //7.1 拥有者是指定用户 [{"controlId":"ownerid","dataType":26,"spliceType":1,"filterType":2,"dateRange":0,"dateRangeType":1,"values":["用户id"]}]//7.2 拥有者是常规用户 [{"controlId":"ownerid","dataType":26,"spliceType":1,"filterType":41,"dateRange":0,"dateRangeType":1}]//8. 附件筛选条件只能是（为空不为空） //8.1 附件有 {"controlId": "附件控件","dataType": 14,"spliceType": 1,"filterType": 8,"value": 1} //8.2 附件无 {"controlId": "附件控件","dataType": 14,"spliceType": 1,"filterType": 7,"value": 1}

4.参考文档