### 案例分享：金蝶云星空数据集成到金蝶云星空 - 采购退料单（委外）OK方案
在企业信息系统的日常运维中，精准、稳定的数据对接至关重要。本文聚焦于一个具体的技术案例，介绍如何实现将“采购退料单（委外）”数据从金蝶云星空系统高效且精确地集成到另一个金蝶云星空实例中。
此次数据集成采用轻易云数据集成平台，通过配置特定的数据流和API映射来完成。而选择轻易云平台进行此项任务，是因为其支持高吞吐量的数据写入能力，以及全面完善的监控告警机制。在这个过程中，我们主要使用了以下几个关键API：
1. **获取数据的API**：executeBillQuery
2. **写入数据的API**：batchSave
首先，在整个对接流程开始之前，需要解决两个核心问题：
- 如何确保从源系统准确抓取所有相关业务单据，并避免漏单现象。
- 如何快速、高效地批量处理并将这些大规模数据写入目标系统。
为了解决第一个问题，设计了一套基于时间戳和状态标识符联合校验的方法，每次调用`executeBillQuery`接口时，都通过查询增量更新记录以及待处理状态的数据，实现高效、安全的数据抓取。其次，为了应对大量实时交易带来的性能压力，我们利用轻易云的平台特性，如自定义分布式事务管理策略，与batchSave API相结合，有力保障了海量数据信息能分块、批次导入，不会导致目标数据库负载过重或出现限流瓶颈。
此外，全生命周期管理功能使我们能够实时监控每一条由源端拉取，到转换，再上传至目标端这全流程中的任何异常情况。当检测到某些关键操作失败时，即刻触发错误告警并启动重试机制，以确保最终一致性及完整性。同时可视化工作台，也让团队成员更直观地理解各环节动作及其依赖关系，大幅减少沟通成本，加快项目推进进度。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，第一步是从源系统获取数据。本文将详细探讨如何通过调用金蝶云星空接口`executeBillQuery`来获取采购退料单（委外）的数据，并进行初步加工。
#### 接口配置与请求参数
首先，我们需要配置接口及其请求参数。根据提供的元数据配置，`executeBillQuery`接口采用POST方法，主要参数包括单据编号（FBillNo）、实体主键（FID）等。以下是请求参数的详细配置：
```json
{
"api": "executeBillQuery",
"method": "POST",
"number": "FBillNo",
"id": "FPURMRBENTRY_FEntryID",
"pagination": {
"pageSize": 500
},
"idCheck": true,
"request": [
{"field":"FPURMRBENTRY_FEntryID","label":"明细信息ID","type":"string","value":"FPURMRBENTRY_FEntryID"},
{"field":"FID","label":"实体主键","type":"string","value":"FID"},
{"field":"FBillNo","label":"单据编号","type":"string","value":"FBillNo"},
{"field":"FDocumentStatus","label":"单据状态","type":"string","value":"FDocumentStatus"},
{"field":"FStockOrgId_FNumber","label":"退料组织","type":"string","value":"FStockOrgId.FNumber"},
{"field":"FDate","label":"退料日期","type":"string","value":"FDate"},
{"field":"FBillTypeID_FNumber","label":"单据类型","type":"string","value":"FBillTypeID.FNumber"},
{"field":"FTAKEDELIVERYNO","label":"提货单号","type":"string","value":"FTAKEDELIVERYNO"},
{"field":"FSupplierID_FName","label":"供应商","type":"string","value":"FSupplierId.FName"},
{"field":"FDESCRIPTION","label":"备注","type":"string","value":"FDESCRIPTION"}
],
"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":
`示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>="`,
`value`: `FApproveDate>='{{LAST_SYNC_TIME|date}}' and FBillTypeID.FNumber= 'TLD04_SYS' and FMRTYPE<>'A'`
},
{"field":
`FieldKeys`,
`label`: `需查询的字段key集合`,
`type`: `array`,
`describe`: `金蝶分录主键ID格式：FPOOrderEntry_FEntryId,其它格式 FPurchaseOrgId.FNumber`,
`parser`: {`name`: `ArrayToString`, `params`: ","}},
{`field`: `FormId`, `label`: `业务对象表单Id`, `type`: `string`, `describe`: 必须填写金蝶的表单ID如:PUR_PurchaseOrder, value: PUR_MRB}
]
}
```
#### 数据请求与清洗
在调用接口时，我们需要特别注意分页参数和过滤条件。分页参数确保我们能够逐页获取大量数据，而过滤条件则用于精确筛选所需的数据。例如，通过设置`FilterString`为`FApproveDate>='{{LAST_SYNC_TIME|date}}' and FBillTypeID.FNumber= 'TLD04_SYS' and FMRTYPE<>'A'`，我们可以筛选出特定时间段内符合条件的采购退料单。
以下是一个示例请求体：
```json
{
"FormId": "PUR_MRB",
"FieldKeys": [
FPURMRBENTRY_FEntryID, FID, FBillNo, FDocumentStatus, FStockOrgId.FNumber,
FDate, FBillTypeID.FNumber, FTAKEDELIVERYNO, FSupplierId.FName, FDESCRIPTION
],
FilterString: `FApproveDate>='2023-01-01' and FBillTypeID.FNumber= 'TLD04_SYS' and FMRTYPE<>'A'`,
Limit: 500,
StartRow: 0
}
```
#### 数据转换与写入
在获取到原始数据后，我们需要对其进行初步清洗和转换，以便后续处理和存储。清洗过程可能包括：
1. **字段映射**：将原始字段名映射为目标系统中的字段名。
2. **数据格式转换**：例如，将日期字符串转换为标准日期格式。
3. **数据校验**：检查关键字段是否为空或格式是否正确。
以下是一个简单的数据清洗示例：
```python
def clean_data(raw_data):
cleaned_data = []
for record in raw_data:
cleaned_record = {
'entry_id': record['FPURMRBENTRY_FEntryID'],
'bill_no': record['FBillNo'],
'status': record['FDocumentStatus'],
'org_id': record['FStockOrgId.FNumber'],
'date': convert_date(record['FDate']),
'supplier_name': record['FSupplierId.FName'],
'description': record['FDESCRIPTION']
}
cleaned_data.append(cleaned_record)
return cleaned_data
def convert_date(date_str):
# 假设日期格式为 YYYY-MM-DD
return datetime.strptime(date_str, '%Y-%m-%d')
```
通过上述步骤，我们可以有效地从金蝶云星空系统中获取并清洗采购退料单（委外）数据，为后续的数据处理和分析打下坚实基础。在整个过程中，轻易云数据集成平台提供了全透明可视化的操作界面，使得每个环节都清晰易懂，并实时监控数据流动和处理状态，大大提升了业务透明度和效率。
### 轻易云数据集成平台中的ETL转换与金蝶云星空API接口集成技术案例
在数据集成生命周期的第二步中，我们需要将已经集成的源平台数据进行ETL转换，转为目标平台金蝶云星空API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨如何利用轻易云数据集成平台配置元数据，实现采购退料单（委外）的数据转换和写入。
#### 元数据配置解析
元数据配置是实现ETL转换的关键部分。以下是一个典型的元数据配置示例：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"method": "merge",
"field": "FBillNo,FDate,FSupplierID_FName,FSettleCurrId_FNumber",
"bodyName": "details",
"header": ["FBillNo", "FDate", "FSupplierID_FName", "FSettleCurrId_FNumber", "FStockOrgId_FNumber"],
"body": ["FMATERIALID_FNumber", "FRMREALQTY", "FTAXPRICE", "FALLAMOUNT", "FDiscount", "FStockOrgId_FNumber"]
},
...
}
```
该配置定义了请求方式、操作方法以及需要处理的数据字段。具体字段的解释如下：
- `api` 和 `method`：指定了调用金蝶云星空API的接口和HTTP方法。
- `idCheck`：用于检查是否存在重复记录。
- `operation`：定义了数据处理的方法和字段映射，包括头部和明细部分。
#### 数据请求与清洗
在进行ETL转换之前，首先需要对源平台的数据进行请求与清洗。这一步骤确保我们获取到的数据是准确且符合要求的。以下是部分关键字段及其对应的处理逻辑：
```json
{
...
{
"field": "FBillNo",
"label": "单据编号",
"type": "string",
...
"value": "{FBillNo}-1"
},
{
...
"field": "FDate",
...
"value": "{FDate}"
},
{
...
"field": "FSupplierID",
...
...
...
}
```
这些字段定义了从源平台获取的数据如何映射到目标平台中。例如，`FBillNo` 字段在传输过程中增加了后缀 `-1` 以避免重复；`FDate` 字段直接映射日期值。
#### 数据转换与写入
接下来，我们将清洗后的数据进行转换，使其符合金蝶云星空API接口的要求，并最终写入目标平台。这一步主要涉及复杂的数据映射和格式转换。例如：
```json
{
...
{
...
field: 'FPURMRBENTRY',
label: '明细信息',
type: 'array',
children: [
{
field: 'FMATERIALID',
label: '物料编码',
type: 'string',
parser: { name: 'ConvertObjectParser', params: 'FNumber' },
value: '{{details.FMATERIALID_FNumber}}'
},
{
field: 'FRMREALQTY',
label: '实退数量',
type: 'string',
value: '{{details.FRMREALQTY}}'
},
...
]
}
}
```
这里，`FPURMRBENTRY` 定义了采购退料单明细信息，其中包括物料编码、实退数量等字段。每个字段都通过特定的解析器（如 `ConvertObjectParser`）进行转换，以确保符合金蝶云星空API接口的格式要求。
#### 特殊逻辑处理
在某些情况下，需要根据特定业务逻辑对数据进行处理。例如，根据不同的组织编码设置不同的值：
```json
{
field: 'FOwnerIdHead',
label: '货主',
type: 'string',
parser: { name: 'ConvertObjectParser', params: 'FNumber' },
value: "_function case when '{FStockOrgId_FNumber}' ='100' then '104' when '{FStockOrgId_FNumber}' ='202' then '126' else '109' end"
}
```
这种情况下，通过 `_function case when ... then ... end` 语句实现条件判断和赋值，确保不同组织编码对应正确的货主编号。
#### 调用API并写入目标平台
最后，将所有处理好的数据通过POST请求发送至金蝶云星空API接口，实现最终的数据写入：
```json
{
api:"batchSave",
method:"POST",
idCheck:true,
operation:{
method:"merge",
field:"FBillNo,FDate,FSupplierID_FName,FSettleCurrId_FNumber",
bodyName:"details",
header:["FBillNo","FDate","FSupplierID_FName","FSettleCurrId_FNumber","FStockOrgId_FNumber"],
body:["FMATERIALID_FNumber","FRMREALQTY","FTAXPRICE","FALLAMOUNT","FDiscount","FStockOrgId_FNumber"]
},
request:[...],
otherRequest:[...]
}
```
通过上述配置和调用，我们成功实现了从源平台到金蝶云星空API接口的数据ETL转换和写入。
本文详细探讨了如何利用轻易云数据集成平台中的元数据配置，实现采购退料单（委外）的ETL转换与写入金蝶云星空API接口。通过合理配置和调用API，我们能够高效地完成复杂的数据集成任务。
