### 案例分享：金蝶云星空数据集成方案解析
在本技术案例中，我们将深入探讨如何通过系统对接，实现从“采购入库单”到“成本调整单（委外材料）”的数据集成。该案例的主要目标是在两个金蝶云星空系统之间高效、可靠地传输和处理大量业务数据。
#### 数据获取与写入接口
首先，利用金蝶云星空提供的`executeBillQuery` API实现对采购入库单数据的抓取。该API允许我们根据特定参数查询并批量获取所需业务数据，这是整个流程中的关键一步。成功获取原始数据后，需要经过一定的数据转换逻辑，以适应下一步的数据写入操作。
为了保证高吞吐量和低延迟的数据写入，采用了`batchSave` API将处理后的成本调整单推送至目标金蝶云星空系统。这个API支持大批量数据的一次性写入，可显著提升整体效率，同时也减少了接口调用次数，提高稳定性。
#### 实时监控与告警机制
整个集成过程中，通过平台提供的集中监控和告警系统，对所有任务状态及性能进行实时跟踪。一旦检测到异常情况，如接口请求失败、超时或返回错误信息等，都能及时生成告警，并触发相应的重试机制，以确保最终不会出现漏单或漏传现象。这种全面而细致的监控措施，是保障全链路稳定运行的重要手段之一。
#### 数据质量与异常检测
此外，为了避免在流程中产生任何潜在的数据问题，我们部署了严格的数据质量监控和异常检测模块。这些模块会自动检验每一条待写入记录，包括字段完整性校验、格式一致性检查等，一旦发现不符合预期标准，将会暂停后续操作并即时通知相关人员进行纠正处理，从而保证持久性的高质量数据流动。
通过上述技术点实施，本案例成功地实现了一套可靠、高效且符合业务需求的跨系统集成解决方案。在接下来的部分，我们将详细介绍具体配置步骤及其背后的实现逻辑，帮助你更好地掌握这一过程中的各个环节。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何使用轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口来获取采购入库单和成本调整单（委外材料）的数据，并进行初步加工。
#### 接口配置与调用
首先，我们需要配置`executeBillQuery`接口的元数据。以下是该接口的配置细节：
- **API**: `executeBillQuery`
- **请求方法**: `POST`
- **分页参数**: 每页500条记录
- **主键字段**: `FInStockEntry_FEntryId`
- **请求字段**:
- `FInStockEntry_FEntryId`: 分录主键ID
- `FID`: 实体主键
- `FBillNo`: 单据编号
- `FDocumentStatus`: 单据状态
- `FStockOrgId_FNumber`: 收料组织
- `FDate`: 入库日期
- `FBillTypeID_FNumber`: 单据类型
- 更多字段详见元数据配置...
#### 请求参数构建
在构建请求参数时，需要特别注意分页和过滤条件。以下是一个示例请求参数：
```json
{
"FormId": "STK_InStock",
"FieldKeys": "FInStockEntry_FEntryId,FID,FBillNo,FDocumentStatus,FStockOrgId.FNumber,FDate,FBillTypeID.FNumber,...",
"FilterString": "FDate>='2023-01-01' and ( FBillTypeID.FNumber = 'RKD03_SYS' or FBillTypeID.FNumber ='RKD17_SYS' ) and FMaterialCosts > '0' and FDate<='2024-04-30 23:59:59'",
"Limit": 500,
"StartRow": 0,
"TopRowCount": true
}
```
#### 数据清洗与转换
获取到原始数据后，需要对其进行清洗和转换，以便后续处理。以下是一些常见的数据清洗和转换操作：
1. **字段映射与重命名**:
将原始字段名映射为目标系统所需的字段名。例如，将`FInStockEntry_FEntryId`映射为`entry_id`，将`FBillNo`映射为`bill_no`。
2. **数据类型转换**:
确保所有字段的数据类型符合目标系统的要求。例如，将日期字符串转换为标准日期格式，将数值字段转换为浮点数或整数。
3. **过滤无效数据**:
根据业务规则过滤掉无效或不完整的数据。例如，过滤掉单据状态为“作废”的记录。
4. **计算衍生字段**:
根据现有字段计算出新的衍生字段。例如，根据入库数量和单价计算总金额。
#### 实际案例
假设我们从金蝶云星空获取了以下几条采购入库单记录：
```json
[
{
"FInStockEntry_FEntryId": "1001",
"FID": "2001",
"FBillNo": "PO20230101",
"FDocumentStatus": "A",
"FStockOrgId.FNumber": "ORG001",
"FDate": "2023-01-01",
...
},
{
"FInStockEntry_FEntryId": "1002",
...
}
]
```
经过清洗和转换后，得到的数据可能如下：
```json
[
{
"entry_id": "1001",
"entity_id": "2001",
"bill_no": "PO20230101",
"document_status": "A",
"stock_org_number": "ORG001",
"date": "2023-01-01T00:00:00Z",
...
},
{
...
}
]
```
#### 小结
通过上述步骤，我们成功地从金蝶云星空获取了采购入库单和成本调整单的数据，并进行了必要的清洗和转换。这些操作确保了数据在进入下一个生命周期阶段时已经准备就绪，可以顺利进行进一步处理和分析。
### 数据集成：ETL转换与写入金蝶云星空API接口
在数据集成的生命周期中，ETL（Extract, Transform, Load）转换是至关重要的一环。本文将详细探讨如何使用轻易云数据集成平台，将采购入库单-成本调整单（委外材料）的数据转换为金蝶云星空API接口所能接收的格式，并最终写入目标平台。
#### 元数据配置解析
首先，我们需要理解元数据配置中的各个字段和参数，以便准确进行ETL转换。
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"method": "merge",
"field": "FBillNo,FDate",
"bodyName": "details",
"bodySum": ["FRealQty"],
"header": ["FBillNo", "FDate", "FPurchaseOrgId_FNumber", "FOwnerIdHead_FNumber"],
"body": ["FMaterialId_FNumber", "FRealQty", "FMaterialCosts", "FPurchaseOrgId_FNumber", "FOwnerIdHead_FNumber"]
},
...
}
```
在这个配置中，`api`字段指定了调用的API接口名称为`batchSave`，请求方法为`POST`。`idCheck`表示是否进行ID检查，而`operation`字段则定义了具体的操作方法和相关字段。
#### 请求参数与映射
请求参数部分定义了每个字段的映射关系和转换规则：
```json
{
...
"request": [
{"label":"FID","field":"FID","type":"string"},
{"label":"单据类型","field":"FBillTypeID","type":"string","value":"CGRKTZD01_SYS","parser":{"name":"ConvertObjectParser","params":"FNumber"}},
{"label":"单据编号","field":"FBillNo","type":"string","value":"{FBillNo}"},
{"label":"业务类型","field":"FBusinessType","type":"string","value":"1"},
{"label":"日期","field":"FDate","type":"string","value":"{FDate}"},
...
],
...
}
```
这些请求参数通过`parser`和`mapping`等属性，实现了从源数据到目标平台数据格式的转换。例如，`FBillTypeID`字段通过 `ConvertObjectParser` 转换为金蝶系统中的编码 `CGRKTZD01_SYS`。
#### 明细信息处理
明细信息部分是整个ETL过程中的关键，它涉及到多个子字段的映射和转换：
```json
{
...
{"label":"明细信息","field":"FEntity","type":"array","value":"details","children":[
{"parent":"FEntity","label":"库存组织","field":"FStockOrgID","type":"string","value":"{FOwnerIdHead_FNumber}"},
{"parent":"FEntity","label":"物料编码","field":"FMaterialID","type":"string","value":"{FMaterialId_FNumber}"},
{"parent":"FEntity","label":"调整金额","field":"FAdjustmentAMOUNT","type":"string","value":"{FMaterialCosts}"},
...
]}
}
```
在这个配置中，明细信息被定义为一个数组，每个子字段都进行了详细的映射。例如，库存组织 `FStockOrgID` 被映射为 `{FOwnerIdHead_FNumber}`，并通过 `ConvertObjectParser` 转换为目标系统所需格式。
#### 操作执行与提交
最后，我们需要配置操作执行和提交相关的信息：
```json
{
...
"otherRequest":[
{"field": "FormId", "label": "业务对象表单Id", "type": "string", "describe": "必须填写金蝶的表单ID如:PUR_PurchaseOrder", "value": "HS_AdjustmentBill"},
{"field": "Operation", "label": "执行的操作", "type": "string", "value": "BatchSave"},
{"field": "IsAutoSubmitAndAudit", "label": "提交并审核", "type": bool, value: true},
...
]
}
```
在这里，我们指定了业务对象表单ID `HS_AdjustmentBill` 和操作类型 `BatchSave`，并设置自动提交和审核为 `true`。
#### 实际案例应用
假设我们有一条采购入库单-成本调整单（委外材料）的源数据如下：
```json
{
FBillNo: 'PO12345',
FDate: '2023-10-01',
FOwnerIdHead_FNumber: 'ORG001',
details: [
{
FMaterialId_FNumber: 'MAT001',
FRealQty: '100',
FMaterialCosts: '5000'
}
// 更多明细项...
]
}
```
根据上述元数据配置，该源数据将被转换为如下目标格式，并通过 `batchSave` API 接口写入金蝶云星空：
```json
{
FormId: 'HS_AdjustmentBill',
Operation: 'BatchSave',
IsAutoSubmitAndAudit: true,
Model: {
FBillNo: 'PO12345',
FDate: '2023-10-01',
FOwnerIdHead_FNumber: 'ORG001',
FEntity: [
{
FStockOrgID: 'ORG001',
FMaterialID: 'MAT001',
FAdjustmentAMOUNT: '5000'
}
// 更多明细项...
]
}
}
```
通过上述步骤，我们实现了从源平台到目标平台的数据无缝对接，并确保了数据的一致性和准确性。
