### 金蝶云星空数据集成到钉钉的实践分享：金蝶付款申请单 -> 钉钉供应商月结付款①
在本次技术案例中，我们将深入探讨如何通过轻易云数据集成平台实现金蝶云星空与钉钉之间的数据对接，具体方案为“金蝶付款申请单->钉钉供应商月结付款①”。这其中涉及了多个关键技术点，包括但不限于API调用、分页处理、数据格式转换及错误重试机制。
首先，为确保集成中金蝶云星空的所有付款申请单都能够准确无误地传输到钉钉中，我们利用了executeBillQuery接口。该接口可以高效地抓取金蝶云星空系统中的各类业务数据，并提供可靠的分页功能以应对大规模数据量。
针对大量资金申请单在短时间内需要写入到钉钉的需求，topapi/processinstance/create成为我们的选择。这一API不仅支持批量导入，还具有较高的数据吞吐能力。然而，在实际操作过程中还需特别注意限流问题，这意味着我们不能一次提交过多请求，否则将触发频率限制。因此，需要在程序逻辑上进行适度控制，例如实现自定义延时策略来分散请求压力。
除此之外，两者之间的数据格式差异也是一个不可忽视的问题。虽然两边均使用标准JSON作为交换格式，但字段命名规则及层级结构并不完全一致。为了处理这些差异，我们构建了一系列映射规则，将从金蝶云获取的数据重新封装，使其符合topapi/processinstance/create接口所需的输入要求。
至于异常处理部分，当某些情况下由于网络波动或系统响应超时导致部分数据推送失败时，我们设计了一套错误重试机制，通过捕获异常信息并记录日志，从而随时监控和调试可能存在的问题。这不仅提高了系统稳定性，也提供了实时反应能力，使整个流程透明可视化，大幅提升整体联动效率。
以上内容只是全面项目实施中的冰山一角，下文将继续详细阐述每个环节的具体配置和实施方法，以帮助大家更好地理解这一跨平台整合方案是如何运作与实现的。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成过程中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口来获取付款申请单的数据，并进行初步加工。
#### 接口调用配置
首先，我们需要配置元数据以便正确调用金蝶云星空的`executeBillQuery`接口。以下是元数据配置的关键部分：
```json
{
"api": "executeBillQuery",
"method": "POST",
"number": "FBillNo",
"id": "FBillNo",
"pagination": {
"pageSize": 500
},
"idCheck": true,
"condition": [
[{"field":"FPAYORGID","logic":"eq","value":"2.01"}],
[{"field":"FPAYORGID","logic":"eq","value":"2.02"}],
// ...其他条件
],
"request": [
{"field":"FID","label":"实体主键","type":"string","value":"FID"},
{"field":"FBillNo","label":"单据编号","type":"string","value":"FBillNo"},
{"field":"FDOCUMENTSTATUS","label":"单据状态","type":"string","value":"FDOCUMENTSTATUS"},
// ...其他字段
],
"otherRequest": [
{"field":"Limit","label":"最大行数","type":"string","describe":"金蝶的查询分页参数","value":"{PAGINATION_PAGE_SIZE}"},
{"field":"StartRow","label":"开始行索引","type":"string","describe":"金蝶的查询分页参数","value":"{PAGINATION_START_ROW}"},
{"field":"FilterString","label":"过滤条件","type":"string","describe":"","value":""},
{"field":"FieldKeys","label":"需查询的字段key集合","type":"array"},
{"field":"FormId","label":"业务对象表单Id","type":"string"}
]
}
```
#### 数据请求与清洗
在调用接口时，我们需要特别注意请求参数的设置和数据清洗过程。以下是具体步骤：
1. **设置请求参数**：
- `FormId`: 设置为`CN_PAYAPPLY`，表示我们要查询的是付款申请单。
- `FieldKeys`: 包含所有需要查询的字段，如`FID`, `FBillNo`, `FDOCUMENTSTATUS`等。
- `FilterString`: 用于过滤条件，这里可以根据业务需求设置，例如按日期过滤。
2. **分页处理**：
- `Limit`: 设置每次请求返回的最大行数，这里设置为500。
- `StartRow`: 设置开始行索引，用于分页。
3. **发送请求**：
使用POST方法发送请求到金蝶云星空接口，并获取返回的数据。
```json
{
"FormId": "CN_PAYAPPLY",
"FieldKeys": ["FID", "FBillNo", "FDOCUMENTSTATUS", ...],
"FilterString": "",
"Limit": 500,
"StartRow": 0
}
```
#### 数据转换与写入
获取到原始数据后，需要对其进行转换和清洗，以便后续处理和写入目标系统。以下是一些常见的数据处理操作：
1. **字段映射**：
将金蝶返回的数据字段映射到目标系统所需的字段。例如，将`FID`映射为目标系统中的主键ID。
2. **数据类型转换**：
根据目标系统要求，将数据类型进行转换。例如，将日期字符串转换为标准日期格式。
3. **数据过滤与校验**：
对返回的数据进行过滤和校验，确保数据完整性和准确性。例如，过滤掉状态为“作废”的记录。
4. **批量写入**：
将处理后的数据批量写入目标系统，如钉钉供应商月结付款模块。
```python
def process_data(raw_data):
processed_data = []
for record in raw_data:
processed_record = {
'主键ID': record['FID'],
'单据编号': record['FBillNo'],
'单据状态': record['FDOCUMENTSTATUS'],
# ...其他字段映射
}
processed_data.append(processed_record)
return processed_data
# 示例：将处理后的数据写入目标系统
write_to_target_system(processed_data)
```
通过上述步骤，我们实现了从金蝶云星空获取付款申请单数据，并进行了初步加工，为后续的数据集成打下了坚实基础。这一过程不仅提高了数据处理效率，也确保了数据的一致性和准确性。
### 使用轻易云数据集成平台将金蝶付款申请单转换为钉钉API格式并写入
在数据集成生命周期的第二步中，我们需要将已经集成的源平台数据进行ETL转换，转为目标平台钉钉API接口所能够接收的格式，并最终写入目标平台。以下是具体的技术实现过程。
#### 钉钉API接口配置
根据提供的元数据配置，我们需要调用钉钉API `topapi/processinstance/create`，使用POST方法提交数据。以下是该接口的详细配置：
```json
{
"api": "topapi/processinstance/create",
"method": "POST",
"idCheck": true,
"request": [
{
"field": "process_code",
"label": "审批流的唯一码",
"type": "string",
"describe": "process_code在审批流程编辑页面的URL网址中获取。",
"value": "PROC-C1D46DC7-ACB2-4B63-8C48-F644942F63E5"
},
{
"field": "originator_user_id",
"label": "发起人",
"type": "string",
"describe": "审批实例发起人的userid。",
"value": "_findCollection find user_id from 0aa3e172-35e6-310b-8b94-3fbdec29583d where name={F_VAOJ_FQR}"
},
{
"field": "dept_id",
"label": "发起人所在部门",
"type": "string",
"describe": "发起人所在的部门，如果发起人属于根部门，传-1。",
"value": "_findCollection find dept_order_list.0.dept_id from 0aa3e172-35e6-310b-8b94-3fbdec29583d where name={F_VAOJ_FQR}"
},
{
"field": "form_component_values",
"label": "审批流表单参数",
"type": "object",
"children": [
{"field":"单据编号","type":"string","value":"{FBillNo}","parent":"form_component_values"},
{"field":"货款所属项目","type":"string","value":"{FSETTLEORGID}","parent":"form_component_values","mapping":"6295fa8ab3945438dd215d24","mappingDirection":"reverse"},
{"field":"供应商名称","type":"string","value":"{FCONTACTUNIT}","parent":"form_component_values"},
{"field":"付款时间","type":"string","value":"{{FCREATEDATE|date}}","parent":"form_component_values"},
{"field":"货款属性","type":"string","value":"_function case '{F_VAOJ_HKSX}' when 'CP' then '成品' else '辅料' end","parent":"form_component_values"},
{"field":"备注信息","type":"string","value":"备注为：{F_VAOJ_Remarks}","parent":"form_component_values"},
{"field":"付款金额（元）","type":"string","value":"{FAPPLYAMOUNTFOR_H}","parent":"form_component_values"},
{"field":"收款人（公司名称）","type":"string","value":"{FEACHCCOUNTNAME}","parent":"form_component_values"},
{"field":"收款人帐号","type":"string","value":"{FEACHBANKACCOUNT}","parent":"form_component_values"}
]
}
]
}
```
#### 数据转换与写入
1. **字段映射与转换**
首先，我们需要将金蝶付款申请单中的字段映射到钉钉API所需的字段。例如：
- `FBillNo` 映射到 `单据编号`
- `FSETTLEORGID` 映射到 `货款所属项目`
- `FCONTACTUNIT` 映射到 `供应商名称`
- `FCREATEDATE` 转换为日期格式后映射到 `付款时间`
- 根据 `F_VAOJ_HKSX` 的值进行条件判断并映射到 `货款属性`
- `F_VAOJ_Remarks` 映射到 `备注信息`
- `FAPPLYAMOUNTFOR_H` 映射到 `付款金额（元）`
- `FEACHCCOUNTNAME` 映射到 `收款人（公司名称）`
- `FEACHBANKACCOUNT` 映射到 `收款人帐号`
2. **动态值查找**
使用 `_findCollection` 函数从指定集合中查找动态值。例如，通过用户姓名查找用户ID和部门ID：
```json
{
"_findCollection find user_id from 0aa3e172-35e6-310b-8b94-3fbdec29583d where name={F_VAOJ_FQR}"
}
{
"_findCollection find dept_order_list.0.dept_id from 0aa3e172-35e6-310b-8b94-3fbdec29583d where name={F_VAOJ_FQR}"
}
```
3. **条件判断与函数应用**
对于某些字段，需要根据条件进行判断和转换。例如，对于货款属性字段，我们使用了 `_function case` 来实现：
```json
{
"_function case '{F_VAOJ_HKSX}' when 'CP' then '成品' else '辅料' end"
}
```
4. **最终数据结构**
将所有处理后的数据组装成符合钉钉API要求的数据结构，并通过POST方法提交：
```json
{
"_apiUrl_": "/topapi/processinstance/create",
"_method_": "_post_",
"_data_":
{
process_code: 'PROC-C1D46DC7-ACB2-4B63-8C48-F644942F63E5',
originator_user_id: '_findCollection find user_id from 0aa3e172-35e6-310b-8b94-3fbdec29583d where name={F_VAOJ_FQR}',
dept_id: '_findCollection find dept_order_list.0.dept_id from 0aa3e172-35e6-310b-8b94-3fbdec29583d where name={F_VAOJ_FQR}',
form_component_values: [
{name: '单据编号', value: '{FBillNo}'},
{name: '货款所属项目', value: '{FSETTLEORGID}'},
{name: '供应商名称', value: '{FCONTACTUNIT}'},
{name: '付款时间', value: '{{FCREATEDATE|date}}'},
{name: '货款属性', value: '_function case \'{F_VAOJ_HKSX}\' when \'CP\' then \'成品\' else \'辅料\' end'},
{name: '备注信息', value: '备注为：{F_VAOJ_Remarks}'},
{name: '付款金额（元）', value: '{FAPPLYAMOUNTFOR_H}'},
{name: '收款人（公司名称）', value: '{FEACHCCOUNTNAME}'},
{name: '收款人帐号', value: '{FEACHBANKACCOUNT}'}
]
}
}
```
通过以上步骤，我们成功地将金蝶付款申请单的数据转换为符合钉钉API要求的格式，并提交至目标平台，实现了系统间的数据无缝对接。
