### xsth-2金蝶销售退货查询 数据测试： 金蝶云星空到轻易云数据集成案例分享
在这一案例中，我们成功实现了从金蝶云星空系统向轻易云集成平台的无缝数据对接。该项目命名为“xsth-2金蝶销售退货查询”，其核心任务是通过executeBillQuery API接口，从金蝶云星空获取销售退货数据，并将这些数据精准、高效地写入到轻易云集成平台。
#### 挑战与解决方案
##### 数据高吞吐量处理
由于销售退货业务日均产生大量的数据，确保快速、可靠地将这些信息传输至目标系统成为了首要挑战。利用轻易云平台的高吞吐量能力，我们设计了一套批量上传策略，使得数据能够及时被采集和处理。这极大提升了整体业务流程的响应速度和效率。
##### 分页与限流机制
在调用executeBillQuery接口时，为了解决分页和限流问题，我们采用自定义逻辑对请求进行分段管理。同时，通过设置合理的数据抓取频率，保障系统稳定运行，避免因过多请求导致接口拥堵或宕机。
##### 数据转换及质量监控
面对源端（即金蝶云星空）和目的端（轻易云）的数据格式差异，自定义转换逻辑被应用于整个过程中，以符合特定业务需求。此外，通过启用数据质量监控功能，实时检测并报告任何可能出现的数据异常，对潜在问题进行提前干预和修正。
#### 实时监控与告警
为了确保整个集成过程中的各个环节处于受控状态，我们启用了集中监控和告警功能。这不仅有助于跟踪每个API调用及其响应时间，还能立即报告网络延迟或失败情况，以便快速采取相应措施。这一机制有效提高了整体操作的透明度及可靠性。
以上技术实施使得复杂繁杂的数据交互变得简单而高效，同时保证了信息完整性和一致性。在下文中，将详细探讨具体实施步骤以及经验总结。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成生命周期的第一步中，调用源系统的API接口是关键环节。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口，获取并加工销售退货数据。
#### API接口配置
首先，我们需要配置调用金蝶云星空的API接口。根据提供的元数据配置，我们使用`POST`方法调用`executeBillQuery`接口，并传递必要的请求参数。
```json
{
"api": "executeBillQuery",
"effect": "QUERY",
"method": "POST",
"number": "FBillNo",
"id": "FEntity_FENTRYID",
"idCheck": true,
"formatResponse": [
{
"old": "FDate",
"new": "FDate_new",
"format": "date"
}
],
"request": [
{"field":"FBillNo","label":"FBillNo","type":"string","describe":"111","value":"FBillNo"},
{"field":"FDocumentStatus","label":"FDocumentStatus","type":"string","describe":"111","value":"FDocumentStatus"},
{"field":"FEntity_FENTRYID","label":"FEntity_FENTRYID","type":"string","value":"FEntity_FENTRYID"},
{"field":"FDate","label":"FDate","type":"string","describe":"111","value":"FDate"},
{"field":"FRealQty","label":"FRealQty","type":"string","describe":"111","value":"FRealQty"},
{"field":"FAmount","label":"FAmount","type":"string","describe":"111","value":"FAmount"}
],
"otherRequest": [
{"field":"Limit","label":"Limit","type":"string","describe":"金蝶的查询分页参数","value":"2000"},
{"field":"StartRow","label":"StartRow","type":"string","describe":"金蝶的查询分页参数","value":"{PAGINATION_START_ROW}"},
{"field":"TopRowCount","label":"TopRowCount","type":"int"},
{"field":"FilterString",
"label": "FilterString",
"type": "string",
"describe": "示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>=",
"value": "FDate>='{{LAST_SYNC_TIME|dateTime}}' and FBillNo NOT LIKE '%XSTHD%'"
},
{"field": "FieldKeys",
"label": "FieldKeys",
"type": "array",
"describe": "金蝶分录主键ID格式：FPOOrderEntry_FEntryId,其它格式 FPurchaseOrgId.FNumber",
"value": "{MAIN_REQUEST}"
},
{"field": "FormId",
"label": "FormId",
"type": "string",
"describe": "",
"value": ""
}
],
autoFillResponse: true
}
```
#### 请求参数详解
1. **基本请求字段**：
- `FBillNo`: 单据编号
- `FDocumentStatus`: 单据状态
- `FEntity_FENTRYID`: 分录主键ID
- `FDate`: 单据日期
- `FRealQty`: 实际数量
- `FAmount`: 金额
2. **其他请求字段**：
- `Limit`: 分页参数，限制每次查询返回的数据量。
- `StartRow`: 分页起始行。
- `TopRowCount`: 查询结果的最大行数。
- `FilterString`: 查询过滤条件，例如过滤掉特定单据编号或日期范围内的数据。
- `FieldKeys`: 查询字段列表，用于指定需要返回的数据字段。
- `FormId`: 表单ID，用于指定查询的表单类型，这里为`SAL_RETURNSTOCK`（销售退货）。
#### 数据处理与格式化
在获取到原始数据后，需要对数据进行处理和格式化。例如，将日期字段`FDate`转换为新的格式，并重命名为`FDate_new`：
```json
"formatResponse":[
{
"old": "FDate",
"new": "FDate_new",
"format": "date"
}
]
```
#### 自动填充响应
配置中的`autoFillResponse: true`表示系统会自动将响应结果填充到相应的数据结构中，简化了后续的数据处理工作。
#### 实际应用案例
假设我们需要查询从上次同步时间开始，所有未包含特定前缀（如“XSTHD”）的销售退货单据，并且每次查询最多返回2000条记录。我们可以构建如下请求：
```json
{
api: 'executeBillQuery',
method: 'POST',
data: {
FormId: 'SAL_RETURNSTOCK',
FieldKeys: ['FBillNo', 'FDocumentStatus', 'FEntity_FENTRYID', 'FDate', 'FRealQty', 'FAmount'],
FilterString: `FDate>='${LAST_SYNC_TIME}' and FBillNo NOT LIKE '%XSTHD%'`,
Limit: '2000',
StartRow: PAGINATION_START_ROW,
}
}
```
通过上述配置和请求，我们能够高效地从金蝶云星空获取所需的数据，并进行必要的加工处理。这一步骤是整个数据集成生命周期中的关键环节，为后续的数据转换与写入奠定了基础。
### 数据集成生命周期第二步：ETL转换与数据写入
在轻易云数据集成平台的生命周期中，ETL（Extract, Transform, Load）过程是至关重要的一环。本文将深入探讨如何将已经集成的源平台数据进行ETL转换，并转为目标平台轻易云集成平台API接口所能够接收的格式，最终写入目标平台。
#### 数据请求与清洗
在数据请求与清洗阶段，我们已经从源平台获取了需要的数据，并进行了初步的清洗和过滤。这些数据现在需要进行进一步的转换，以符合目标平台的要求。我们将重点关注如何使用轻易云提供的API接口来完成这一任务。
#### 数据转换
首先，我们需要根据目标平台的需求，对源数据进行格式转换。假设我们从金蝶系统获取了一批销售退货数据，这些数据可能包含订单号、退货日期、退货数量等字段。在转换过程中，我们需要确保这些字段符合目标平台API接口的要求。
```json
{
"orderNumber": "123456",
"returnDate": "2023-10-01",
"returnQuantity": 10
}
```
在这个例子中，我们将源数据中的字段名称和格式进行了调整，以匹配目标平台的要求。
#### 配置元数据
为了将转换后的数据写入目标平台，我们需要配置元数据。根据提供的元数据配置：
```json
{
"api": "写入空操作",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true
}
```
这段配置告诉我们以下几点：
1. API接口为“写入空操作”，意味着我们将调用一个特定的API来执行写入操作。
2. `effect`字段为“EXECUTE”，表明这是一个执行操作。
3. `method`字段为“POST”，表示我们将使用HTTP POST方法来提交数据。
4. `idCheck`字段为`true`，意味着在写入之前需要进行ID校验。
#### 调用API接口
接下来，我们通过编程方式调用轻易云集成平台的API接口。以下是一个示例代码片段，展示了如何使用Python来实现这一过程：
```python
import requests
import json
# 定义API URL和Headers
api_url = "https://api.qingyiyun.com/write"
headers = {
'Content-Type': 'application/json'
}
# 构建请求体
data = {
"orderNumber": "123456",
"returnDate": "2023-10-01",
"returnQuantity": 10
}
# 发起POST请求
response = requests.post(api_url, headers=headers, data=json.dumps(data))
# 检查响应状态码
if response.status_code == 200:
print("Data written successfully.")
else:
print(f"Failed to write data. Status code: {response.status_code}")
```
在这个示例中，我们首先定义了API URL和请求头，然后构建了请求体，将其转换为JSON格式，并通过POST方法发送到目标平台。如果响应状态码为200，则表示数据写入成功；否则，将输出错误信息。
#### 实时监控与调试
为了确保整个过程顺利进行，实时监控和调试是必不可少的。轻易云集成平台提供了强大的监控工具，可以实时查看每个环节的数据流动和处理状态。一旦发现问题，可以快速定位并解决，从而保证业务流程的连续性和稳定性。
通过上述步骤，我们完成了从源平台到目标平台的数据ETL转换与写入过程。这不仅提高了数据处理效率，还确保了数据的一致性和准确性。
