### 吉客云数据集成至金蝶云星空的技术案例分享
在企业的数据管理中，系统间的数据集成是确保信息流畅传递和业务高效运作的关键环节。本篇文章将聚焦一个具体的技术案例：如何利用轻易云数据集成平台，将吉客云的盘盈单-其他入库-正数数据成功对接并写入到金蝶云星空。这一过程将详细讲解各个环节中的技术实现、挑战应对以及优化方案。
我们首先要解决的问题是如何通过吉客云API接口`erp.storage.goodsdocin.v2`可靠获取所需数据，并实现大量数据快速且准确地写入到金蝶云星空。为了保证整个流程顺畅无漏单，关键在于处理好分页和限流问题及对接过程中可能出现的异常。
### 接口调用与分页处理
从吉客云获取大批量盘盈单数据是此次集成任务中的首要步骤。借助轻易云平台提供的高吞吐量支持，我们可以定时抓取接口`erp.storage.goodsdocin.v2`的数据。在实际操作中，通过自定义逻辑设置，实现了针对不同时间段内新增或更新记录进行分页提取，这不仅提高了响应效率，同时也避免了超出接口调用频率限制的问题。
### 数据转换与映射
由于吉客云和金蝶云星空之间的数据格式存在差异，自定义数据转换逻辑显得尤为重要。我们利用轻易**可视化**工具设计了一套灵活的数据映射方案，以适配特定业务需求。此外，通过集中管理监控工具，可以实时追踪每一步骤执行状态，及时发现并处理潜在异常，确保整体运行稳定性。
### 批量写入与重试机制
为了保证大量采集的数据能够准确无误地批量写入到金蝶【API batchSave】中，对于每次提交结果进行了严格验证。当检测到任何错误或失败情况时，即刻启动重试机制，保障所有有效记录最终都能得到正确存储。同时，还设立告警系统，在发生严重故障时第一时间通知相关人员介入，提高响应速度和修复效率。
这一系列措施从根本上提升了整体系统整合能力，使得企业能够在最大程度上保持信息一致性与业务连续性。在接下来的章节中，我们将继续深入解析此项目中的具体实施细节，包括异常处理策略、性能优化窍门等内容。
### 调用吉客云接口获取并加工数据的技术实现
在轻易云数据集成平台的生命周期管理中，调用源系统接口是关键的第一步。本文将深入探讨如何通过调用吉客云接口`erp.storage.goodsdocin.v2`获取并加工数据，以实现盘盈单-其他入库-正数的集成方案。
#### 接口调用配置
首先，我们需要配置API接口调用的元数据。以下是具体的配置细节：
```json
{
"api": "erp.storage.goodsdocin.v2",
"effect": "QUERY",
"method": "POST",
"number": "goodsdocNo",
"id": "goodsdocNo",
"idCheck": true,
"request": [
{"field":"pageIndex","label":"分页页码","type":"string"},
{"field":"pageSize","label":"分页页数","type":"string","value":"50"},
{"field":"goodsDocNo","label":"入库单号","type":"string"},
{"field":"startDate","label":"创建时间的起始时间","type":"string","value":"{{LAST_SYNC_TIME|datetime}}"},
{"field":"endDate","label":"创建时间的结束时间","type":"string","value":"{{CURRENT_TIME|datetime}}"},
{"field":"inouttype","label":"入库类型","type":"string","describe":"入库类型(100-期初库存 101-采购入库 102-调拨入库 103-盘盈入库 104-其他入库 105-销售退货 106-完工入库 107-组装拆卸入库 108-翻新入库 109-报废入库 110-残次品入库111-成本调整 112-即采即入113-退料入库114-调拨退回115-维修返厂返还)","value":"103"},
{"field":"warehouseId","label":"仓库ID","type":"string"},
{"field":"warehouseCode","label":"仓库编号","type":"string"},
{"field":"vendId","label":"供应商ID(往来单位)","type":"string"},
{"field":"vendCode","label":"供应商编号(往来单位)","type":"string"},
{"field":"billNo","label":"上游单据号(关联单号)","type":"string"},
{"field":"userName","label":"创建人名称","type":"string"},
{"field":"gmtModifiedStart","label":"主表更新时间起始","type":"string"},
{"field":"gmtModifiedEnd","label":"主表更新时间截至","type":"string"},
{"field": "selelctFields", "label": "返回参数", "type": "string", "value": "goodsdocNo,inOutDate,gmtCreate,inouttype,vendCustomerCode,warehouseCode,warehouseName,inOutReason,redStatus,financeBillStatus,goodsDocDetailList.goodsNo,goodsDocDetailList.quantity,goodsDocDetailList"}
],
"autoFillResponse": true,
"beatFlat": ["goodsDocDetailList"],
"condition_bk": [[{"field": "goodsDocDetailList.quantity", "logic": "gt", "value": "0"}]],
"omissionRemedy": {
"crontab": "9 2 * * *",
"takeOverRequest":[{"field": "startDate", "value": "_function FROM_UNIXTIME( unix_timestamp() -259200 , '%Y-%m-%d %H:%i:%s' )", "type": "string", "label": "接管字段"}]
},
"condition":[[{"field": "goodsDocDetailList.quantity", "logic": "gt", "value": "0"}]]
}
```
#### 请求参数详解
1. **分页参数**：
- `pageIndex`: 分页页码，字符串类型。
- `pageSize`: 分页页数，默认值为50。
2. **时间参数**：
- `startDate`: 创建时间的起始时间，使用模板变量`{{LAST_SYNC_TIME|datetime}}`。
- `endDate`: 创建时间的结束时间，使用模板变量`{{CURRENT_TIME|datetime}}`。
3. **业务参数**：
- `inouttype`: 入库类型，固定值为103（盘盈入库）。
- `warehouseId`, `warehouseCode`, `vendId`, `vendCode`, `billNo`, `userName`: 可选字段，用于进一步筛选数据。
4. **返回参数**：
- 使用`selelctFields`字段指定需要返回的数据字段，包括主表和子表信息，如`goodsdocNo`, `inOutDate`, `gmtCreate`, `inouttype`, 等等。
#### 数据过滤与条件设置
为了确保获取的数据符合业务需求，我们设置了两个条件过滤器：
1. **主条件过滤器**：仅保留数量大于0的数据。
```json
{
“condition”: [[{"field”: “goodsDocDetailList.quantity”, “logic”: “gt”, “value”: “0”}]]
}
```
2. **备用条件过滤器**：同样仅保留数量大于0的数据，用于备用情况。
```json
{
“condition_bk”: [[{"field”: “goodsDocDetailList.quantity”, “logic”: “gt”, “value”: “0”}]]
}
```
#### 异常处理与补偿机制
为了应对可能出现的数据遗漏问题，我们配置了定时任务（crontab）和接管字段：
1. **定时任务**：每天凌晨2:09执行一次补偿任务。
```json
{
“crontab”: “9 2 * * *”
}
```
2. **接管字段**：在补偿任务中，将起始时间设置为当前时间前72小时。
```json
{
“takeOverRequest”: [{"field”: “startDate”, “value”: “_function FROM_UNIXTIME( unix_timestamp() -259200 , ‘%Y-%m-%d %H:%i:%s’ )”}]
}
```
#### 数据请求与清洗
在完成上述配置后，通过POST方法向吉客云API发送请求，并根据返回的数据进行清洗和加工。由于我们启用了自动填充响应（autoFillResponse），平台会自动处理返回的数据结构，并将子表数据平铺到主表中。
通过这种方式，我们能够高效地从吉客云获取所需的盘盈单数据，并确保数据的准确性和完整性，为后续的数据转换与写入奠定坚实基础。
### 使用轻易云数据集成平台将吉客云盘盈单数据转换并写入金蝶云星空API接口
在数据集成生命周期的第二步中，我们需要将已经集成的源平台数据进行ETL（提取、转换、加载）处理，并将其转换为目标平台所能接收的格式。本文将详细介绍如何使用轻易云数据集成平台，将吉客云盘盈单数据转换并写入金蝶云星空API接口。
#### 数据请求与清洗
首先，我们从吉客云获取盘盈单的原始数据。假设我们已经完成了数据请求和清洗阶段，接下来我们需要对这些数据进行转换，以便符合金蝶云星空API接口的要求。
#### 数据转换与写入
为了实现数据的无缝对接，我们需要根据金蝶云星空API接口的元数据配置，对吉客云的数据进行相应的字段映射和格式转换。以下是具体的配置细节：
##### API接口配置
根据提供的元数据配置，金蝶云星空API接口使用`batchSave`方法，通过POST请求来接收数据。以下是关键字段及其对应关系：
- **单据编号 (FBillNo)**：这是一个字符串类型字段，用于标识单据。
- **吉客云单号 (FJKYNo)**：映射到`goodsdocNo`字段。
- **单据类型 (FBillTypeID)**：固定值为`QTRKD98_SYS`。
- **库存组织 (FStockOrgId)**：映射到`goodsDocDetailList_ownerName`字段，并通过`ConvertObjectParser`解析。
- **库存方向 (FStockDirect)**：固定值为`GENERAL`。
- **日期 (FDate)**：映射到`inOutDate`字段。
- **部门 (FDEPTID)**：固定值为`BM000029`，通过`ConvertObjectParser`解析。
- **货主类型 (FOwnerTypeIdHead)**：固定值为`BD_OwnerOrg`。
- **货主 (FOwnerIdHead)**：映射到`goodsDocDetailList_ownerName`字段，并通过`ConvertObjectParser`解析。
##### 明细信息配置
对于明细信息部分，我们需要处理多个子字段：
- **物料编码 (FMATERIALID)**：映射到明细项中的 `goodsDocDetailList_goodsNo` 字段，并通过 `ConvertObjectParser` 解析。
- **库存状态 (FStockStatusId)**：固定值为 `KCZT01_SYS`, 通过 `ConvertObjectParser`.
- **收货仓库 (FSTOCKID)**：映射到 `warehouseCode`, 通过 `ConvertObjectParser`.
- **实收数量 (FQty)**：映射到明细项中的 `goodsDocDetailList_quantity`.
##### 请求体示例
以下是一个完整的请求体示例，展示了如何将吉客云的数据按照上述配置转换为金蝶云星空API所需格式：
```json
{
"FormId": "STK_MISCELLANEOUS",
"IsVerifyBaseDataField": true,
"Operation": "Save",
"IsAutoSubmitAndAudit": true,
"Model": {
"FBillNo": "123456",
"FJKYNo": "{goodsdocNo}",
"FBillTypeID": {"FNumber": "QTRKD98_SYS"},
"FStockOrgId": {"FNumber": "{goodsDocDetailList_ownerName}"},
"FStockDirect": "GENERAL",
"FDate": "{inOutDate}",
"FDEPTID": {"FNumber": "BM000029"},
"FOwnerTypeIdHead": "BD_OwnerOrg",
"FOwnerIdHead": {"FNumber": "{goodsDocDetailList_ownerName}"},
"FEntity": [
{
"FMATERIALID": {"FNumber": "{{items.goodsDocDetailList_goodsNo}}"},
"FStockStatusId": {"FNumber": "KCZT01_SYS"},
"FSTOCKID": {"FNumber": "{warehouseCode}"},
"FQty": "{{items.goodsDocDetailList_quantity}}"
}
]
}
}
```
#### 数据写入
在完成上述配置后，我们可以通过轻易云的数据集成平台，将转换后的数据发送至金蝶云星空API接口，实现最终的数据写入操作。确保每个字段都正确映射和解析，以保证数据的一致性和准确性。
通过这种方式，我们能够高效地完成不同系统间的数据集成任务，实现业务流程的自动化和智能化。
