### 金蝶云星空到聚水潭系统集成案例：组装单（子项）对接其他出库单
在企业信息化管理中，数据的高效流转和准确对接是保证业务顺畅运作的关键。本文将分享一个具体的技术案例，即如何通过轻易云数据集成平台，实现金蝶云星空与聚水潭之间的数据无缝集成。本次配置场景为：金蝶--组装单（子项）=>聚水潭--其他出库单。
#### 技术要点解析
1. **API接口调用与数据获取**
利用金蝶云星空提供的`executeBillQuery` API，我们能够实时、可靠地抓取其系统内的组装单（子项）数据。同时，为了避免漏单现象，我们设计了一套定时任务机制，确保每隔一段时间自动拉取最新数据。
2. **分页处理与限流策略**
由于金蝶云星空API对于返回结果有分页限制，我们需要合理设置分页参数并处理批量请求，以便顺利获取全部所需的数据。此外，在高频请求情况下，还需注意API接口的限流问题，通过排队机制来平衡接口调用频率，防止触发限制规则而影响整体流程。
3. **自定义转换逻辑与格式适配**
在实现跨系统的数据写入前，需要先完成格式转换。由于金蝶和聚水潭在不同业务模块下的数据结构存在差异，因此必须利用轻易云提供的数据转换工具，自定义编写映射脚本，将源端结构精准匹配至目标端要求的格式，并进行必要的字段校验与补全操作。
4. **数据写入及性能优化**
聚水潭支持通过开放API `/open/jushuitan/otherinout/upload` 接口导入外部数据。在大批量、高频率插入操作中，应当充分发挥平台高吞吐量特点，将预处理后的数据信息快速传输至目标数据库。这不仅提高了工作效率，也减少了因网络波动导致延迟或误差的情况发生。
5. **监控告警及异常重试机制**
针对此次集成项目，我们配置了全面且细致的数据监控和告警措施。当出现任何异常状况，如网络故障或接口响应超时等，都能第一时间获得预警信号并采取相应方案，同时启动错误重试机制以保障最终任务执行成功。一整套完善且灵活的问题追踪体系，为整个集成过程保驾护航。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在轻易云数据集成平台中，调用源系统接口是数据处理生命周期的第一步。本文将深入探讨如何通过金蝶云星空接口`executeBillQuery`获取并加工数据。
#### 接口概述
金蝶云星空的`executeBillQuery`接口支持POST请求，用于查询特定业务对象的数据。该接口支持分页查询，并允许通过过滤条件精确筛选所需数据。以下是元数据配置中的关键参数：
- `api`: "executeBillQuery"
- `method`: "POST"
- `number`: "FBillNo"
- `id`: "FSubEntity_FDetailID"
- `pagination`: {"pageSize":500}
- `idCheck`: true
#### 请求参数配置
在实际调用中，我们需要根据业务需求配置请求参数。以下是主要的请求字段及其含义：
1. **实体主键** (`FID`): 用于唯一标识每条记录。
2. **单据编号** (`FBillNo`): 用于标识具体的单据。
3. **单据状态** (`FDocumentStatus`): 仅查询状态为已审核的单据。
4. **库存组织** (`FStockOrgId.FNumber`): 指定库存组织编号。
5. **日期** (`FDate`): 单据日期。
6. **单据类型** (`FBillTypeID`): 指定单据类型。
7. **成品货主类型** (`FOwnerTypeIdHead`): 成品货主类型。
8. **成品货主** (`FOwnerIdHead.FNumber`): 成品货主编号。
9. **事务类型** (`FAffairType`): 事务类型，示例中为"Assembly"。
其他字段如费用、部门、备注等也可以根据需要进行配置。
#### 分页与过滤条件
为了提高查询效率，接口支持分页查询。分页参数包括：
- `Limit`: 每页返回的最大行数，配置为500。
- `StartRow`: 查询起始行索引，根据实际情况动态调整。
过滤条件通过`FilterString`字段进行配置，例如：
```json
"FilterString": "FApproveDate>='{{LAST_SYNC_TIME|datetime}}' and FAFFAIRTYPE = 'Assembly' and FDocumentStatus='C'"
```
该条件表示仅查询审核日期在上次同步时间之后且事务类型为"Assembly"、单据状态为已审核的记录。
#### 字段集合与表单ID
字段集合通过`FieldKeys`字段指定，包含所有需要查询的字段。例如：
```json
"FieldKeys": ["FID", "FBillNo", "FDocumentStatus", "FStockOrgId.FNumber", ...]
```
表单ID通过`FormId`字段指定，例如：
```json
"FormId": "STK_AssembledApp"
```
#### 实际调用示例
以下是一个实际调用示例，通过POST请求获取组装单（子项）数据：
```json
{
"api": "executeBillQuery",
"method": "POST",
"number": "FBillNo",
"id": "FSubEntity_FDetailID",
"pagination": {"pageSize": 500},
"idCheck": true,
"request": [
{"field":"FID","label":"实体主键","type":"string","value":"FID"},
{"field":"FBillNo","label":"单据编号","type":"string","value":"FBillNo"},
{"field":"FDocumentStatus","label":"单据状态","type":"string","value":"FDocumentStatus"},
{"field":"FStockOrgId_FNumber","label":"库存组织","type":"string","value":"FStockOrgId.FNumber"},
{"field":"FDate","label":"日期","type":"string","value":"FDate"},
{"field":"FBillTypeID","label":"单据类型","type":"string","value":"FBillTypeID"},
{"field":"FOwnerTypeIdHead","label":"成品货主类型","type":"string","value":"FOwnerTypeIdHead"},
{"field":"FOwnerIdHead_FNumber","label":"成品货主","type":"string","value":"FOwnerIdHead.FNumber"},
{"field":"FAffairType","label":"事务类型","type":"string","value":"FAffairType"},
...
],
"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: FApproveDate>='{{LAST_SYNC_TIME|datetime}}' and FAFFAIRTYPE = 'Assembly' and FDocumentStatus='C'},
...
]
}
```
通过上述配置，可以高效地从金蝶云星空系统中获取所需的数据，并在后续步骤中进行进一步的数据清洗和转换处理。
### 使用轻易云数据集成平台进行ETL转换并写入聚水潭API接口的技术案例
在数据集成生命周期的第二步中，我们需要将已经集成的源平台数据进行ETL（Extract, Transform, Load）转换，最终写入目标平台。在本案例中，我们将金蝶系统中的组装单（子项）数据转换为聚水潭系统能够接收的其他出库单格式，并通过API接口上传。
#### 元数据配置解析
以下是我们在轻易云数据集成平台上配置的元数据：
```json
{
"api": "/open/jushuitan/otherinout/upload",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{
"field": "is_confirm",
"label": "是否确认单据",
"type": "string",
"value": "_function IF({F_POKM_JSTSTOCKNUMBER} = 10816570 , 1 , 0 )"
},
{
"field": "excute_confirming",
"label": "是否审核单据",
"type": "string",
"value": "false"
},
{
"field": "wms_co_id",
"label": "仓库编号",
"type": "int",
"value": "{F_POKM_JSTSTOCKNUMBER}"
},
{
"field": "type",
"label": "出入库类型",
"type": "string",
"value": "out"
},
{
"field": "external_id",
"label": "外部单号",
"type": "string",
"value":"Z{FBillNo}{F_POKM_JSTSTOCKNUMBER}{F_POKM_JSTSTOCKNUMBER2}"
},
{
...
}
],
...
}
```
#### 配置细节与实现
1. **API 接口路径与请求方法**：
- `api`字段指定了目标平台聚水潭的API路径为`/open/jushuitan/otherinout/upload`。
- `method`字段指定了HTTP请求方法为POST。
2. **字段映射与转换**：
- `is_confirm`字段通过自定义函数判断仓库编号是否为特定值，来决定是否确认单据。
- `excute_confirming`字段直接设置为"false"，表示不自动审核单据。
- `wms_co_id`字段直接映射金蝶系统中的仓库编号 `{F_POKM_JSTSTOCKNUMBER}`。
- `type`字段固定为"out"，表示出库类型。
- `external_id`字段组合了多个源字段生成唯一外部单号：`Z{FBillNo}{F_POKM_JSTSTOCKNUMBER}{F_POKM_JSTSTOCKNUMBER2}`。
3. **备注与物流信息**：
- `remark`字段包含了推送来源和单号信息，便于追踪。
- 物流相关字段如`lc_id`, `l_id`, 和`logistics_company`等可以根据实际需求进行填充或留空。
4. **嵌套数组处理**：
- 对于复杂结构的数据，如商品明细，通过嵌套数组实现。每个商品明细项包括商品编码和入库数量：
```json
{
...
{
“field”: “items”,
“label”: “items”,
“type”: “array”,
“value”: “list”,
“children”: [
{“field”: “sku_id”, “label”: “商品编码”, “type”: “string”, “value”: “{{list.FMaterialIDSETY_FNumber}}”},
{“field”: “qty”, “label”: “入库数量”, “type”: “string”, “value”: “{{list.FQtySETY}}”}
]
}
...
}
```
5. **操作配置**：
- 在操作部分，我们定义了如何合并多个源记录到一个目标记录中。具体配置如下：
```json
{
...
”operation“: {
”method“: ”merge“,
”field“: ”FBillNo,F_POKM_JSTSTOCKNUMBER,F_POKM_JSTSTOCKNUMBER2“,
”bodyName“: ”list“,
”header“: [”FBillNo“, ”F_POKM_JSTSTOCKNUMBER“, ”F_POKM_JSTSTOCKNUMBER2“],
”body“: [”FMaterialIDSETY_FNumber“, ”FQtySETY“],
”bodySum“: [”FQtySETY“]
}
...
}
```
- 此配置确保将同一订单下的多个子项合并处理，并计算总数量。
通过以上详细的元数据配置，我们成功实现了从金蝶系统到聚水潭系统的数据ETL转换，并通过API接口顺利上传。这不仅提升了数据处理效率，还确保了数据的一致性和准确性。
