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

1.概述

数据同步功能可以帮助您实现数据源之间的数据同步,适用于各系统数据整合、查询与报表分流、BI软件、实时数据仓库等多种业务场景。本文将介绍通过明道云API实现数据同步效果的具体流程,帮助您快速掌握明道云API的使用方法及数据同步管理要领。

正式开始学习之前,我们先要了解以下信息:

介绍数据同步功能使用的API、方案概述,以及配置步骤。

由于不同的数据库支持的数据类型不一样,数据类型无法完全对应。明道云应用本身是由零代码搭建生成的,使用MongoDB非关系型数据库来存储数据。因此,在使用API获取结果数据并写入明道云应用里时,需要进行结果解析。

目前,在明道云里有三种实现应用数据自动同步的方案:

  1. 工作表事件推送(工作流使用webhook调用对方接口实时推送 推荐)
  2. API数据抽取(动态获取工作表配置解析字段释义或界面设置字段别名)
  3. 数据库直连数据抽取(仅私有部署支持 详情点击查看
  • 功能特性接口配置

API数据同步配置自动化方案详情请参见以下步骤:

    • 接口基础名词释义

基于企业授权的接口需要的Appkey,与Sign参数的传递、工作表的Appkey Sign可能不一致。所以,我们按照以下指引分别获取正确的接口和签名。

    • 企业接口AppKey信息获取方式

进入明道云系统 – 组织管理 – 其他 – 组织密钥,获取企业授权开放接口密钥。

    • 工作表接口AppKey信息获取方式

参考下图,进入应用 – API开发文档,找到你需要的AppKey。

    • 如何获得企业接口签名?
  1. 进入明道云系统 – 组织管理 – 其他 – 组织密钥,获取企业授权开放接口密钥对信息。
  2. 获取当前 Unix 时间戳(精度为毫秒),此时间戳在调用数据接口过程中需要传递。
  3. 将密钥对当中的 AppKey、SecretKey 和此 Unix 时间戳进行按照键值对参数的方式拼接为字符串,如:AppKey=value1&SecretKey=value2&Timestamp=value3。各个参数要以&拼接。
  4. 将拼接的字符串用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.参考文档

关于明道云

明道云(www.mingdao.com)成立于2013年,位于上海,创始人为互联网知名人士任向晖先生。明道云是一个APaaS平台,帮助企业快速搭建个性化业务应用。用户不需要代码开发就能够搭建出用户体验上佳的销售、运营、人事、采购等核心业务应用,打通企业内部数据,也能够通过API和Webhook和其他系统对接。

明道云的自动化工作流还可以实现审批、填写等控制流程和业务自动化。如果用户企业使用钉钉或企业微信,也可以将明道云搭建的应用直接对接到工作台上。

明道云可以帮助企业大大节省软件费用、降低定制开发的成本和时间,拥有一个极度灵活和易用的数据中台,并提高整体数字化和智能化水平。目前已有上百万用户使用,付费企业超过4000家,典型客户包括:中铁三局、佛山地铁、普华永道、艾瑞咨询、迪卡侬、北京大学、四川航空、上海静安区街道、艾默生电子、西门子、杭州建筑设计研究院、七天四季酒店、希尔顿、凯宾斯基酒店、可口可乐等知名机构。了解更多