### 钉钉与金蝶云星空的数据集成实战案例：transfer-新转账单（资金调拨）V4.0
在企业日常运营中，数据的快速、准确传输和处理是业务流程优化的核心要素。本次分享的是一个实际应用中的系统对接集成案例，通过使用轻易云数据集成平台，实现了从钉钉到金蝶云星空的数据无缝对接。具体方案名为：**transfer-新转账单（资金调拨）V4.0**。
首先，我们需要解决的是如何从钉钉获取到相关的业务数据。通过调用`v1.0/yida/processes/instances` API接口，我们能够定时可靠地抓取到所需的数据。这一步骤至关重要，以确保我们后续的数据不会产生遗漏或重复，从而保证每笔交易记录都能准确传递至金蝶云星空。
为了适配特定业务需求和复杂的数据结构，本方案支持自定义数据转换逻辑。在这过程中，我们利用轻易云提供的可视化数据流设计工具，有效简化了整个转换过程，使得各种操作更加直观且便于管理。同时，处理分页和限流问题也是不可忽视的一环。通过设置合理的参数并结合重试机制，成功应对API调用限制带来的挑战。
写入到目标系统——金蝶云星空，则依赖于其`batchSave` API接口。这一过程中，必须考虑批量数据高吞吐量写入的问题，以确保大量数据能在短时间内被有效接收并存储。另外，为了进一步提升稳定性，本方案结合了集中监控及告警系统，对整个任务状态做实时跟踪，一旦发现异常立即给予反馈，并自动触发错误重试机制来防止因突发状况导致的数据丢失或延迟问题。
综上所述，这个案例完美展示了如何借助现代平台实现跨系统之间高效、可靠的数据集成。以下将详细介绍具体技术实现细节及配置步骤。
### 调用钉钉接口获取并加工数据的技术案例
在轻易云数据集成平台中，调用源系统接口是数据处理生命周期的第一步。本文将详细探讨如何通过调用钉钉接口`v1.0/yida/processes/instances`来获取并加工数据，以实现高效的数据集成。
#### API 接口配置
首先，我们需要配置API接口的元数据。根据提供的metadata，我们可以看到以下关键字段：
- `api`: "v1.0/yida/processes/instances"
- `method`: "POST"
- `number`: "title"
- `id`: "processInstanceId"
- `idCheck`: true
这些字段定义了我们将要调用的API接口及其请求方法。接下来，我们需要配置请求参数。
#### 请求参数配置
请求参数是API调用成功与否的关键。以下是metadata中定义的请求参数：
```json
[
{"field":"pageNumber","label":"分页页码","type":"string","describe":"分页页码","value":"{PAGINATION_START_PAGE}"},
{"field":"pageSize","label":"分页大小","type":"string","describe":"分页大小","value":"{PAGINATION_PAGE_SIZE}"},
{"field":"appType","label":"应用ID","type":"string","describe":"应用ID","value":"APP_WTSCMZ1WOOHGIM5N28BQ"},
{"field":"systemToken","label":"应用秘钥","type":"string","describe":"应用秘钥","value":"IS866HB1DXJ8ODN3EXSVD750RBTK2X72R8MELL4"},
{"field":"userId","label":"用户的userid","type":"string","describe":"用户的userid","value":"16000443318138909"},
{"field":"language","label":"语言","type":"string","describe":"语言，取值：zh_CN：中文（默认值）en_US：英文"},
{"field":"formUuid","label":"表单ID","type":"string","describe":"表单ID","value":"FORM-KW766OD1931ALBVJBHUHLD6KFJ3G3OELLVLGL0"},
{"field":"searchFieldJson","label":"条件","type": "object", "children":[{"field": "selectField_lglvrpmg", "label": "类型", "type": "string", "value": "跨组织转账"}]},
{"field": "originatorId", "label": "根据流程发起人工号查询", "type": "string", "describe": "根据流程发起人工号查询"},
{"field": "createFromTimeGMT", "label": "创建时间起始值", "type": "string", "describe": "创建时间起始值",
"value": "_function DATE_FORMAT(DATE_ADD(NOW(),INTERVAL - 25 DAY),'%Y-%m-%d 00:00:00')"},
{"field": "createToTimeGMT", "label": "创建时间终止值",
"type": "string",
"describe":
...
]
```
这些参数包括分页信息、应用ID、用户ID、表单ID、查询条件等。特别注意的是，`createFromTimeGMT`和`createToTimeGMT`字段使用了函数和模板变量来动态生成时间范围。
#### 数据请求与清洗
在发送请求之前，我们需要确保所有必需字段都已正确填充，并且符合API要求。例如，分页信息可以通过系统变量动态设置：
```json
{
...
{"field": "pageNumber", ... , value: "{PAGINATION_START_PAGE}"},
{"field": "pageSize", ... , value: "{PAGINATION_PAGE_SIZE}"}
}
```
这些变量可以在实际调用时由系统自动替换为具体数值，从而实现自动化分页处理。
#### 数据转换与写入
一旦成功获取到数据，我们需要对数据进行清洗和转换，以便后续写入目标系统。在这个过程中，可以利用轻易云平台提供的数据处理工具，例如：
- 数据格式转换：将JSON格式的数据转换为目标系统所需的格式。
- 字段映射：将源系统字段映射到目标系统字段。
- 数据过滤：根据业务需求过滤掉不必要的数据。
例如，将获取到的实例状态为"COMPLETED"且审批结果为"agree"的数据进行筛选和转换：
```json
{
...
{
field: 'instanceStatus',
label: '实例状态',
type: 'string',
describe: '实例状态',
value: 'COMPLETED'
},
{
field: 'approvedResult',
label: '流程审批结果',
type: 'string',
describe: '流程审批结果',
value: 'agree'
}
}
```
通过以上步骤，我们可以确保从钉钉接口获取的数据经过清洗和转换后，能够无缝对接到目标系统，实现高效的数据集成。
#### 实际案例操作
假设我们需要从钉钉获取过去25天内所有跨组织转账且审批通过的流程实例，具体操作步骤如下：
1. 配置API元数据及请求参数。
2. 动态生成时间范围并填充其他必要字段。
3. 调用API获取数据。
4. 对返回的数据进行清洗和转换。
5. 将处理后的数据写入目标系统。
通过上述步骤，可以实现从钉钉接口高效、安全地获取并加工数据，为后续的数据处理和分析打下坚实基础。
### 使用轻易云数据集成平台将数据转换并写入金蝶云星空API接口
在轻易云数据集成平台中，完成数据生命周期的第二步，即将已经集成的源平台数据进行ETL转换，并转为目标平台金蝶云星空API接口所能够接收的格式，是一个关键步骤。以下是详细的技术实现过程。
#### API接口配置
首先，我们需要配置金蝶云星空的API接口。根据提供的元数据配置，API接口为`batchSave`，使用POST方法。以下是具体的配置细节：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 1,
"method": "batchArraySave"
},
"request": [
{"field":"FBillNo","label":"单据编号","type":"string","value":"{serialNumberField_lgov9d3b}(ZJDB)"},
{"field":"FBillTypeID","label":"类型","type":"string","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"ZJDBDLX01_SYS"},
{"field":"FDate","label":"日期","type":"string","value":"_function FROM_UNIXTIME( ( {dateField_lglvrpp4} \/ 1000 ) ,'%Y-%m-%d' )"},
{"field":"FFundsOrgID","label":"资金组织","type":"string","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{textField_lglvrpmt}"},
{"field":"FPayOrgID","label":"转出组织","type":"string","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{textField_lglvrpmt}"},
{"field":"FBankID","label":"转出银行","type":"string","parser":{"name":"ConvertObjectParser","params":"FNumber"}},
{"field":"FBankActID","label":"转出银行账号","type":"string","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{selectField_lglvrpot}"},
{"field":"FCURRENCYID","label":"币别","type":"string","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"PRE001"},
{"field":"FSettleTypeID","label":"结算方式","type": "string", "parser": {"name": "ConvertObjectParser", "params": "FNumber"}, "value": "JSFS04_SYS"},
{"field": "FMAINBOOKID", "label": "帐薄", "type": "string", "parser": {"name": "ConvertObjectParser", "params": "FNumber"}, "value": "PRE001"},
{"field": "FEXCHANGETYPE", "label": "汇率类型", "type": "string", "parser": {"name": "ConvertObjectParser", "params": "FNumber"}, "value": "HLTX01_SYS"},
{
“field”: “FFUNDSTRANSFENTRY”,
“label”: “单据体”,
“type”: “array”,
“children”: [
{
“field”: “FReceiveOrgId”,
“label”: “收款组织”,
“type”: “string”,
“parser”: {“name”: “ConvertObjectParser”, “params”: “FNumber”},
“value”: "{textField_lglvrpmv}",
“parent”: “FFUNDSTRANSFENTRY”
},
{
“field”: “FEntryBankID”,
“label”: “银行”,
“type”: “string”,
“parser”: {“name”: “ConvertObjectParser”, “params”: “FNumber”},
”parent“: ”FFUNDSTRANSFENTRY“
},
{
”field“: ”FENTRYBANKActID“,
”label“: ”银行账号“,
”type“: ”string“,
”parser“: {”name“: ”ConvertObjectParser“, ”params“: ”FNumber“},
”value“: "{selectField_lglvrpoz}",
”parent“: ”FFUNDSTRANSFENTRY“
},
{
”field“: ”FAmount“,
”label“: ”金额“,
”type“: ”string“,
”value“: "{numberField_lglvrpn8}",
”parent“: ”FFUNDSTRANSFENTRY“
},
{
”field“: ”FAMOUNT_LC“,
”label“: ”本位币“,
”type“: ”string“,
parent:“FFUNDSTRANSFENTRY”,
parser:{name:“ConvertObjectParser”, params:“FNumber”}
},
{
parent:“FFUNDSTRANSFENTRY”,
label:“备注”,
field:“FCOMMENT”,
type:“string”,
value:"{textareaField_lglvrpoa}"
}
],
parser:{ name:“ConvertObjectParser”, params:“ FNumber"}
},
{ label:"摘要", field:" FDescription ", type:" string ", value:" {textareaField_lglvrpoa}"},
{ label:"往来类型 ", field:" F_QKZI_Assistant1 ", type:" string ", value:" {selectField_lglvrpna_id}", parser:{ name:" ConvertObjectParser ", params:" FNumber"}},
{ label:"借出部门 ", field:" F_QKZI_Base ", type:" string ", value:" {textField_l3wlou1j}", parser:{ name:" ConvertObjectParser ", params:" FNumber"}}],
otherRequest:[{ field:" FormId ", label:"业务对象表单Id", type:" string ", describe :"必须填写金蝶的表单 ID如:PUR_PurchaseOrder", value :"SC_FundsTransf"},{ field :" Operation ", label :"执行的操作 ", type :" string ", value :" BatchSave"},{ field :" IsAutoSubmitAndAudit ", label :"提交并审核 ", type :" bool ", value :" false"},{ field :" IsVerifyBaseDataField ", label :"验证基础资料 ", type :" bool ", describe :"是否验证所有的基础资料有效性，布尔类，默认false（非必录）"， value :false}]
}
```
#### 数据字段解析与转换
在上述配置中，每个字段都需要进行相应的数据解析和转换，以确保符合金蝶云星空API接口的要求。例如：
- `FBillNo`（单据编号）：通过 `{serialNumberField_lgov9d3b}(ZJDB)` 获取。
- `FBillTypeID`（类型）：固定值 `ZJDBDLX01_SYS`，并通过 `ConvertObjectParser` 转换。
- `FCURRENCYID`（币别）：固定值 `PRE001`，并通过 `ConvertObjectParser` 转换。
- `FFUNDSTRANSFENTRY`（单据体）：这是一个数组类型，其中包含多个子字段，如 `FAmount`（金额）、`FCOMMENT`（备注）等。
每个字段都需要根据其类型和解析器进行相应处理。例如，对于日期字段 `FDate`，需要将UNIX时间戳转换为标准日期格式：
```json
{
...
{"field": "FDate",
"label": "",
"type ": "",
"value ":"_function FROM_UNIXTIME( ( {dateField_lglvrpp4} / 1000 ) , '%Y-%m-%d' )"
}
}
```
#### 数据写入目标平台
在完成所有字段的数据解析和转换后，我们可以将处理后的数据通过POST请求写入到金蝶云星空平台。以下是一个示例请求体：
```json
{
...
{
"FormId ": "",
"Operation ":" BatchSave ",
"IsAutoSubmitAndAudit ":false,
"IsVerifyBaseDataField ":false,
"Model ":{
...
"FBillNo ":" ZJDB20230901 ",
"FBillTypeID ":" ZJDBDLX01_SYS ",
" FDate ":"2023-09-01",
...
" FFUNDSTRANSFERTRY":[
{
...
" FReceiveOrgId ":" ORG001 ",
...
}
]
}
}
```
#### 实际应用案例
假设我们有一组源数据，需要将其转换并写入到金蝶云星空中。以下是一个具体的应用案例：
源数据：
```json
{
...
serial_number_field : '123456',
date_field : '1693555200000',
text_field : 'ORG001',
select_field : 'BANK001',
number_field : '1000.00',
}
```
根据元数据配置和解析规则，我们可以生成如下目标数据：
```json
{
...
FBillNo:'123456(ZJDB)',
FBillTypeID:'ZJDBDLX01_SYS',
FDate:'2023-09-01',
...
FFUNDSTRANSFERTRY:[
...
FReceiveOrgId:'ORG001',
...
]
}
```
最终，通过POST请求将上述目标数据写入到金蝶云星空中。
以上即为使用轻易云数据集成平台，将已经集成的源平台数据进行ETL转换，并转为目标平台金蝶云星空API接口所能够接收格式，并最终写入目标平台的技术实现过程。
