轻易云ETL技术：将销售退货单数据转换并写入金蝶云星空
### 金蝶云星空数据集成案例分享：销售退货单-销售退货单TW9.1日
在复杂的企业应用生态环境中，实现系统间的数据无缝对接与高效处理一直是技术人员面临的关键挑战之一。本文将重点介绍一个实际运行的解决方案：通过轻易云数据集成平台，将金蝶云星空系统中的“销售退货单”数据集成至另一套相同系统，并展示如何利用该平台实现高吞吐量的数据写入能力、实时监控任务状态以及定制化的数据转换逻辑。
#### 背景和需求分析
在本次案例中，我们需要将一种名为“销售退货单TW9.1日”的业务数据从一个金蝶云星空实例迁移到另一个相同类型的实例。这个过程包括从源系统获取数据、处理和转换以符合目标系统结构，并最终批量写入目标系统，以确保两者之间的数据一致性和完整性。
#### 技术方案设计
我们采用轻易云提供的可视化操作界面对整个流程进行配置，以下是几个重要步骤及其技术要点：
1. **API调用（executeBillQuery）**：
- 首先，通过金蝶云星空的`executeBillQuery`接口从源系统抓取“销售退货单”相关数据。为了确保不漏单，我们设定了定时触发机制，周期性地拉取最新生成或更新的数据。
2. **批量写入（batchSave）**：
- 获取到所需数据后，需要通过`batchSave`接口将这些记录写入目标金蝶云星空实例。在这个过程中，为保证高效性能与稳定操作，我们使用了并行分批次提交方式，同时还考虑到分页请求结果及限流问题，避免资源阻塞。
3. **自定义转换逻辑**:
- 数据格式差异往往导致直接复制失败，因此我们配置了自定义映射规则，对字段名称、类型等进行必要调整，使之符合目标表结构要求。同时，这也涉及部分复杂字段计算与组合，例如根据不同条件拼接或拆分某些值域。
4. **集中监控与告警机制**:
- 整个集成过程中借助轻易云的平台功能，对每步执行情况进行实时监控，一旦检测异常自动告警并即时采取措施，如重试机制等，提高整体可靠性。
5. **异常处理及错误重试机制**:
- 特别针对网络抖动、接口超时等常见问题，在具体实施环节设计了一套完善应对策略，包括捕捉具体异常信息、定位故障点，以及适时重新投递未成功条目，最大限度降低
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，第一步是调用源系统接口获取数据，并对其进行初步加工。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口，以获取销售退货单的数据，并进行必要的加工处理。
#### 接口调用配置
首先，我们需要配置调用金蝶云星空接口的元数据。以下是一个典型的元数据配置示例：
```json
{
"api": "executeBillQuery",
"method": "POST",
"number": "FBillNo",
"id": "FEntity_FENTRYID",
"pagination": {
"pageSize": 500
},
"idCheck": true,
"formatResponse": [
{
"old": "FApproveDate",
"new": "FApproveDate_new",
"format": "date"
}
],
"request": [
{"field":"FBillTypeID_FNumber","label":"单据类型","type":"string","describe":"单据类型","value":"FBillTypeID.FNumber"},
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","value":"FBillNo"},
{"field":"FDate","label":"日期","type":"string","describe":"日期","value":"FDate"},
{"field":"FApproveDate","label":"审核时间","type":"string","describe":"日期","value":"FApproveDate"},
{"field":"FSaleOrgId_FNumber","label":"销售组织","type":"string","describe":"组织","value":"FSaleOrgId.FNumber"},
// ...其他字段省略
],
"otherRequest": [
{"field":"Limit","label":"最大行数","type":"string","describe":"金蝶的查询分页参数","value":"{PAGINATION_PAGE_SIZE}"},
{"field":"StartRow","label":"开始行索引","type":"string","describe":"金蝶的查询分页参数","value":"{PAGINATION_START_ROW}"},
{"field":"TopRowCount","label":"返回总行数","type":"int","describe":"金蝶的查询分页参数"},
{"field":"FilterString","label":"过滤条件","type":"string", "describe": "示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>=",
"value": "FDate >='{{LAST_SYNC_TIME|date}}' and FSaleOrgId.FNumber='202'"},
{"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": "SAL_RETURNSTOCK"}
]
}
```
#### 数据请求与清洗
在上述配置中，我们定义了需要从金蝶云星空系统中提取的数据字段，以及如何对这些字段进行初步清洗和转换。例如，通过`formatResponse`字段，我们将原始的审核时间`FApproveDate`转换为新的格式化日期字段`FApproveDate_new`。
##### 请求参数解析
- `api`: 指定要调用的API名称，这里是`executeBillQuery`。
- `method`: HTTP请求方法，通常为POST。
- `number`: 用于标识记录唯一性的字段，这里是单据编号`FBillNo`。
- `id`: 用于标识记录详细信息的字段，这里是分录ID`FEntity_FENTRYID`。
- `pagination`: 分页配置，每次请求500条记录。
- `idCheck`: 是否检查记录唯一性。
- `formatResponse`: 定义响应数据格式化规则，例如将审核时间格式化为新的日期格式。
##### 请求体构建
在构建请求体时，需要根据元数据中的定义填充具体参数：
```json
{
// 示例请求体
{
...
// 填充其他必要参数
...
{
// 分页参数
Limit: metadata.pagination.pageSize,
StartRow: startRowIndex,
TopRowCount: topRowCount,
// 查询条件
FilterString: filterString,
// 查询字段集合
FieldKeys: fieldKeys.join(","),
// 表单ID
FormId: formId
}
}
```
#### 数据转换与写入
在获取到原始数据后，需要对其进行进一步处理和转换，以便写入目标系统。以下是一些常见的数据转换操作：
1. **字段重命名**：根据业务需求，将某些字段重命名。例如，将原始审核时间字段重命名为新的格式化日期字段。
2. **数据类型转换**：将某些字符串类型的数据转换为日期、数字等特定类型，以便后续处理。
3. **过滤无效数据**：根据业务规则，过滤掉不符合条件的数据记录。
#### 实践案例
假设我们需要从金蝶云星空系统中提取所有在特定时间段内审核通过的销售退货单，并将其导入到另一个系统中。以下是具体步骤：
1. **构建请求体**：
- 设置分页参数，如每页500条记录。
- 设置过滤条件，如只提取审核时间在特定范围内的数据。
2. **发送请求**：
- 调用`executeBillQuery`接口，发送构建好的请求体。
3. **处理响应**：
- 对响应数据进行初步清洗和转换，如格式化日期、重命名字段等。
4. **写入目标系统**：
- 将处理后的数据写入目标系统，确保数据的一致性和完整性。
通过以上步骤，我们可以高效地从金蝶云星空系统中提取并加工所需的数据，为后续的数据集成工作打下坚实基础。
### 使用轻易云数据集成平台将销售退货单数据转换并写入金蝶云星空API接口的技术案例
在数据集成过程中，将源平台的数据转换为目标平台可接受的格式是关键步骤之一。本文将详细探讨如何使用轻易云数据集成平台，将销售退货单的数据通过ETL（提取、转换、加载）过程，最终写入金蝶云星空API接口。
#### 数据请求与清洗
首先，我们需要从源平台提取销售退货单的数据，并进行必要的清洗和预处理。这一步骤确保了数据的准确性和一致性，为后续的转换和写入奠定基础。
#### 数据转换与写入
接下来，我们进入数据生命周期的第二步：将已经集成的源平台数据进行ETL转换，转为目标平台金蝶云星空API接口所能够接收的格式，并最终写入目标平台。
##### 配置元数据
根据提供的元数据配置，我们需要设置API请求参数，以便将销售退货单的数据正确地传递给金蝶云星空。以下是关键配置项：
- **API接口**：`batchSave`
- **HTTP方法**：`POST`
- **操作方法**：合并（`merge`）
- **字段映射**：
- `FBillTypeID_FNumber`: 单据类型
- `FBillNo`: 单据编号
- `FDate`: 日期
- `FSaleOrgId_FNumber`: 销售组织
- `FRetcustId_FNumber`: 客户
- `FStockOrgId_FNumber`: 发货组织
##### 请求体结构
请求体主要包含两个部分：头部信息和明细信息。
###### 头部信息
头部信息包括单据类型、日期、销售组织、客户、发货组织等基本信息。以下是部分关键字段及其解析方式：
```json
{
"field": "FBillTypeID",
"label": "单据类型",
"type": "string",
"describe": "单据类型",
"parser": {
"name": "ConvertObjectParser",
"params": "FNumber"
},
"value": "XSTHD01_SYS"
}
```
上述配置将单据类型字段解析为`XSTHD01_SYS`，并通过`ConvertObjectParser`解析器将其转换为目标系统所需格式。
###### 明细信息
明细信息包含物料编码、实发数量、含税单价、仓库等详细记录。以下是部分关键字段及其解析方式：
```json
{
"field": "FMaterialID",
"label": "物料编码",
"type": "string",
"describe": "基础资料",
"parser": {
"name": "ConvertObjectParser",
"params": "FNumber"
},
"value": "{{details.FMaterialId_FNumber}}"
}
```
上述配置将物料编码字段解析为源数据中的`FMaterialId_FNumber`，并通过`ConvertObjectParser`解析器进行转换。
##### 动态计算字段
在某些情况下，需要根据业务逻辑动态计算字段值。例如，折扣额可以根据含税单价和实发数量计算得出：
```json
{
"parent":"FEntity",
"label":"折扣额",
"field":"FDiscount",
"type":"string",
"value":"_function {FTaxPrice}*{FRealQty} - {FAllAmount}"
}
```
上述配置使用函数表达式动态计算折扣额，并将结果传递给目标系统。
##### 提交请求
最后，通过HTTP POST请求，将构建好的JSON请求体提交到金蝶云星空API接口，实现数据的写入：
```json
{
"api":"batchSave",
...
}
```
#### 实践案例
假设我们有一条销售退货单记录，其基本信息如下：
- 单据类型：XSTHD01_SYS
- 单据编号：THD20230901
- 日期：2023-09-01
- 销售组织：1001
- 客户：CUST001
- 发货组织：126
对应的明细信息如下：
- 物料编码：MAT001, 实发数量：10, 含税单价：100, 仓库：CK001, 税率：13%
通过上述元数据配置，我们可以构建出如下JSON请求体：
```json
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
