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}