### 金蝶云星空与聚水潭系统集成：采购退货对接案例分享
在现代企业运营中，数据的精准流转与高效处理是提升业务效率的关键。本文将重点分享一个实际运行方案——金蝶采购退货对接聚水潭采购退货ok，通过使用轻易云数据集成平台，实现两个系统间的数据无缝衔接。
#### 集成架构概览
为了保证金蝶云星空到聚水潭的数据集成不漏单，轻易云数据集成平台提供了全生命周期管理和实时监控功能。首先，我们通过调用金蝶云星空接口`executeBillQuery`定时可靠地抓取采购退货的相关数据。该接口支持分页查询，以应对大规模数据量，同时可以根据需求设置限流机制，确保接口稳定性。在采集到有效的数据后，将其批量写入到聚水潭指定的API `jushuitan.purchaseout.upload` 中，这一过程需要处理两者之间的数据格式差异并进行定制化映射。
#### 关键技术实现
**1. 数据获取与分页处理**
我们采用分步式策略，每次调用`executeBillQuery` API 时，仅提取一定数量记录，并利用分页参数逐页遍历。这不仅防止一次性加载过多产生压力，也简化了错误重试逻辑。在保证每一页查询的位置精确记录下来的前提下，即使在异常情况下也能准确继续上一次中断点，从而避免任何遗漏。
**2. 数据快速写入及格式适配**
对于从金蝶云星空获取到的大量采购退货信息，需要进行同步至聚水潭。而这一步骤则通过优化后的批量处理方式来完成，其中借助轻易云平台强大的转换引擎，可以灵活地将不同字段名称、类型等转换为目标系统所需格式，提高上传速度和成功率。此外，还会涉及到一些自定义规则来满足特定业务需求，使得最终生成的数据满足聚水潭 API 的规范要求。
#### 异常处理及监控机制
针对可能出现的问题，如网络波动或API限制等情况，实施了细致的异常捕获和重试机制。当检测到失败时，会自动触发重试逻辑，并在日志中详细记录失败原因以便后续排查。同时，为确保整个流程透明可追踪，每个步骤都会有详尽日志输出，通过可视化界面展示实时数据处理状态，从而及时发现并解决问题，保障整个集成工作的顺利执行。
这一系列高效且安全的方法，不仅加速了企业内部各部门间的信息共享，还显著提升了整体操作中的可靠性，在施工项目中起到了举足轻重的作用
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，第一步是调用源系统接口获取数据。本文将详细介绍如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口，获取采购退货数据并进行初步加工。
#### 接口配置与调用
首先，我们需要配置并调用金蝶云星空的`executeBillQuery`接口。以下是元数据配置的关键部分：
```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_FNumber","label":"供应商","type":"string","value":"FSupplierID.FNumber"},
{"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|dateTime}}' AND FDocumentStatus = 'C' AND FStockId.FGROUP='现货仓库' AND FISGENFORIOS != 1`
},
{"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`
}
]
}
```
#### 数据请求与清洗
在调用接口时，我们需要传递适当的参数以确保获取到所需的数据。以下是一些关键参数及其作用：
- **FormId**: 表单ID，例如`PUR_MRB`表示采购退货。
- **FieldKeys**: 查询字段集合，通过解析器将数组转换为字符串。
- **FilterString**: 用于过滤数据，例如根据审批日期和单据状态进行过滤。
- **Limit**和**StartRow**: 分页参数，用于控制每次请求的数据量和起始位置。
通过这些参数，我们可以构建一个完整的API请求，确保获取到符合条件的数据。
#### 数据转换与写入
在获取到原始数据后，需要对其进行初步加工。这包括数据清洗、格式转换等操作。例如，将日期字段转换为标准格式，确保所有字段都有一致的命名和类型。
以下是一个简单的数据清洗示例：
```python
def clean_data(raw_data):
cleaned_data = []
for entry in raw_data:
cleaned_entry = {
'明细信息ID': entry.get('FPURMRBENTRY_FEntryID'),
'实体主键': entry.get('FID'),
'单据编号': entry.get('FBillNo'),
'单据状态': entry.get('FDocumentStatus'),
'退料组织': entry.get('FStockOrgId_FNumber'),
'退料日期': format_date(entry.get('FDate')),
'供应商': entry.get('FSupplierID_FNumber'),
'备注': entry.get('FDESCRIPTION')
}
cleaned_data.append(cleaned_entry)
return cleaned_data
def format_date(date_str):
# 假设日期格式为 YYYY-MM-DD
return date_str.replace('-', '/')
```
通过上述代码，我们可以将原始数据中的日期格式从`YYYY-MM-DD`转换为`YYYY/MM/DD`，并确保所有字段都有一致的命名。
#### 实践案例
假设我们需要从金蝶云星空中获取所有在特定时间段内已审核通过且未生成跨组织结算的采购退货记录，并将其导入到聚水潭系统中。我们可以按照以下步骤进行操作：
1. 配置API请求参数，包括表单ID、查询字段、过滤条件等。
2. 调用`executeBillQuery`接口获取原始数据。
3. 对原始数据进行清洗和格式转换。
4. 将清洗后的数据写入目标系统（例如聚水潭）。
通过这种方式，我们可以实现不同系统间的数据无缝对接，确保业务流程的顺畅运行。
### 数据集成生命周期的第二步：ETL转换与数据写入聚水潭API接口
在数据集成过程中，ETL（Extract, Transform, Load）转换是至关重要的一环。本文将深入探讨如何将已经集成的源平台数据，通过ETL转换为目标平台聚水潭API接口所能接收的格式，并最终写入目标平台。
#### 1. 数据请求与清洗
在进入ETL转换之前，首先需要从源系统获取原始数据并进行清洗。假设我们已经完成了这一步，接下来将重点放在如何将清洗后的数据进行转换和写入。
#### 2. 数据转换与写入
为了实现数据的无缝对接，我们需要根据聚水潭API接口的要求，对数据进行格式化处理。以下是详细的元数据配置及其应用。
##### 元数据配置解析
```json
{
"api": "jushuitan.purchaseout.upload",
"method": "POST",
"idCheck": true,
"operation": {
"method": "merge",
"field": "FBillNo,FSTOCKID_FNumber",
"bodyName": "items",
"bodySum": ["FRMREALQTY"],
"header": ["FBillNo", "FSupplierID_FNumber", "FSTOCKID_FNumber"],
"body": ["FMATERIALID_FNumber", "FRMREALQTY", "FLot_FNumber", "FProduceDate", "FEXPIRYDATE"]
},
"request": [
{"field":"is_confirm","label":"是否自动确认","type":"string","describe":"是否自动确认"},
{"field":"wms_co_id","label":"分仓编号","type":"string","describe":"分仓编号","value":"{FSTOCKID_FNumber}"},
{"field":"supplier_id","label":"供应商编号","type":"string","describe":"供应商编号","value":"_findCollection find supplier_id from 8212cf64-d26d-3c38-8112-d4ffae353278 where supplier_code={FSupplierID_FNumber}"},
{"field":"po_id","label":"采购单号","type":"string","describe":"采购单号"},
{"field":"external_id","label":"外部单号","type":"string","describe":"外部单号","value":"{FBillNo}"},
{"field":"remark","label":"备注","type":"string","describe":"备注"},
{"field":"warehouse","label":"仓库编号","type":"string","describe":"仓库编号 主仓=1，销退仓=2， 进货仓=3，次品仓 = 4","value":"1"},
{
"field": "items",
"label": "items",
"type": "array",
"describe": "items",
"children": [
{"field": "sku_id", "label": "商品编码", "type": "string", "describe": "商品编码", "value": "{{items.FMATERIALID_FNumber}}",
{"field":
qty",
label:
数量,
type:
string,
describe:
数量,
value: "{{items.FRMREALQTY}}"},
{"field":
price,
label: 单价,
type: string,
describe: 单价},
{"field":
batch_id,
label: 批次单号,
type:
string,
describe:
批次单号，
系统中需开启相关配置,
value:
"{{items.FLot_FNumber}}"},
{"field":
produced_date,
label:
生产日期,
type:
string,
describe:
生产日期，
系统中需开启相关配置,
value:
"{{items.FProduceDate}}"}
],
value:"items"}]
}
```
##### 数据字段映射
1. **头部字段**
- `FBillNo`：采购单号
- `FSupplierID_FNumber`：供应商编号
- `FSTOCKID_FNumber`：分仓编号
2. **主体字段**
- `FMATERIALID_FNumber`：商品编码
- `FRMREALQTY`：数量
- `FLot_FNumber`：批次单号
- `FProduceDate`：生产日期
- `FEXPIRYDATE`：到期日期
##### 请求参数解析
- **is_confirm**：是否自动确认
- **wms_co_id**：分仓编号（通过 `{FSTOCKID_FNumber}` 动态获取）
- **supplier_id**：供应商编号（通过 `_findCollection` 查询）
- **po_id**：采购单号
- **external_id**：外部单号（通过 `{FBillNo}` 动态获取）
- **remark**：备注信息
- **warehouse**：仓库编号（固定值为1）
##### 子项参数解析
- **sku_id**：商品编码（通过 `{{items.FMATERIALID_FNumber}}` 动态获取）
- **qty**：数量（通过 `{{items.FRMREALQTY}}` 动态获取）
- **price**：单价
- **batch_id**：批次单号（通过 `{{items.FLot_FNumber}}` 动态获取）
- **produced_date**：生产日期（通过 `{{items.FProduceDate}}` 动态获取）
#### 实际应用案例
假设我们从金蝶系统中获取了一条采购退货记录，其包含以下信息：
```json
{
FBillNo: 'PO123456',
FSupplierID_FNumber: 'SUP001',
FSTOCKID_FNumber: 'WH01',
items: [
{
FMATERIALID_FNumber: 'MAT001',
FRMREALQTY: '100',
FLot_FNumber: 'LOT123',
FProduceDate: '2023-01-01',
FEXPIRYDATE: '2024-01-01'
}
]
}
```
根据上述元数据配置，我们将其转换为聚水潭API所需的格式：
```json
{
is_confirm: 'true',
wms_co_id: 'WH01',
supplier_id: '_findCollection find supplier_id from ... where supplier_code=SUP001',
po_id: '',
external_id: 'PO123456',
remark: '',
warehouse: '1',
items: [
{
sku_id: 'MAT001',
qty: '100',
price: '',
batch_id: 'LOT123',
produced_date: '2023-01-01'
}
]
}
```
#### 总结
本文详细介绍了如何利用轻易云数据集成平台，将源平台的数据经过ETL转换后，写入目标平台聚水潭API接口。通过对元数据配置的深入解析和实际案例的展示，可以看出在整个过程中，每个步骤都需要精确地映射和处理，以确保数据能够正确地传输和存储。
