### 金蝶云星空与广东省特殊食品电子追溯平台数据集成案例
在进行金蝶云星空到广东省特殊食品电子追溯平台的数据对接时，我们选择了“品牌--分步式调入同步（销退）”方案，确保整个过程的高效性和可靠性。本文将探讨如何使用API接口executeBillQuery从金蝶云星空获取数据并成功写入到广东省特殊食品电子追溯平台的ReturnDetailInfo接口。
#### 1. 数据获取及分页处理
首先，系统需要通过调用金蝶云星空提供的executeBillQuery API来抓取订单退货信息。该过程中会涉及到分页和限流问题，为此我们采用了以下策略：
- **分页处理**：根据实际记录量，通过参数设置实现多次请求，以避免单次请求数据过大导致超时或失败。
- **限流控制**：为防止对源系统造成压力，每次请求增设合理频率限制，同时监控各批次返回结果，确保无遗漏。
#### 2. 数据转换及格式适配
由于两个系统间的数据结构存在差异，需要自定义转换逻辑来匹配双方要求。这包括字段映射、类型转换等具体操作。在轻易云数据集成平台中，我们利用其可视化设计工具完成这些任务，使得流程更加直观且易于管理。
例如，从executeBillQuery API获取到的数据可能包含多个嵌套结构，而ReturnDetailInfo API则需要扁平化后的JSON对象。因此，在转发前需逐个解析并重组数据包，以满足目标接口要求。
#### 3. 实时监控与异常处理机制
为了保证整个集成过程的稳定运行，对实时监控和异常检测提出了严格要求。特别是当大量数据快速写入到广东省特殊食品电子追溯平台时，通过集中式监控和告警系统实时跟踪每一个任务的状态，一旦发现错误立即触发重试机制：
- **日志记录与分析**：详细记录每一次API调用，包括响应时间、结果状态等，有助于快速定位问题根源。
- **自动重试**：针对常见网络波动或临时故障，引入自动重试功能，多次尝试后仍未成功才会上报人工干预通知。
通过上述步骤，使我们能够高效地完成金蝶云星空与广东省特殊食品电子追溯平台之间的大规模数据同步工作，并保障业务连续性的同时提升整体运作效率。在接下来的部分中，将深入解析具体实施细节及代码示例。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口，以实现品牌分步式调入同步（销退）的数据获取和初步加工。
#### 接口调用配置
首先，我们需要配置调用金蝶云星空接口的元数据。以下是元数据配置的关键部分：
```json
{
"api": "executeBillQuery",
"method": "POST",
"number": "FBillNo",
"id": "FSTKTRSINENTRY_FEntryID",
"pagination": {
"pageSize": 500
},
"request": [
{"field":"FSTKTRSINENTRY_FEntryID","label":"FEntryID","type":"string","value":"FSTKTRSINENTRY_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","label":"单据类型","type":"string","value":"FBillTypeID"},
{"field":"FTransferDirect","label":"调拨方向","type":"string","value":"FTransferDirect"},
{"field":"FNOTE","label":"备注","type":"string","value":"FNOTE"},
{"field":"FCreateDate","label":"创建日期","type":"string","value":"FCreateDate"},
{"field":"FApproveDate","label":"审核日期","type":"string","value":"FApproveDate"},
{"field":...}
],
"otherRequest": [
{"field": "Limit", "label": "最大行数", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_PAGE_SIZE}"},
{"field": "StartRow", "label": "开始行索引", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_START_ROW}"},
{"field":...}
]
}
```
#### 请求参数解析
在请求参数中，我们需要特别注意以下几个字段：
- `FormId`: 表示业务对象表单Id，在本案例中为`STK_TRANSFERIN`。
- `FieldKeys`: 指定需要查询的字段集合，格式为数组。
- `FilterString`: 用于定义过滤条件，例如：
```sql
FApproveDate >= '{{LAST_SYNC_TIME|dateTime}}' and FTransferDirect = 'RETURN' and FStockOrgID.fnumber = '100' and FStockOutOrgID.fnumber = '101'
```
这些字段确保我们能够精准地获取所需的数据。
#### 数据请求与清洗
在实际操作中，我们通过POST方法向`executeBillQuery`接口发送请求，并根据配置的分页参数进行多次请求以获取完整的数据集。以下是一个示例请求体：
```json
{
"FormId": "STK_TRANSFERIN",
"FieldKeys": ["FID", "FBillNo", ...],
"FilterString": "...",
...
}
```
每次请求返回的数据需要进行初步清洗和转换，以便后续处理。例如，可以通过编写脚本或使用轻易云平台内置功能对返回的数据进行去重、格式转换等操作。
#### 数据转换与写入
在完成数据清洗后，下一步是将数据转换为目标系统所需的格式，并写入目标数据库或系统。这一步通常涉及复杂的映射规则和业务逻辑，需要根据具体需求进行定制。
#### 实时监控与错误处理
为了确保数据集成过程的稳定性和可靠性，实时监控和错误处理机制必不可少。轻易云平台提供了丰富的监控工具，可以实时跟踪数据流动和处理状态，并在出现异常时及时报警和处理。
通过上述步骤，我们可以高效地调用金蝶云星空接口获取并加工所需的数据，为后续的数据集成奠定坚实基础。
### 使用轻易云数据集成平台进行ETL转换并写入广东省特殊食品电子追溯平台
在数据集成生命周期的第二步中，我们需要将已经集成的源平台数据进行ETL（提取、转换、加载）处理，最终将其转换为目标平台——广东省特殊食品电子追溯平台API接口所能够接收的格式，并写入目标平台。以下是详细的技术实现步骤。
#### API接口配置
我们使用的目标API接口为`ReturnDetailInfo`，该接口采用POST方法进行数据提交。元数据配置如下：
```json
{
"api": "ReturnDetailInfo",
"effect": "EXECUTE",
"method": "POST",
"number": "1",
"id": "1",
"name": "1",
"idCheck": true,
"request": [
{
"field": "DOCUMENTID",
"label": "文档唯一标识号",
"type": "string",
"describe": "暂无描述",
"value": "_function CONCAT('{FBillNo}-{FID}', FLOOR(RAND() * 10001))"
},
{
"field": "dataset",
"label": "数据集",
"type": "array",
"describe": "暂无描述",
"children": [
{
...
}
]
}
]
}
```
#### 数据字段映射与转换
在ETL过程中，我们需要将源平台的数据字段映射到目标平台所需的数据字段，并进行必要的转换。以下是具体的字段映射和转换规则：
1. **文档唯一标识号 (DOCUMENTID)**
- 来源字段：`FBillNo` 和 `FID`
- 转换规则：使用 `_function CONCAT('{FBillNo}-{FID}', FLOOR(RAND() * 10001))` 拼接生成唯一标识号。
2. **退货单号 (returnNumber)**
- 来源字段：`FBillNo`
- 转换规则：使用 `_function CONCAT('{FBillNo}', FLOOR(RAND() * 10001))` 拼接生成退货单号。
3. **退货日期 (returnDate)**
- 来源字段：`FDate`
- 转换规则：使用 `{{FDate|date}}` 格式化为 `yyyy-mm-dd` 格式。
4. **供应商企业名称 (supplierEnterpriseName)**
- 来源字段：通过 `FCustID_FNumber` 查询 MongoDB 获取 `content.FName`
- 转换规则：使用 `_mongoQuery da6fffcd-e55f-3237-8be1-72194dc4777d findField=content.FName where={"content.FNumber":{"$eq":"{FCustID_FNumber}"}}`
5. **供应商企业许可证编号 (supplierEnterprisePermitNumber)**
- 转换规则：默认值为 `isNull`
6. **产品条形码 (productBarCode)**
- 来源字段：`F_APP_BaseProperty`
7. **生产批号 (batch)**
- 来源字段：`FLOT`
8. **退货数量 (total)**
- 来源字段：`FQty`
9. **生产日期 (produceDate)**
- 来源字段：`FProduceDate`
- 转换规则：使用 `{{FProduceDate|date}}` 格式化为 `yyyy-mm-dd` 格式。
10. **计量单位 (packUnitName)**
- 来源字段：通过 `FUnitID` 查询 MongoDB 获取 `content.Name`
- 转换规则：使用 `_mongoQuery da6fffcd-e55f-3237-8be1-72194dc4777d findField=content.Name where={"content.Id":{"$eq":"{FUnitID}"}}`
11. **箱码 (boxCode)**
- 转换规则：默认值为 `isNull`
12. **追溯码 (traceCode)**
- 来源字段：`FLOT`
#### 数据写入
在完成上述数据转换后，我们将处理后的数据通过POST方法写入到广东省特殊食品电子追溯平台。以下是示例请求体：
```json
{
"DOCUMENTID": "<生成的文档唯一标识号>",
"dataset": [
{
...
}
]
}
```
通过上述步骤，我们成功实现了从源平台到目标平台的数据ETL转换和写入。在实际操作中，确保每个步骤都准确无误，以保证数据的完整性和一致性。
