### 案例分享：金蝶云星空数据集成到金蝶云星空 - 销售退货单-销售退货单-分销组【浩悦&鼎骏电子】OK_copy
在本案例中，我们将深入探讨如何利用轻易云数据集成平台将一个业务关键的销售退货数据从一个金蝶云星空系统有效地集成到另一个金蝶云星空系统。该方案名为“销售退货单-销售退货单-分销组【浩悦&鼎骏电子】OK_copy”，通过实施这一方案，我们需要解决大规模数据快速写入、接口调用及优化、异常处理等技术挑战。
首先，通过使用executeBillQuery API接口，从源系统精确抓取所有相关的销售退货单据。这一步骤不仅要求对API本身有深刻理解，还需具备分页和限流机制，以确保高效的数据提取，防止因请求过于频繁而触发限流警告或产生性能瓶颈。特别是在处理大量交易记录时，必须保障每一条数据完整无误地被获取并传输。
接下来，将抓取的数据转换并依据目标系统所需格式进行重构，这里可以充分利用自定义的数据转换逻辑功能。这种方法可以灵活应对不同业务需求和复杂的数据结构。同时，为了保证整个过程透明度高且可追溯，我们依赖于提供的集中监控和告警功能，实时跟踪每个任务执行状态，并在出现问题时及时通知相关人员采取纠正措施。
最后，通过batchSave API接口，将整理好的数据批量写入目标金蝶云星空系统内。在这个环节中，高吞吐量的数据写入能力显得尤为重要，能够显著提升整体效率。此外，还应实现健全的错误重试机制，以便在网络波动或其他非预期故障引起操作失败后自动重新尝试。
整个解决方案不但确保了跨系统间的大规模、高效、安全稳定的数据迁移，同时借助轻易云强大的可视化工具，使得操作管理更加简便直观，为用户带来极大的便利……
### 调用金蝶云星空接口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": "FBillNo= 'XSTHD6518251' or\nFBillNo= 'XSTHD6518221' or\nFBillNo= 'XSTHD6511489' or\nFBillNo= 'XSTHD6511369'"
},
{"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
}
]
}
```
#### 数据请求与清洗
在进行数据请求时，我们需要构建一个包含所有必要字段和过滤条件的请求体。例如：
```json
{
"FormId": "<业务对象表单Id>",
// 示例：SAL_RETURNSTOCK
// 请求参数
// ...
}
```
通过上述配置，轻易云平台会自动生成并发送HTTP POST请求到金蝶云星空API端点。响应结果将会被接收并存储，以便后续处理。
#### 数据转换与格式化
收到响应后，我们需要对数据进行清洗和转换。根据元数据配置中的`formatResponse`部分，我们可以对特定字段进行格式化。例如，将审核时间字段`FApproveDate`转换为新的字段`FApproveDate_new`，并将其格式化为日期类型。
```json
{
// 原始响应数据
// ...
// 格式化后的响应数据
{
// ...
FApproveDate_new: formatAsDate(FApproveDate),
// ...
}
}
```
#### 分页处理
为了处理大规模的数据，分页是必不可少的。在元数据配置中，我们设置了分页参数，如每页大小（pageSize）和起始行索引（StartRow）。通过这些参数，可以逐页获取完整的数据集。
```json
{
// 示例分页请求体
{
FormId: "<业务对象表单Id>",
Limit: pageSize,
StartRow: startIndex,
FilterString: "<过滤条件>"
}
}
```
每次请求后，更新起始行索引以获取下一页的数据，直到所有数据都被成功获取。
#### 实践案例
假设我们需要获取特定销售退货单的数据，并且这些退货单编号分别为`XSTHD6518251`, `XSTHD6518221`, `XSTHD6511489`, 和 `XSTHD6511369`。我们可以设置如下过滤条件：
```json
{
FilterString: `FBillNo= 'XSTHD6518251' or\nFBillNo= 'XSTHD6518221' or\nFBillNo= 'XSTHD6511489' or\nFBillNo= 'XSTHD6511369'`
}
```
通过这种方式，可以精准地从源系统中提取所需的数据，并确保其准确性和完整性。
综上所述，通过轻易云平台调用金蝶云星空接口，我们能够高效地获取并加工销售退货单的数据。这一过程不仅简化了系统集成的复杂性，还提升了数据处理的透明度和效率。
### 数据集成生命周期中的ETL转换：将数据写入金蝶云星空API接口
在数据集成生命周期的第二步，我们需要将已经集成的源平台数据进行ETL转换，转为目标平台金蝶云星空API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨这一过程中的技术细节和实现方法。
#### API接口配置
我们使用金蝶云星空的`batchSave` API接口来实现数据写入。该接口采用POST方法，支持批量保存操作。以下是具体的元数据配置：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"method": "merge",
"field": "FBillTypeID_FNumber,FBillNo,FDate,FSaleOrgId_FNumber,FCustomerID_FNumber,FStockOrgId_FNumber",
"bodyName": "details",
"header": ["FBillTypeID_FNumber", "FBillNo", "FDate", "FSaleOrgId_FNumber", "FRetcustId_FNumber", "FStockOrgId_FNumber", "FRetcustId_FDJZDYSWDYZZ"],
"body": ["FMaterialId_FNumber", "FRealQty", "FTaxPrice", "FStockID_FNumber", "FAllAmount", "FDiscount", "FRetcustId_FDJZDYSWDYZZ"]
},
...
}
```
#### 数据请求与清洗
在数据请求与清洗阶段，我们需要将源平台的数据进行标准化处理，以确保其符合目标平台的要求。例如，将日期字段格式化、组织编码转换等。以下是部分字段的处理逻辑：
- **日期字段 `FDate`**：我们需要根据特定条件对日期进行处理：
```sql
CASE WHEN DAY(STR_TO_DATE('{FDate}', '%Y-%m-%d')) BETWEEN 26 AND DAY(LAST_DAY(STR_TO_DATE('{FDate}', '%Y-%m-%d'))) THEN DATE_FORMAT(DATE_ADD(STR_TO_DATE('{FDate}', '%Y-%m-%d'), INTERVAL 1 MONTH), '%Y-%m-01') ELSE STR_TO_DATE('{FDate}', '%Y-%m-%d') end
```
- **销售组织 `FSaleOrgId`**：通过名称转换为编码：
```json
{"name":"ConvertObjectParser","params":"FName"}
```
#### 数据转换与写入
在数据转换阶段，我们需要将清洗后的数据映射到目标平台的数据结构中，并通过API接口进行写入。以下是关键字段的映射和处理：
- **单据类型 `FBillTypeID`**：
```json
{"field":"FBillTypeID","label":"单据类型","type":"string","describe":"单据类型","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"XSTHD01_SYS"}
```
- **客户 `FRetcustId`**：
```json
{"field":"FRetcustId","label":"客户","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{FRetcustId_FNumber}","mapping":{"target":"6368c0eac6075446d927c5dd","direction":"positive"},"mappingDirection":"positive"}
```
- **仓库 `FStockID`**：根据客户名称选择不同的仓库编码：
```sql
case when '{FRetcustId_FNumber}' like '%京东%' then 'CK001' when '{{FCustomerID.FName}}' like '%唯品会%' then 'CK002' else 'CK001' end
```
#### 请求参数配置
在向金蝶云星空API发送请求时，需要配置以下参数：
- **业务对象表单ID `FormId`**：
```json
{"field":"FormId","label":"业务对象表单Id","type":"string","describe":"必须填写金蝶的表单ID如:PUR_PurchaseOrder","value":"SAL_RETURNSTOCK"}
```
- **执行操作 `Operation`**：
```json
{"field":"Operation","label":"执行的操作","type":"string","value":"Save"}
```
- **是否提交并审核 `IsAutoSubmitAndAudit`**：
```json
{"field":"IsAutoSubmitAndAudit","label":"提交并审核","type":"bool","value":"false"}
```
通过上述配置，我们可以确保源平台的数据经过ETL转换后，能够准确地写入到金蝶云星空系统中。这不仅提高了数据处理效率，还保证了数据的一致性和准确性。
以上就是利用轻易云数据集成平台，将源平台数据经过ETL转换后写入金蝶云星空API接口的详细技术方案。希望这些技术细节能为您的系统集成工作提供有价值的参考。
