### 金蝶云星空数据集成案例分享：30-物料同步--OK
在现代企业的数据管理中，系统对接和数据集成是提升业务效率的重要环节。本文将展示如何通过一个实际运行的方案——“30-物料同步--OK”，实现金蝶云星空与金蝶云星空之间的数据集成。
**项目背景**
该方案旨在解决企业内部不同系统间的物料数据传递问题，通过定时可靠地抓取源系统（如ERP）中的物料数据，并批量写入到目标系统（金蝶云星空）。为确保数据的完整性和一致性，我们使用了executeBillQuery接口来从源系统获取数据，并利用batchSave接口将处理后的物料信息保存到目标系统。
**技术实现**
1. **高吞吐量的数据写入能力**
- 采用批量处理机制，大幅提升了大量数据快速被集成到金蝶云星空系统中的性能。这不仅缩短了处理时间，也减少了网络通信开销。
2. **集中监控和告警**
- 实现实时跟踪整个数据集成任务的状态及性能，包括对API调用次数、成功率以及失败重试情况等关键指标进行监控。当出现异常情况时，能够即时发出告警通知，从而及时采取相应措施，保证任务正常运行。
3. **自定义数据转换逻辑**
- 针对不同业务需求和结构设计，自定义了一套灵活的数据转换规则，使得原始的ERP物料信息能够无缝映射并适配至金蝶云星空所需格式，实现优化配置。
4. **分页与限流控制**
- 为有效避免由于大规模请求引起API服务器负载过高的问题，我们针对executeBillQuery接口设置了合理的分页机制。同时加入限流控制策略，确保每次请求均能顺利完成，不漏单、不重复。
5. **异常处理与重试机制**
- 对于可能遇到的网络波动或服务暂不可用情形，引入健壮的错误检测和自动重试策略，以保障所有必要操作最终都能执行完毕，同时做好详细日志记录便于后续排查问题。
这些技术要点共同构筑了一条可信赖、高效益的数据通路，让企业轻松掌握并操控其核心资产。接下来，将讲述具体实施步骤及代码示例。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，第一步是从源系统获取数据。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空接口`executeBillQuery`，获取并加工物料数据。
#### 配置元数据
首先，我们需要配置元数据，以便正确调用金蝶云星空的API接口。以下是元数据配置的详细信息：
```json
{
"api": "executeBillQuery",
"method": "POST",
"number": "FNumber",
"id": "FMATERIALID",
"pagination": {
"pageSize": 100
},
"idCheck": true,
"request": [
{"field":"FMATERIALID","label":"实体主键","type":"string","value":"FMATERIALID"},
{"field":"FNumber","label":"编码","type":"string","value":"FNumber"},
{"field":"FName","label":"名称","type":"string","value":"FName"},
{"field":"FSpecification","label":"规格型号","type":"string","value":"FSpecification"},
{"field":"FOldNumber","label":"旧物料编码","type":"string","value":"FOldNumber"},
{"field":"FBARCODE","label":"条码","type":"string","value":"FBARCODE"},
{"field":"FDescription","label":"描述","type":"string","value":"FDescription"},
{"field":"FMaterialGroup_FNumber","label":"物料分组","type":"string","value":"FMaterialGroup.FNumber"},
{"field":"FErpClsID","label":"物料属性","type":"string","value":"FErpClsID"},
{"field":"FDocumentStatus","label":"数据状态","type":"string","value":"FDocumentStatus"},
{"field":"FForbidStatus","label":"禁用状态","type":"string","value":"FForbidStatus"},
{"field": "Limit", "label": "最大行数", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_PAGE_SIZE}"},
{"field": "StartRow", "label": "开始行索引", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_START_ROW}"},
{"field": "TopRowCount", "label": "返回总行数", "type": "int", "describe": ""},
{"field": "FilterString",
"label":
"过滤条件",
"type":
"string",
"describe":
"示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>=",
"value":
"FApproveDate>='{{LAST_SYNC_TIME|date}}' and FUseOrgId.FNumber='100'"
},
{
"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":
"BD_MATERIAL"
}
]
}
```
#### 调用API接口
根据上述元数据配置，我们使用POST方法调用`executeBillQuery`接口。以下是具体的请求示例：
```json
{
"FormId": "BD_MATERIAL",
"FieldKeys": [
"FMATERIALID",
...
],
...
}
```
在请求体中，我们需要传递表单ID（FormId）和需要查询的字段集合（FieldKeys）。此外，还可以通过`FilterString`字段设置过滤条件，例如：
```json
{
...
"FilterString":
FApproveDate>='2023-01-01' and FUseOrgId.FNumber='100'
}
```
#### 数据处理与清洗
获取到原始数据后，下一步是对其进行清洗和加工。轻易云平台提供了丰富的数据处理功能，可以对原始数据进行多种操作，包括但不限于：
1. **字段映射**：将源系统中的字段映射到目标系统中的对应字段。
2. **数据转换**：对特定字段进行格式转换，例如日期格式、数值单位等。
3. **过滤与筛选**：根据业务需求，对不符合条件的数据进行过滤。
例如，对于物料编码（`FNumber`）和名称（`FName`）字段，可以进行如下处理：
```json
{
...
{
field: 'FMATERIALID',
label: '实体主键',
type: 'string',
value: 'FMATERIALID'
},
{
field: 'FNumber',
label: '编码',
type: 'string',
value: 'FNumber'
},
{
field: 'FName',
label: '名称',
type: 'string',
value: 'FName'
}
}
```
#### 分页处理
由于可能存在大量的数据，分页处理是必要的。我们可以通过设置分页参数来控制每次请求的数据量。例如，每次请求100条记录，并通过调整起始行索引来实现分页：
```json
{
...
{
field:
Limit,
label:
最大行数,
type:
string,
describe:
金蝶的查询分页参数,
value:
{PAGINATION_PAGE_SIZE}
},
{
field:
StartRow,
label:
开始行索引,
type:
string,
describe:
金蝶的查询分页参数,
value:
{PAGINATION_START_ROW}
}
```
#### 实时监控与日志记录
在整个过程中，实时监控和日志记录是确保数据集成顺利进行的重要手段。轻易云平台提供了全面的监控功能，可以实时查看每个步骤的数据流动和处理状态，并记录详细日志以便排查问题。
通过以上步骤，我们可以高效地从金蝶云星空获取物料数据，并对其进行清洗和加工，为后续的数据转换与写入打下坚实基础。
### 使用轻易云数据集成平台实现金蝶云星空API接口的数据转换与写入
在数据集成的生命周期中，ETL（提取、转换、加载）过程是关键的一环。本文将深入探讨如何利用轻易云数据集成平台，将已经集成的源平台数据进行ETL转换，并转为金蝶云星空API接口所能够接收的格式，最终写入目标平台。
#### 配置元数据
首先，我们需要配置元数据以适应金蝶云星空API接口的要求。以下是一个典型的元数据配置示例：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 20,
"method": "batchArraySave"
},
"request": [
{"field": "FName", "label": "名称", "type": "string", "value": "{FName}"},
{"field": "FNumber", "label": "编码", "type": "string", "value": "{FNumber}"},
{"field": "FDescription", "label": "描述", "type": "string", "value": "{FDescription}"},
{"field": "FCreateOrgId",
"label": "创建组织",
"type": "string",
"parser":{"name":"ConvertObjectParser","params":"FNumber"},
"value":"100"
},
{"field": "FUseOrgId",
"label":"使用组织",
"type":"string",
"parser":{"name":"ConvertObjectParser","params":"FNumber"},
"value":"100"
},
{
...
// 其他字段省略
...
}
],
...
}
```
#### 数据请求与清洗
在进行数据转换之前，首先需要从源系统请求数据并进行清洗。这个过程通常包括以下步骤：
1. **请求源数据**：通过API或者数据库连接获取源系统的数据。
2. **数据清洗**：对获取的数据进行预处理，包括去除无效值、标准化字段格式等。
#### 数据转换
接下来，我们需要将清洗后的数据转换为金蝶云星空API能够接受的格式。这一步骤包括字段映射和格式转换。
1. **字段映射**：根据元数据配置，将源系统的数据字段映射到目标系统所需的字段。例如，将源系统中的`物料名称`映射到目标系统中的`FName`。
2. **格式转换**：根据目标系统的要求，对字段进行必要的格式转换。例如，将日期格式从`YYYY-MM-DD`转换为`YYYYMMDD`，或者将数值类型从字符串转换为整数。
以下是一个简单的字段映射示例：
```json
{
// 源系统的数据
{
"_id" : ObjectId("5f50c31e1c9d440000a7b0d3"),
"_class" : "",
...
// 源系统其他字段
...
}
// 转换后的目标系统的数据
{
...
// 映射后的字段
FName: sourceData.materialName,
FNumber: sourceData.materialCode,
FDescription: sourceData.materialDesc,
FCreateOrgId: convertToOrgId(sourceData.createOrg),
FUseOrgId: convertToOrgId(sourceData.useOrg),
// 子对象映射
SubHeadEntity: {
FErpClsID: sourceData.erpClsID,
FBaseUnitId: convertToUnitId(sourceData.baseUnit),
FCategoryID: convertToCategoryID(sourceData.category),
FMaterialGroup: convertToMaterialGroup(sourceData.materialGroup),
FDJZDYPingPai: convertToBrand(sourceData.brand)
},
SubHeadEntity1: {
FStockId: convertToStockId(sourceData.stock)
}
...
// 转换后的其他字段
...
}
```
#### 数据写入
最后一步是将转换后的数据通过API接口写入金蝶云星空。根据元数据配置，我们使用POST方法调用`batchSave` API：
```javascript
const axios = require('axios');
async function writeToKingdee(data) {
const config = {
method: 'post',
url: 'https://api.kingdee.com/batchSave',
headers: {
'Content-Type': 'application/json'
},
data : data
};
try {
const response = await axios(config);
console.log(JSON.stringify(response.data));
} catch (error) {
console.error(error);
}
}
// 调用函数并传入转换后的数据
writeToKingdee(transformedData);
```
通过上述步骤，我们可以成功地将源平台的数据经过ETL处理后，转化为金蝶云星空API所能接受的格式，并最终写入目标平台。这一过程不仅提高了业务流程的透明度和效率，也确保了不同系统间的数据无缝对接。
