### 金蝶-盘盈单——>聚水潭-其他出库单 集成案例
在企业的日常数据处理过程中，如何高效、稳定地进行系统对接和数据集成，是提升业务效率的关键。本案例将分享如何通过轻易云数据集成平台，将金蝶云星空中的盘盈单数据无缝导入到聚水潭作为其他出库单，实现两个系统间的数据互通与同步。
#### 实现目标
首先，我们需要确保从金蝶云星空获取到准确且完整的盘盈单数据。为此，我们将利用金蝶云星空提供的executeBillQuery接口来定时抓取所需的数据，并基于API反馈的信息构建可靠的数据采集机制，以防止漏单问题。
与此同时，针对大量快速写入需求，我们会使用轻易云平台支持的大吞吐量能力，将已获取的数据批量、高速地写入到聚水潭。这一步骤主要通过调用聚水潭开放的其他出库单上传API(`/open/jushuitan/otherinout/upload`)来实现。
为了保障整个流程顺利运行，还要特别注意以下几点技术细节：
1. **分页及限流处理**：由于金蝶云星空API存在分页及调用频率限制，需要设计适当的方案以分批次抓取大规模数据，同时避免触发限流策略。
2. **自定义转换逻辑**：根据不同系统之间的数据格式差异，通过自定义转换逻辑，使得输出结果能够被聚水潭准确识别并存储。
3. **实时监控和告警机制**：利用集中式监控功能，随时跟踪记录每一次任务执行情况。一旦检测到异常状况，则启动错误重试机制，以最大程度降低因网络连接或其它意外导致的失败可能性。
这个案例不仅展示了如何运用强大的工具完成复杂系统间的数据整合，也为后续类似项目提供了一个可参考的重要范本。在接下来的内容中，我们将逐步解析具体实施步骤和代码示例，从而帮助您更深入理解这一过程。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成过程中，调用源系统的API接口是关键的一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口来获取盘盈单的数据，并进行初步加工。
#### 接口调用配置
首先，我们需要配置调用金蝶云星空接口的元数据。以下是元数据配置的主要内容：
```json
{
"api": "executeBillQuery",
"method": "POST",
"number": "FBillNo",
"id": "FBillEntry_FEntryID",
"pagination": {
"pageSize": 500
},
"idCheck": true,
"request": [
{"field":"FBillEntry_FEntryID","label":"FEntryID","type":"string","value":"FBillEntry_FEntryID"},
{"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":"FStockerId","label":"仓管员","type":"string","value":"FStockerId"},
{"field":"FCreatorId","label":"创建人","type":"string","value":"FCreatorId"},
{"field":"FCreateDate","label":"创建日期","type":"string","value":"FCreateDate"},
{"field":"FModifierId","label":"最后修改人","type":"string","value":"FModifierId"},
{"field":"FModifyDate","label":"最后修改日期","type\":\"string\",\"value\":\"FModifyDate\"},
{"field\":\"FApproverId\",\"label\":\"审核人\",\"type\":\"string\",\"value\":\"FApproverId\"},
{"field\":\"FApproveDate\",\"label\":\"审核日期\",\"type\":\"string\",\"value\":\"FApproveDate\"},
{"field\":\"FNoteHead\",\"label\":\"备注\",\"type\":\"string\",\"value\":\"FNoteHead\"},
{"field\":\"FMaterialId_FNumber\",\"label\":\"物料编码\",\"type\":\"string\",\"value\":\"FMaterialId.FNumber\"},
{"field\":\"FUnitID\",\"label\":\"单位\",\"type\":\"string\",\"value\":\"FUnitID\"},
{"field\":\"FAcctQty\",\"label\":\"账存数量\",\"type\":\"string\",\"value\":\"FAcctQty\"},
{"field\": \" FCountQty \", \" label \ ": \"盘点数量\", \" type \ ": \" string \ ", \" value \ ": \" FCountQty \"},
{\" field \ ": \" FGainQty \ ", \" label \ ": \"盘盈数量\", \" type \ ": \" string \ ", \" value \ ": \" FGainQty \"},
{\" field \ ": \" FStockId_FNumber \ ", \" label \ ": \"仓库\", \" type \ ": \" string \ ", \" value \ ": \" FStockId.FNumber \"},
{\" field \ ": \" FStockStatusId \ ", \" label \ ": \"库存状态\", \" type \ ": \" string \ ", \" value \ ": \" FStockStatusId \"},
{\" field \ ": \" FOwnerid_FNumber\ ",\" label\ ":"货主\ "," type\ ":" string\ "," value\ ":"FOwnerid.FNumber\ "},
{\" field\ ":" FPrice\ "," label\ ":"成本价\ "," type\ ":" string\ "," value\ ":" FPrice\ "},
{\" field\": “FAmount”, “标签”: “总成本”, “类型”: “字符串”, “值”: “FAmount”},
{“字段”: “注释”, “标签”: “注释”, “类型”: “字符串”, “值”: “注释”},
{“字段”: “FBomId”, “标签”: “BOM版本”, “类型”: “字符串”, “值”: “FBomId”},
{“字段”: “FMtoNo”, “标签”: “计划跟踪号”, “类型”: ”字符串“, ”值“: ”FMtoNo“ },
{“字段”：”库存标识“，”标签“：”库存更新标识“，”类型“：”字符串“，”值“：”库存标识“ },
{“字段”：”仓位“，”标签“：”仓位“，”类型“：”字符串“，”值“：”仓位“ },
{“字段”：”批号“，”标签：“批号”，“类型”：”字符串”，“值”：”批号.编号“
{‘字段’：“生产日期”，“标签”：‘生产日期’，“类型”：‘字符串’，‘值’：“生产日期”
{‘字段’：“有效期至”，“标签”：‘有效期至’，“类型”：‘字符串’，‘值’：“有效期至”
],
"otherRequest":[
{" field ":" Limit "," label ":"最大行数 "," type ":" string "," describe ":"金蝶的查询分页参数 "," value ":"{PAGINATION_PAGE_SIZE}"}，
{" 字段 ":" StartRow "," 标签 ":"开始行索引 "," 类型 ":" 字符串 "," 描述 ":" 金蝶的查询分页参数 "," 值 ":"{PAGINATION_START_ROW}"}，
{" 字段 ":" TopRowCount "," 标签 ":"返回总行数 "," 类型 ":" int "," 描述 ":" 金蝶的查询分页参数 "}，
{" 字段 ":" FilterString "," 标签 ":"过滤条件 "," 类型 ：" 字符串"，"描述"："示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>="," 值"：" FApproveDate>='{{LAST_SYNC_TIME|datetime}}' and FStockId in ('285633','327726')"}，
{" 字段 ：" FieldKeys"，" 标签 ："需查询的字段key集合"，" 类型 ：" 数组"，" 描述 ："金蝶分录主键ID格式：FPOOrderEntry_FEntryId,其它格式FPurchaseOrgId.FNumber"，"解析器":{"名称："ArrayToString"，参数："，"}}，
{" 字段 ：" FormId"，" 标签 ：业务对象表单 Id"，" 类型 ：字符串"，描述："必须填写金蝶的表单 ID 如：PUR_PurchaseOrder"，值："STK_StockCountGain"}
],
条件：[[
{" 字段 ：'UHZG_JJQty',"逻辑："neqv2"，值："0"}
]]
}
```
#### 数据请求与清洗
在配置完成后，我们通过POST方法调用`executeBillQuery`接口，传递必要的请求参数以获取盘盈单的数据。请求参数包括但不限于：
- `FormId`: 表单ID，指定为`STK_StockCountGain`
- `FieldKeys`: 查询字段集合，通过解析器将数组转换为逗号分隔的字符串
- `FilterString`: 过滤条件，例如根据上次同步时间和特定仓库进行过滤
- `Limit`和`StartRow`: 分页参数，用于控制每次查询的数据量和起始位置
以下是一个示例请求体：
```json
{
"FormId": "STK_StockCountGain",
"FieldKeys": "FBillEntry_FEntryID,FID,FBillNo,FDocumentStatus,FStockOrgId.FNumber,FDate,FBillTypeID,FStockerId,FCreatorId,FCreateDate,FModifierId,FModifyDate,FApproverId,FApproveDate,FNoteHead,FMaterialId.FNumber,FUnitID,FAcctQty,FCountQty,FGainQty,FStockId.FNumber,FStockStatusId,FOwnerid.FNumber,FPrice,FAmount,Fnote,FBomId,FMtoNo,FStockFlag,FStockLocId,FLOT.Fnumber,FProduceDate,FExpiryDate",
"FilterString": "FApproveDate>='2023-01-01' and FStockOrg in ('285633','327726')",
"Limit": 500,
"StartRow": 0
}
```
#### 数据转换与写入
获取到原始数据后，需要对其进行初步清洗和转换。例如，将日期格式统一、处理缺失或异常数据等。这一步可以通过轻易云平台提供的数据处理工具来实现。
接下来，将清洗后的数据写入目标系统（如聚水潭）。这一步通常涉及到数据映射，即将源系统的数据字段映射到目标系统对应的字段。确保数据的一致性和完整性是关键。
#### 示例代码
以下是一个简化的Python示例代码，展示如何调用接口并处理返回的数据：
```python
import requests
import json
url = 'https://api.kingdee.com/executeBillQuery'
headers = {'Content-Type': 'application/json'}
payload = {
'FormId': 'STK_StockCountGain',
'FieldKeys': 'FBillEntry_FEntryID,FID,FBillNo,...',
'FilterString': '...',
'Limit': 500,
'StartRow': 0
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
# 数据清洗与转换
cleaned_data = []
for entry in data['Result']:
cleaned_entry = {
'entry_id': entry['FBillEntry_FEntryID'],
'bill_no': entry['FBillNo'],
# 更多字段映射...
}
cleaned_data.append(cleaned_entry)
# 将清洗后的数据写入目标系统
# write_to_target_system(cleaned_data)
```
通过上述步骤，我们可以高效地从金蝶云星空获取盘盈单的数据，并进行初步加工，为后续的数据集成打下坚实基础。
### 使用轻易云数据集成平台进行ETL转换并写入聚水潭API接口
在数据集成的生命周期中，将源平台的数据进行ETL转换并写入目标平台是一个关键步骤。本文将详细探讨如何利用轻易云数据集成平台，将金蝶的盘盈单数据转换为聚水潭API接口所能接收的格式，并最终写入聚水潭系统。
#### API接口配置
首先，我们需要了解聚水潭API接口的配置元数据。以下是我们将使用的元数据配置：
```json
{
"api": "/open/jushuitan/otherinout/upload",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{"field":"is_confirm","label":"是否确认单据","type":"bool","describe":"是否确认单据；默认false","value":"1"},
{"field":"excute_confirming","label":"是否审核单据","type":"string","describe":"是否审核单据；默认false","value":"true"},
{"field":"wms_co_id","label":"分仓编号","type":"int","describe":"分仓编号","value":"{FStockOrgId_FNumber}","mapping":{"target":"66b46c57aa8cd574f847540a","direction":"reverse"}},
{"field":"warehouse","label":"仓库类型","type":"int","describe":"默认1 ，主仓=1，销退仓=2，进货仓=3，次品仓=4，自定义1仓=6，自定义2仓=7，自定义3仓=8（对应ERP仓库资料设定页面）","value":"1"},
{"field":"type","label":"出入库类型","type":"string","describe":"出入库类型:in是入库（其它退货）out是出库（其它出库）","value":"out"},
{"field":"external_id","label":"外部单号（单据上传成功之后对应页面线上单号）","type":"string","describe":"外部单号（单据上传成功之后对应页面线上单号）","value":"{FBillNo}"},
{"field":"remark","label":"备注","type":"string","describe":"备注，不能传空值","value":"{FNoteHead}"},
{"field":"drp_co_name","label":"出库类型","type":"string","describe":""},
{"field": "items", "label": "商品列表", "type": "array", "describe": "商品列表", "value": "list",
"children": [
{"field": "sku_id", "label": "商品编码", "type": "string", "describe": "", "value": "{FMaterialId_FNumber}"},
{"field": "sale_price", "label": "商品单价", "type": "int", "describe": ""},
{"field": "remark", "label": "", "type": "", },
{"field": "", "", "", ""},
{"field":"","","",""}
]
}
],
...
}
```
#### 数据转换与映射
在进行ETL转换时，我们需要将金蝶盘盈单的数据字段映射到聚水潭API所需的字段。以下是一些关键字段及其映射关系：
- `is_confirm`: 是否确认单据，默认为`false`，在这里设置为`true`。
- `excute_confirming`: 是否审核单据，默认为`false`，在这里设置为`true`。
- `wms_co_id`: 分仓编号，对应金蝶中的`FStockOrgId_FNumber`。
- `warehouse`: 仓库类型，默认设置为主仓，即值为`1`。
- `type`: 出入库类型，这里设置为出库，即值为`out`。
- `external_id`: 外部单号，对应金蝶中的`FBillNo`。
- `remark`: 备注，对应金蝶中的`FNoteHead`。
对于商品列表部分：
- `sku_id`: 商品编码，对应金蝶中的`FMaterialId_FNumber`。
- `qty`: 数量，对应金蝶中的`FGainQty`。
#### 数据清洗与处理
在进行数据清洗时，需要确保以下几点：
1. **字段完整性**：确保所有必要字段都有相应的数据。例如，备注字段不能传空值。
2. **数据格式**：确保所有字段的数据格式符合API要求。例如，数量字段应该是整数型。
3. **逻辑一致性**：确保业务逻辑的一致性。例如，如果某个商品没有生产日期和有效期，则需要根据业务需求决定如何处理这些缺失信息。
#### 数据写入
完成数据清洗与处理后，即可通过POST请求将数据写入聚水潭系统。以下是一个示例请求体：
```json
{
"is_confirm": true,
"excute_confirming": true,
"wms_co_id": 12345,
...
}
```
该请求体包含了所有必要的字段和相应的数据，通过轻易云平台的全异步处理机制，可以高效地将这些数据写入目标系统。
#### 实践案例
假设我们有一条来自金蝶盘盈单的数据记录如下：
```json
{
...
}
```
经过上述ETL转换和清洗处理后，我们得到如下请求体：
```json
{
...
}
```
通过轻易云平台，我们可以实时监控这一过程，并确保每个环节都透明可见，提高了业务透明度和效率。
总结来说，通过合理配置元数据并利用轻易云平台强大的ETL功能，我们可以高效地将源平台的数据转换并写入目标平台，实现不同系统间的数据无缝对接。
