### 系统对接集成案例分析：聚水潭数据集成到金蝶云星空
在某中大型零售企业的采购退货管理中，原系统存在诸多瓶颈和痛点，如数据漏单、接口调用失败及大量数据处理速度慢等问题。为了提升业务效率，我们决定使用轻易云数据集成平台，将聚水潭的数据无缝对接至金蝶云星空，实现采购退货的自动化处理。
**背景与挑战**
该方案旨在将发生在聚水潭中的采购退货行为，实时传输并写入到金蝶云星空的相应模块，即从“/open/purchaseout/query”接口抓取聚水潭的数据，再通过“batchSave” API批量写入到金蝶系统。这一过程需要解决如下几个关键技术问题：
1. **如何确保集成聚水潭数据不漏单**：
聚水潭提供了标准API来获取相关业务数据，但实际操作过程中往往会遇到网络波动、请求超时或其他突发情况导致的数据丢失。我们采用定时任务配合重试机制，对每次抓取结果进行日志记录和状态监控。
2. **分页与限流处理机制**：
由于该系统涉及大量历史订单，需要考虑API本身的分页功能以及限流策略，以确保大规模数据能够高效、安全地拉取，同时避免因频繁访问触发服务器防护机制。
3. **格式差异与映射转换**：
聚水潭和金蝶两套系统间存在着显著的数据格式差异，比如字段命名规范、日期时间戳格式及嵌套层级结构等。为此，我们设计了一套灵活、高效的映射转换规则，通过脚本化配置实现自动适配，并支持自定义字段填充值。
4. **异常处理与错误重试机制**：
在向目标系统（金蝶云）提交批量更新请求过程中，可能因为服务过载或者短暂性故障而导致部分请求失败。在这种情况下，制定合理的错误捕获和重试机制不仅能尽快恢复正常业务，还能保障数据的一致性和完整性。
5. **实时监控与日志记录**:
数据传输过程中的实时监控可以让整个流程一目了然，包括成功率、错误原因定位，以及性能瓶颈识别。结合轻易云平台自身提供的全生命周期管理工具，我们得以针对每个环节准确把控，从而大幅提升整体运作效率。
综上所述，本篇将详细解析如何借助上述技术手段，有效实现从聚水潭到金蝶云星空之间的数据精准对接，为您的应用场景提供有力参考依据
### 调用聚水潭接口/open/purchaseout/query获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用聚水潭接口`/open/purchaseout/query`，并对获取的数据进行初步加工。
#### 接口概述
聚水潭的`/open/purchaseout/query`接口用于查询采购退货单信息。该接口采用POST方法，支持分页查询，并且可以根据修改时间、订单状态等条件进行过滤。以下是该接口的元数据配置：
```json
{
"api": "/open/purchaseout/query",
"effect": "QUERY",
"method": "POST",
"number": "io_id",
"id": "io_id",
"name": "io_id",
"idCheck": true,
"request": [
{
"field": "page_index",
"label": "第几页",
"type": "string",
"describe": "第几页，从第一页开始，默认1",
"value": "1"
},
{
"field": "page_size",
"label": "每页多少条",
"type": "string",
"describe": "每页多少条，默认30，最大50",
"value": "30"
},
{
"field": "modified_begin",
"label": "修改起始时间",
"type": "datetime",
"describe": "修改起始时间，和结束时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空",
"value": "{{HOURE_AGO_1|datetime}}"
},
{
"field": "modified_end",
"label": "修改结束时间",
"type":"datetime",
“describe”: “修改结束时间，和起始时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空”,
“value”: “{{CURRENT_TIME|datetime}}”
},
{
“field”: “so_ids”,
“label”: “指定线上订单号”,
“type”: “string”,
“describe”: “指定线上订单号，和时间段不能同时为空”
},
{
“field”: “status”,
“label”: “单据状态”,
“type”: “string”,
“describe”: “单据状态，Confirmed=生效，WaitConfirm待审核，Creating=草拟，Archive=归档，Cancelled=作废”,
”value”: ”Confirmed”
},
{
”field”: ”io_ids”,
”label”: ”采购退货单号列表”,
”type”: ”string”,
”describe”：”最大30”
}
],
”buildModel”：true
}
```
#### 请求参数详解
1. **page_index**：分页查询的页码，从第一页开始。默认值为1。
2. **page_size**：每页返回的数据条数。默认值为30条，但最大不超过50条。
3. **modified_begin** 和 **modified_end**：用于指定查询的时间范围。这两个参数必须同时存在，并且时间间隔不能超过七天。
4. **so_ids**：指定线上订单号。如果提供了此参数，则可以精确查询特定订单的信息。
5. **status**：单据状态，可以是Confirmed（生效）、WaitConfirm（待审核）、Creating（草拟）、Archive（归档）或Cancelled（作废）。默认值为Confirmed。
6. **io_ids**：采购退货单号列表，用于批量查询特定的采购退货单。
#### 数据请求与清洗
在调用该接口时，我们需要构建一个符合上述参数要求的请求体。例如，如果我们希望查询过去一小时内所有已生效的采购退货单，可以构建如下请求体：
```json
{
”page_index“: ”1“，
”page_size“: ”30“，
”modified_begin“: "{{HOURE_AGO_1|datetime}}”，
”modified_end“: "{{CURRENT_TIME|datetime}}”，
”status“: ”Confirmed“
}
```
通过轻易云数据集成平台，我们可以使用预定义变量如`{{HOURE_AGO_1|datetime}}`和`{{CURRENT_TIME|datetime}}`来动态生成时间戳。这些变量会在实际请求时被替换为相应的日期和时间值。
#### 数据转换与写入
获取到原始数据后，需要对其进行清洗和转换，以便后续写入目标系统。在这个过程中，可以利用轻易云平台提供的数据处理工具，如字段映射、格式转换等功能。例如，将聚水潭返回的数据字段映射到金蝶系统所需的字段格式。
假设聚水潭返回的数据包含如下字段：
```json
[
{
”io_id“: ”12345“，
”order_date“: ”2023-10-01T12:00:00Z“，
...
}
]
```
我们需要将其转换为金蝶系统所需的格式，例如：
```json
[
{
”purchase_return_id“: ”12345“，
”return_date“: ”2023-10-01T12:00:00Z“，
...
}
]
```
通过配置轻易云平台中的字段映射规则，可以自动完成这一转换过程。
#### 小结
调用聚水潭接口`/open/purchaseout/query`并对数据进行初步加工，是实现数据集成的重要步骤。通过合理配置请求参数和利用轻易云平台的数据处理工具，可以高效地获取并清洗所需数据，为后续的数据写入和业务处理打下坚实基础。
### 数据转换与写入金蝶云星空API接口的技术实现
在数据集成生命周期的第二步，我们需要将源平台的数据进行ETL转换，并将其转为目标平台金蝶云星空API接口所能够接收的格式，最终写入目标平台。以下是一个详细的技术案例，展示如何通过轻易云数据集成平台完成这一过程。
#### API接口配置与调用
我们使用的API接口是`batchSave`，其主要功能是批量保存数据。该接口采用POST方法提交请求，并且需要进行ID校验。以下是元数据配置的详细说明：
```json
{
"api": "batchSave",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{
"field": "FID",
"label": "单据主键",
"type": "string",
"value": "_findCollection find FID from c294d77a-564e-3458-bbf4-4b715774b12b where FBillNo={so_id}"
},
{
"field": "F_QST_INNO",
"label": "退料单号",
"type": "string",
"value": "{io_id}"
},
{
"field": "FUPLOAD",
"label": "上传标志",
"type": "string",
"value": "true"
}
],
...
}
```
#### 配置详解
1. **单据主键（FID）**：
- 类型：字符串
- 值：通过SQL查询从数据库中获取`FID`，其中`{so_id}`为动态参数，通过前一步的数据处理获取。
- 用法：用于唯一标识单据。
2. **退料单号（F_QST_INNO）**：
- 类型：字符串
- 值：直接从源数据中获取`{io_id}`，表示退料单号。
3. **上传标志（FUPLOAD）**：
- 类型：字符串
- 值：固定为`true`，表示该数据需要上传。
#### 其他请求参数
```json
"otherRequest": [
{
...
...
}
]
```
1. **业务对象表单Id（FormId）**：
- 类型：字符串
- 描述：必须填写金蝶的表单ID，如：PUR_PurchaseOrder。
- 值：固定为`PUR_MRB`，表示采购退料表单。
2. **执行的操作（Operation）**：
- 类型：字符串
- 描述：执行的操作。
- 值：固定为`batchSave`，表示批量保存操作。
3. **提交并审核（IsAutoSubmitAndAudit）**：
- 类型：布尔型
- 描述：是否提交并审核。
- 值：固定为`false`，表示不自动提交和审核。
4. **验证基础资料（IsVerifyBaseDataField）**：
- 类型：布尔型
- 描述：是否验证所有基础资料有效性。
- 值：固定为`false`，表示不验证基础资料。
5. **系统模块（SubSystemId）**：
- 类型：字符串
- 描述：默认仓库模块。
- 值：固定为`21`，表示仓库模块。
6. **忽略网控（IsUserModelInit）**：
- 类型：布尔型
- 描述：是否忽略网控。
- 值：固定为`true`，表示忽略网控。
#### 数据转换与写入流程
1. **数据请求与清洗**：
在第一阶段，我们已经从聚水潭平台获取了采购退货的数据，并进行了必要的数据清洗和预处理。这些数据包括但不限于采购退货单号、商品信息、数量等。
2. **数据转换**：
根据金蝶云星空API接口要求，将清洗后的数据进行格式转换。例如，将聚水潭的采购退货单号映射到金蝶云星空的退料单号字段。同时，通过SQL查询获取相应的单据主键FID，以确保数据的一致性和完整性。
3. **数据写入**：
使用配置好的元数据，通过轻易云平台调用金蝶云星空API接口，将转换后的数据批量写入目标平台。具体操作如下：
```python
import requests
url = 'https://api.kingdee.com/batchSave'
headers = {'Content-Type': 'application/json'}
data = {
'FormId': 'PUR_MRB',
'Operation': 'batchSave',
'IsAutoSubmitAndAudit': False,
'IsVerifyBaseDataField': False,
'SubSystemId': '21',
'IsUserModelInit': True,
'Model': [
{
'FID': '_findCollection find FID from c294d77a-564e-3458-bbf4-4b715774b12b where FBillNo={so_id}',
'F_QST_INNO': '{io_id}',
'FUPLOAD': True,
}
# 可以添加更多记录
]
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
```
通过上述步骤，我们成功地将源平台的数据转换并写入到金蝶云星空系统中，实现了不同系统间的数据无缝对接。这一过程不仅提升了业务透明度和效率，还确保了数据的一致性和准确性。
