### 吉客云数据集成到金蝶云星空：盘盈单103v2对接其他入库案例分享
在企业信息管理系统中，实现不同平台之间的数据无缝对接一直是一个挑战。本文将深入探讨如何利用轻易云数据集成平台完成吉客云与金蝶云星空之间的盘盈单103v2对接其他入库的技术方案。
此解决方案涵盖了从吉客云接口`erp.storage.goodsdocin.v2`获取数据并通过金蝶云星空API `batchSave`实现批量写入，确保大规模数据处理的高效性和可靠性。在实施过程中，我们关注以下几个关键技术点：
1. **定时可靠的数据抓取**：通过设置合理的定时任务，从吉客云准时可靠地抓取盘盈单相关数据，确保不漏单、不重单。
2. **快速大量数据写入**: 利用金蝶云星空提供的大容量批量保存接口，在短时间内高效完成多条记录的插入操作，以满足业务实时性的要求。
3. **分页和限流处理**：针对吉客云API可能存在的数据分页返回及请求速率限制问题，设计了智能化分页算法与限流策略来保障稳定的数据传输过程。
4. **格式差异转换**: 鉴于两个系统间的数据结构差异，通过自定义映射规则将吉客云中的字段精准匹配至金蝶云对应表项，大大提升了转化效率。
5. **异常处理与错误重试机制**: 集成过程中不可避免地会遇到各种异常情况，如网络波动、接口响应超时等。因此，我们引入了灵活且稳健的错误检测和重试机制，从而保证任务执行不中断。
6. **实时监控与日志记录**：通过全程透明化跟踪每个步骤，并详细记录日志，使得问题定位更迅速，同时也便于后期审计分析和持续改进。
在下文中，将依次细述上述各个环节的具体实现方法以及我们在实际应用中的心得体会。
### 调用吉客云接口erp.storage.goodsdocin.v2获取并加工数据
在数据集成的生命周期中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用吉客云接口`erp.storage.goodsdocin.v2`，并对获取的数据进行初步加工。
#### 接口调用配置
首先，我们需要配置元数据，以便正确调用吉客云的API接口。以下是元数据配置的关键部分：
```json
{
"api": "erp.storage.goodsdocin.v2",
"method": "POST",
"number": "goodsdocNo",
"id": "recId",
"pagination": {
"pageSize": 10
},
"idCheck": true,
"request": [
{"field":"pageIndex","label":"分页页码","type":"int"},
{"field":"pageSize","label":"分页页数","type":"int","value":"100"},
{"field":"goodsDocNo","label":"入库单号","type":"string"},
{"field":"startDate","label":"创建时间的起始时间","type":"string"},
{"field":"endDate","label":"创建时间的结束时间","type":"string"},
{"field":"gmtModifiedStart","label":"主表更新时间起始","type":"string","value":"_function from_unixtime(({LAST_SYNC_TIME}-86400),'%Y-%m-%d %H:%i:%s')"},
{"field":"gmtModifiedEnd","label":"主表更新时间截至","type":"string","value":"_function from_unixtime(({CURRENT_TIME}-86400),'%Y-%m-%d %H:%i:%s')"},
{"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":"sourceBillNo","label":"原始单号","type":"string"},
{"field":"warehouseCode","label":"仓库编号","type":"string"},
{"field":"outBillNo","label":"外部单号","type":"string"},
{"field":"vendCode","label":"供应商编号(往来单位)","type":"string"},
{"field":"billNo","label":"上游单据号(关联单号)","type":"string"},
{"field":"userName","label":"创建人名称","type": "string"},
{
"field": "selelctFields",
"label": "需要返回的字段",
"type": "string",
"describe": "需要返回的字段,用“,”号拼接，子类用子类名称.属性",
"value": "...(省略具体字段)"
}
],
...
}
```
#### 数据请求与清洗
在配置好元数据后，我们可以开始进行数据请求。通过POST方法调用`erp.storage.goodsdocin.v2`接口，并传递必要的参数，如分页信息、时间范围和特定的过滤条件（如`inouttype`设为103表示盘盈入库）。
```json
{
"pageIndex":1,
"pageSize":100,
"gmtModifiedStart": "_function from_unixtime(({LAST_SYNC_TIME}-86400),'%Y-%m-%d %H:%i:%s')",
"gmtModifiedEnd": "_function from_unixtime(({CURRENT_TIME}-86400),'%Y-%m-%d %H:%i:%s')",
...
}
```
#### 数据转换与写入
获取到的数据通常需要进行一定程度的清洗和转换，以符合目标系统或数据库的要求。例如，我们可能需要将日期格式进行标准化处理，或者将某些字段值进行映射转换。
```json
{
...
// 示例：将日期格式从字符串转换为标准日期格式
"transformedDateField": "_function to_date_format(gmtCreate, '%Y-%m-%d %H:%i:%s')"
}
```
#### 分页处理
由于数据量可能较大，我们需要处理分页逻辑。通过设置`pageIndex`和`pageSize`参数，可以逐页获取数据，并在每次请求后更新这些参数以获取下一页的数据。
```json
{
...
// 示例：分页处理逻辑
for (let pageIndex = 1; ; pageIndex++) {
let response = callApi({
...,
pageIndex: pageIndex,
pageSize: metadata.pagination.pageSize
});
if (response.data.length === 0) break;
processData(response.data);
}
}
```
#### 异常处理与补偿机制
在实际操作中，可能会遇到网络波动或接口响应异常等问题。为此，我们可以设置定时任务（如crontab）和补偿机制，以确保数据同步的完整性。
```json
{
...
// 示例：补偿机制配置
{
crontab: '2 */5 * * *',
takeOverRequest: [
{
field: 'gmtModifiedStart',
value: "_function from_unixtime(({CURRENT_TIME}-172800),'%Y-%m-%d %H:%i:%s')"
},
{
field: 'gmtModifiedEnd',
value: "_function from_unixtime(({CURRENT_TIME}-86400),'%Y-%m-%d %H:%i:%s')"
}
]
}
}
```
通过上述步骤，我们可以高效地调用吉客云接口获取所需的数据，并对其进行初步加工，为后续的数据转换与写入打下坚实基础。这一过程不仅提升了数据集成的透明度和效率，也确保了业务流程的顺畅运行。
### 使用轻易云数据集成平台将源数据转换并写入金蝶云星空API接口
在数据集成的生命周期中，ETL（提取、转换、加载）过程是至关重要的一环。本文将详细探讨如何利用轻易云数据集成平台，将已经集成的源平台数据进行ETL转换，转为金蝶云星空API接口所能够接收的格式，并最终写入目标平台。
#### 数据请求与清洗
首先，我们需要确保从源系统获取的数据经过清洗和预处理。这一步骤通常包括去除无效数据、标准化字段格式以及处理缺失值等。假设我们已经完成了这些前期工作，现在进入关键的ETL转换阶段。
#### 数据转换与写入
在轻易云数据集成平台上，我们通过配置元数据来实现对接金蝶云星空API接口的具体操作。以下是详细的元数据配置及其解析：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 1,
"method": "batchArraySave"
},
"request": [
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","value":"{goodsdocNo}"},
{"field":"FBillTypeID","label":"单据类型","type":"string","describe":"单据类型","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"QTRKD01_SYS"},
{"field":"FStockOrgId","label":"库存组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{companyCode}"},
{"field":"FStockDirect","label":"库存方向","type":"string","describe":"下拉列表","value":"GENERAL"},
{"field":"FDate","label":"日期","type":"string","describe":"日期","value":"_function DATE_FORMAT('{inOutDate}', '%Y-%m-%d')"},
{"field":"FDEPTID","label":"部门","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"BM000016"},
{"field":"FOwnerTypeIdHead","label":"货主类型","type":"string","describe":"多类别基础资料列表","value":"BD_OwnerOrg"},
{"field":"FOwnerIdHead","label":"货主","type":"","describe":"","parser":{"name":"","params":""},"value":""},
{"field":"","label":"","type":"","describe":"","parser":{"name":"","params":""},"value":""},
{"field":"","label":"","type":"","describe":"","parser":{"name":"","params":""},"value":""},
{"field":"","label":"","type":"","describe":"","parser":{"name":"","params":""},"value":""},
{"field":"","label":"","type":"","describe":"","parser":{"name":"","params":""},"value":""},
{"field":"",
"children":[
{
"parent":"",
"children":[
{
"parent":"",
"children":[
{
"parent":"",
"children":[
{
"parent":"",
"children":[
{
"parent":"",
"children":[
{
"parent":"",
"children":[
{
""
}
]
}
]
}
]
}
]
}
]
}
]
}
],
""
],
""
],
""
}
```
#### 元数据配置解析
1. **API接口与方法**
- `api`: `batchSave` 表示使用批量保存接口。
- `method`: `POST` 表示使用HTTP POST方法提交请求。
2. **操作配置**
- `idCheck`: 设置为`true`表示需要进行ID校验。
- `operation`: 配置操作方式，其中`rowsKey`指定数组键名，`rows`设置为1表示单行操作，`method`为`batchArraySave`表示批量保存数组。
3. **请求字段**
- `FBillNo`: 单据编号，对应源数据中的 `{goodsdocNo}`。
- `FBillTypeID`: 单据类型，通过 `ConvertObjectParser` 转换为金蝶系统识别的编码 `QTRKD01_SYS`。
- `FStockOrgId`: 库存组织，通过 `ConvertObjectParser` 转换为对应编码 `{companyCode}`。
- `FStockDirect`: 库存方向，固定值为 `GENERAL`。
- `FDate`: 日期，通过 `_function DATE_FORMAT('{inOutDate}', '%Y-%m-%d')` 格式化日期。
- `FDEPTID`: 部门，通过 `ConvertObjectParser` 转换为编码 `BM000016`。
- 其他字段如货主类型、备注、关联单号等均根据业务需求进行相应配置。
4. **明细信息**
明细信息部分通过嵌套数组实现，每个子项代表一个明细行：
- `FMATERIALID`: 物料编码，通过 `{goodsDocDetailList.goodsNo}` 获取并转换。
- `FCMKBarCode`: 零售条形码，对应源数据中的 `{skuBarcode}`。
- 其他字段如实收数量、成本价、金额等均通过相应的源数据字段获取并映射。
5. **其他请求参数**
- `"FormId"`: 指定业务对象表单ID，如：`STK_MISCELLANEOUS`。
- `"IsVerifyBaseDataField"`: 设置是否验证基础资料有效性，默认为false。
- `"Operation"`: 执行操作类型，设置为 `"Save"` 表示保存操作。
- `"IsAutoSubmitAndAudit"`: 是否自动提交并审核，设置为true。
#### 实际应用案例
假设我们从源系统获取了一组盘盈单数据，需要将其转换并写入金蝶云星空。我们可以利用上述元数据配置，通过轻易云平台完成这一过程：
```json
{
// 示例输入JSON
}
```
通过上述配置，我们能够确保每个字段都被正确地映射和转换，从而顺利地将盘盈单数据写入到金蝶云星空系统中，实现不同系统间的数据无缝对接。
以上就是利用轻易云数据集成平台进行ETL转换，并将数据写入金蝶云星空API接口的技术案例。通过合理配置元数据，可以高效地完成复杂的数据集成任务，提高业务流程的自动化和准确性。
