### 聚水潭数据集成到金蝶云星辰V2的技术实践分享
在实际的系统对接中，将聚水潭平台的数据无缝集成到金蝶云星辰V2是一项颇具挑战性的任务。本次案例展示了如何通过轻易云数据集成平台，实现两者间高效、稳定的数据传输，特别是针对“其他出库单”这一业务对象的完整对接。
首先，我们需要抓取聚水潭中的“其他出库单”数据。为了确保不会漏单，我们调用了聚水潭提供的API接口`/open/other/inout/query`，结合定时调度策略并配合分页处理机制，有效解决了由于限流和大批量数据带来的难题。在那个过程中，每一页的数据都被精确读取，并实时记录日志以保证透明性与可追踪性。
其次，在将抓取的数据写入金蝶云星辰V2之前，需要对双方之间存在的数据格式差异进行处理。我们利用自定义映射功能，将聚水潭返回的不规则字段转换为符合金蝶要求的规范格式，然后通过调用API接口 `/jdy/v2/scm/inv_other_out`完成数据写入。这一步骤不仅确保了数据的一致性，还提升了整体效率。
此外，为应对可能出现的异常情况，如网络波动或者API错误响应，我们实现了一套完善的重试机制以及异常处理方案。当某个请求失败时，系统会自动重新尝试，并在多次失败后触发告警通知，让运维团队及时介入排查问题，从而保障整个流程顺畅运行。同时，对每一次操作进行了详细日志记录，以便于后续分析和优化。
本文将围绕上述关键点展开详细讲解，包括如何程序化调用API、解决分页与限流问题，以及实施可靠的数据映射和异常处理机制等，希望能够为类似需求提供有效参考。
### 调用聚水潭接口/open/other/inout/query获取并加工数据的技术案例
在轻易云数据集成平台中，调用聚水潭接口`/open/other/inout/query`是数据生命周期的第一步。本文将详细探讨如何配置和调用该接口，并对获取的数据进行初步加工。
#### 接口配置与调用
首先，我们需要了解接口的基本信息和配置参数。根据提供的元数据配置，接口采用POST方法进行调用，主要参数如下：
- **modified_begin**: 修改起始时间，默认值为当前时间前20分钟。
- **modified_end**: 修改结束时间，默认值为当前时间。
- **status**: 单据状态，固定为"Confirmed"。
- **page_index**: 页码，默认值为1。
- **page_size**: 每页条数，默认值为30。
- **date_type**: 抓取时间类型，默认为0，即修改时间。
- **wms_co_id**: 仓库编号，固定值为12851795。
以下是一个示例请求体：
```json
{
"modified_begin": "{{MINUTE_AGO_20|datetime}}",
"modified_end": "{{CURRENT_TIME|datetime}}",
"status": "Confirmed",
"page_index": "1",
"page_size": "30",
"date_type": "0",
"wms_co_id": "12851795"
}
```
#### 数据过滤与条件设置
为了确保只获取“其它出库”类型的数据，我们需要设置条件过滤。元数据配置中提供了两个条件：
1. `condition_bk`: 排除非“其它出库”类型的数据。
2. `condition`: 包含“其它出库”类型的数据。
具体配置如下：
```json
"condition_bk":[[{"field":"type","logic":"notin","value":"其它出库"}]],
"condition":[[{"field":"type","logic":"in","value":"其它出库"}]]
```
通过上述条件设置，我们可以精准地筛选出所需的数据类型。
#### 自动填充响应与接管机制
为了简化数据处理过程，我们启用了自动填充响应功能（`autoFillResponse`），这意味着系统会自动处理并填充返回的数据，无需手动干预。此外，为了应对可能出现的数据遗漏问题，我们设置了接管机制（`omissionRemedy`），定时任务每3小时执行一次，以确保数据的完整性。
接管机制配置如下：
```json
"omissionRemedy":{
"crontab":"2 */3 * * *",
"takeOverRequest":[
{
"field":"modified_begin",
"value":"_function FROM_UNIXTIME( unix_timestamp() -86400 , '%Y-%m-%d %H:%i:%s' )",
"type":"string",
"label":"接管字段"
}
]
}
```
#### 数据加工与转换
在获取到原始数据后，需要对其进行初步加工和转换，以便后续写入目标系统。在这个过程中，可以利用轻易云平台提供的可视化工具，对数据进行清洗、格式转换等操作。例如，将日期格式统一转换为ISO标准格式，将数值字段进行单位换算等。
以下是一个简单的数据转换示例：
```json
{
"io_id": "{{io_id}}",
"modified_time": "{{modified_time|datetime('ISO')}}",
"quantity": "{{quantity|number}}"
}
```
通过以上步骤，我们成功完成了从聚水潭接口获取并加工数据的全过程。这一过程不仅确保了数据的准确性和完整性，还极大提升了业务处理效率。
### 使用轻易云数据集成平台实现金蝶云星辰V2 API接口的数据转换与写入
在轻易云数据集成平台的生命周期中，数据请求与清洗是第一步，而第二步则是将已经集成的源平台数据进行ETL（Extract, Transform, Load）转换，并转为目标平台所能够接收的格式。本文将重点探讨如何将聚水潭的其他出库单数据转换为金蝶云星辰V2 API接口所能接收的格式，并最终写入目标平台。
#### 元数据配置解析
在进行ETL转换之前，我们需要理解元数据配置。以下是一个具体的元数据配置示例：
```json
{
"api": "/jdy/v2/scm/inv_other_out",
"effect": "EXECUTE",
"method": "POST",
"number": "id",
"id": "id",
"name": "id",
"idCheck": true,
"request": [
{"field":"bill_date","label":"单据日期","type":"string","describe":"单据日期","value":"{io_date}"},
{"field":"bill_no","label":"单据编码","type":"string","describe":"单据编码","value":"{io_id}"},
{"field":"trans_type_id","label":"业务类型id","type":"string","describe":"业务类型id","value":"13"},
{"field":"custom_field","label":"自定义字段","type":"object","children":[{"field":"custom_field__1__3uapqb6ot43jia","label":"出库类型","type":"string","value":"其它出库"}]},
{"field":"operation_key","label":"操作类型","type":"string","describe":"操作类型，审核audit、提交submit","value":"audit"},
{"field":"remark","label":"备注","type":"string","value":"{remark}"},
{
"field": "material_entity",
"label": "商品分录",
"type": "array",
"describe": "商品分录",
"value": "items",
"children": [
{"field": "material_id",
"label": "商品",
"type": "string",
"describe": "商品",
"value": "_findCollection find id from ac1d70fd-05db-3961-a168-b5617749605e where number={{items.sku_id}}"
},
{"field": "qty",
"label": "数量",
"type": "string",
"describe": "数量",
"value": "{{items.qty}}"
},
{"field": "unit_id",
"label": "单位",
"type": "string",
"describe": "单位",
"'value': '4'"
},
{"field": 'stock_id',
'label': '仓库',
'type': 'string',
'describe': '仓库',
'value': '_findCollection find id from f05acc4f-b637-3497-86d3-3ed5423f226a where name={warehouse}'
},
{"field': 'cost',
'label': '出库成本',
'type': 'string',
'value': '_function {{items.cost_price}}*{{items.qty}}'
}
]
}
]
}
```
#### 数据字段映射与转换
根据上述元数据配置，我们需要将聚水潭的数据字段映射到金蝶云星辰V2 API所需的字段，并进行必要的转换。
1. **单据日期（bill_date）**：从聚水潭获取`io_date`字段并直接映射。
```json
{"field":"bill_date", "value" :"{io_date}"}
```
2. **单据编码（bill_no）**：从聚水潭获取`io_id`字段并直接映射。
```json
{"field" : “bill_no”, “value” : “{io_id}”}
```
3. **业务类型ID（trans_type_id）**：固定值为13，表示“其他出库”。
```json
{"field" : “trans_type_id”, “value” : “13”}
```
4. **自定义字段（custom_field）**：包含一个子字段“出库类型”，固定值为“其它出库”。
```json
{
“field” : “custom_field”,
“children”: [{"field" : “custom_field__1__3uapqb6ot43jia”, “value”: “其它出库”}]
}
```
5. **操作类型（operation_key）**：固定值为“audit”，表示审核。
```json
{“field” : “operation_key”, “value”: “audit”}
```
6. **备注（remark）**：从聚水潭获取`remark`字段并直接映射。
```json
{“field” : “remark”, “value”: "{remark}"}
```
7. **商品分录（material_entity）**：这是一个数组，需要对每个商品项进行处理。包括以下子字段：
- 商品ID（material_id）：通过SKU ID查找对应的商品ID。
```json
{
‘field’ : ‘material_id’,
‘value’: ‘_findCollection find id from ac1d70fd-05db-3961-a168-b5617749605e where number={{items.sku_id}}’
}
```
- 数量（qty）：直接映射数量字段。
```json
{‘field’ : ‘qty’, ‘value’: ‘{{items.qty}}’}
```
- 单位ID（unit_id）：固定值为4。
```json
{‘field’ : ‘unit_id’, ‘value’: ‘4’}
```
- 仓库ID（stock_id）：通过仓库名称查找对应的仓库ID。
```json
{
‘field’ : ‘stock_id’,
‘value’: ‘_findCollection find id from f05acc4f-b637-3497-86d3-3ed5423f226a where name={warehouse}’
}
```
- 出库成本（cost）：计算公式为`cost_price * qty`。
```json
{‘field’ : ‘cost’, ‘value’: ‘_function {{items.cost_price}}*{{items.qty}}’}
```
#### 数据写入目标平台
在完成上述ETL转换后，我们使用POST方法将处理后的数据发送到金蝶云星辰V2 API接口：
```http
POST /jdy/v2/scm/inv_other_out HTTP/1.1
Host: api.kingdee.com
Content-Type: application/json
{
// 转换后的JSON数据结构
}
```
通过轻易云数据集成平台，我们可以实现全异步、无缝的数据对接，确保不同系统间的数据高效流动和处理。以上技术细节展示了如何利用元数据配置，将源平台的数据准确转换并写入目标平台，为企业提供了强大的数据集成解决方案。
