### 系统对接集成案例分享：金蝶云星空数据集成到管易云
在采购退货场景中，如何高效、准确地将金蝶云星空的数据集成到管易云一直是一个实际业务需求。本文将详细介绍我们通过轻易云数据集成平台实现这一目标的技术方案“采购退货对接-已测试”。本方案重点解决了以下几个关键问题：
1. **如何确保集成金蝶云星空数据不漏单**
我们使用了定时任务机制可靠地抓取金蝶云星空接口数据，通过调用 `executeBillQuery` 接口确保每一份数据都能够实时被读取和处理。同时，针对分页和限流问题，我们设计了一套自动重试机制，最大程度上保证了所有有效数据的完整提取。
2. **大量数据快速写入到管易云**
为了解决大批量数据写入的问题，我们采用并行处理与批量提交相结合的方法。在具体实施中，通过调用管易云的 `gy.erp.stock.other.out.add` 接口实现高效的数据传输，并利用缓存加速提交过程，有效提升了整体性能。
3. **处理金蝶云星空与管易云之间的数据格式差异**
数据格式差异往往是不同系统间对接的一大难点。对此，我们在轻易平台上配置了一套灵活的数据映射规则，对获取到的原始记录进行预处理，以适配目标系统所需格式，从而保障后续操作无缝衔接。
4. **异常处理与错误重试机制**
集成过程中不可避免会出现各种异常情况，为此我们设计了一整套完备的异常捕获和错误重试机制。当遇到网络波动或接口超时时，会立即触发告警并启动自动化复原流程，将失败请求重新排队执行，大幅提高对接稳定性。
这只是整个项目中的一部分亮点内容，在下文中还将深入探讨更多具体技术细节，包括如何进行日志记录以便实时监控，以及特殊环境下的定制化优化策略等方面。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口来获取采购退货数据，并对其进行初步加工。
#### API接口配置
根据元数据配置，我们需要调用金蝶云星空的`executeBillQuery`接口。以下是该接口的主要配置参数：
- **API**: `executeBillQuery`
- **方法**: `POST`
- **表单ID**: `PUR_MRB`
- **请求字段**:
- `FPURMRBENTRY_FEntryID`: 明细信息ID
- `FID`: 实体主键
- `FBillNo`: 单据编号
- `FDocumentStatus`: 单据状态
- `FDate`: 退料日期
- 其他字段详见元数据配置
#### 请求参数构建
在构建请求参数时，需要注意分页和过滤条件的设置。以下是一个示例请求参数：
```json
{
"FormId": "PUR_MRB",
"FieldKeys": [
"FPURMRBENTRY_FEntryID", "FID", "FBillNo", "FDocumentStatus",
"FDate", "FBillTypeID.FNumber", "FTAKEDELIVERYNO",
"FSupplierID.FNumber", "FDESCRIPTION", "FMRTYPE",
// 更多字段...
],
"FilterString": "FApproveDate>='2023-01-01' and FBillTypeID.FNUMBER in('TLD10_SYS','TLD09_SYS')",
"Limit": 100,
"StartRow": 0,
"TopRowCount": true
}
```
#### 数据请求与清洗
在发送请求并接收到响应后，需要对数据进行清洗和初步加工。以下是一个简单的数据清洗示例：
1. **过滤无效数据**：去除单据状态为“草稿”的记录。
2. **格式化日期**：将退料日期格式化为标准日期格式。
3. **计算总金额**：根据实退数量和单价计算总金额。
示例代码如下：
```python
import requests
import json
from datetime import datetime
# 定义请求URL和头部信息
url = 'https://api.kingdee.com/executeBillQuery'
headers = {'Content-Type': 'application/json'}
# 构建请求体
payload = {
"FormId": "PUR_MRB",
"FieldKeys": [
"FPURMRBENTRY_FEntryID", "FID", "FBillNo",
// 更多字段...
],
"FilterString": "FApproveDate>='2023-01-01' and FBillTypeID.FNUMBER in('TLD10_SYS','TLD09_SYS')",
"Limit": 100,
"StartRow": 0,
"TopRowCount": True
}
# 发起POST请求
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
# 数据清洗与加工
cleaned_data = []
for record in data['Result']:
if record['FDocumentStatus'] != '草稿':
record['FDate'] = datetime.strptime(record['FDate'], '%Y-%m-%d').strftime('%Y-%m-%d')
record['TotalAmount'] = float(record['FRMREALQTY']) * float(record['FPrice'])
cleaned_data.append(record)
# 输出清洗后的数据
print(json.dumps(cleaned_data, indent=4, ensure_ascii=False))
```
#### 数据转换与写入
经过清洗的数据可以进一步转换为目标系统所需的格式，并写入目标数据库或系统。在此过程中，可以利用轻易云平台提供的可视化工具，简化复杂的数据转换逻辑。
以上就是通过轻易云数据集成平台调用金蝶云星空接口`executeBillQuery`获取并加工采购退货数据的详细技术案例。通过这种方式，可以高效地实现不同系统间的数据无缝对接，为业务决策提供可靠的数据支持。
### 数据请求与清洗
在数据集成的生命周期中，第二步是将已经集成的源平台数据进行ETL转换，并转为目标平台所能够接收的格式。本文将重点讨论如何将采购退货的数据转换为管易云API接口所能接收的格式，并最终写入目标平台。
### API接口配置
为了实现这一目标，我们需要配置管易云API接口。以下是元数据配置的一部分，展示了如何将源平台的数据字段映射到管易云API接口所需的字段：
```json
{
"api": "gy.erp.stock.other.out.add",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"operation": {
"method": "merge",
"field": "FBillNo,F_Shipping_address",
"bodyName": "items",
"bodySum": ["FRMREALQTY"],
"header": ["FBillNo", "FSTOCKID_FNumber", "F_recipient", "F_Receiving_phone_number", "F_Shipping_address", "F_economize", "F_market", "F_distinguish"],
"body": ["FMATERIALID_FNumber", "FRMREALQTY", "FDate"]
},
...
}
```
### 请求参数映射
在请求参数映射中，我们需要确保每个字段都正确地映射到管易云API所需的字段。例如：
- `warehouse_code` 映射到 `FSTOCKID_FNumber`
- `note` 映射到 `金蝶采购退货-{FBillNo}`
- `wms_bizcode` 映射到 `{FBillNo}-{random}`
- `type` 固定值为 `001`
- `receiver_name` 映射到 `F_recipient`
- `receiver_mobile` 映射到 `F_Receiving_phone_number`
- `receiver_address` 映射到 `F_Shipping_address`
- `receiver_province` 映射到 `F_economize`
- `receiver_city` 映射到 `F_market`
- `receiver_district` 映射到 `F_distinguish`
以下是请求参数的具体配置：
```json
"request": [
{"field":"warehouse_code","label":"仓库代码","type":"string","describe":"仓库代码","value":"{FSTOCKID_FNumber}"},
{"field":"note","label":"备注","type":"string","describe":"备注","value":"金蝶采购退货-{FBillNo}"},
{"field":"wms_bizcode","label":"第三方系统单号","type":"string","value":"{FBillNo}-{random}"},
{"field":"type","label":"出库类型代码","type":"string","describe":"出库类型代码","value":"001"},
{"field":"receiver_name","label":"收货人","type":"string","value":"{F_recipient}"},
{"field":"receiver_mobile","label":"收货人手机","type":"string","value":"{F_Receiving_phone_number}"},
{"field":"receiver_address","label":"收货人地址","type":"string","value":"{F_Shipping_address}"},
{"field":"receiver_province","label":"发货人省份","type":"string","value":"{F_economize}"},
{"field":"receiver_city","label":"发货人市","type":"string","value":"{F_market}"},
{"field":"receiver_district","label":"发货人区","type":"string","value":"{F_distinguish}"}
]
```
### 商品列表映射
商品列表是一个数组，需要特别处理。每个商品项包含以下字段：
- 商品代码 (`item_code`) 和规格代码 (`sku_code`) 都映射到 `{items.FMATERIALID_FNumber}`
- 数量 (`qty`) 映射到 `{items.FRMREALQTY}`
- 入库日期 (`stockDate`) 映射到 `{items.FDate}`
以下是商品列表的具体配置：
```json
"details": [
{
"field": "item_code",
"label": "商品代码",
"type": "string",
"describe": "...",
"value": "{{items.FMATERIALID_FNumber}}"
},
{
"field": "sku_code",
"label": "...",
...
...
}
```
### 数据转换与写入
在完成所有字段映射后，数据就可以通过ETL过程进行转换，并最终写入管易云。通过POST请求，将整理好的数据发送至管易云API接口，实现数据的无缝对接。
### 技术要点总结
1. **字段映射**：确保源平台与目标平台字段一一对应。
2. **数组处理**：特殊处理商品列表等数组类型的数据。
3. **固定值设置**：如出库类型代码等，直接设定固定值。
4. **动态生成**：如第三方系统单号，通过模板生成动态值。
通过以上步骤，可以高效地将采购退货的数据从源平台转换并写入目标平台，实现系统间的数据无缝对接。
