### 聚水潭·奇门数据集成到金蝶云星辰V2：技术案例分享
在系统对接和数据集成过程中，如何高效、可靠地将聚水潭·奇门平台的销售出库单数据无缝映射到金蝶云星辰V2，是许多企业面临的一大挑战。本文以实际运行方案“PACKAGE-聚水潭销售出库单对接销售出库单-1”为例，详细探讨如何利用轻易云数据集成平台解决这一问题。
为确保聚水潭·奇门的数据完整不遗漏，我们首先调用了其提供的`jushuitan.saleout.list.query`接口，通过定时任务机制进行可靠的数据抓取。这一过程不仅需要考虑分页和限流问题，还需实时监控请求状态与日志记录，以便及时应对任何异常情况。通过批量处理策略，可有效提升大量数据在传输过程中的效率。
紧接着，将获取到的原始数据转换为金蝶云星辰V2所需格式，在此过程中，我们必须应用定制化的数据映射规则，以适配两者之间的格式差异。在具体写入操作中，使用到了金蝶云星辰V2的API接口:`/jdy/v2/scm/sal_out_bound`。这一步同样采取了批量写入的方法，并引入了一套完善的错误重试机制来应对可能出现的网络或系统故障，从而保证最终的数据落地准确无误。
至此，一个从源头数据抓取、实时监控、格式转换，再到目标系统写入及风险控制全流程已经清晰呈现。当然，这只是整个项目的一部分，通过以下详解我们将进一步深入了解每个环节和步骤...
### 调用聚水潭·奇门接口获取并加工数据
在数据集成生命周期的第一步，我们需要调用源系统接口获取原始数据，并对其进行初步清洗和加工。本文将详细介绍如何通过轻易云数据集成平台调用聚水潭·奇门接口`jushuitan.saleout.list.query`，并对返回的数据进行处理。
#### 接口配置与请求参数
首先，我们需要配置接口的元数据，以便正确调用API并获取所需的数据。以下是该接口的元数据配置：
```json
{
"api": "jushuitan.saleout.list.query",
"effect": "QUERY",
"method": "POST",
"number": "io_id",
"id": "io_id",
"name": "io_id",
"idCheck": true,
"request": [
{"field": "page_index", "label": "页数", "type": "string", "describe": "第几页，从第一页开始，默认1", "value": "1"},
{"field": "page_size", "label": "每页行数", "type": "string", "describe": "每页多少条，默认25，最大25", "value": "25"},
{"field": "start_time", "label": "修改开始时间", "type": "string", "describe": "修改起始时间，和结束时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空",
"value":"{{LAST_SYNC_TIME|datetime}}"},
{"field": "end_time", "label":"修改结束时间","type":"string","describe":"修改结束时间，和起始时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空","value":"{{CURRENT_TIME|datetime}}"},
{"field":"status","label":"单据状态","type":"string","describe":"单据状态: WaitConfirm=待出库; Confirmed=已出库; Cancelled=作废","value":"Confirmed"},
{"field":"date_type","label":"时间类型","type":"int","describe":"时间类型 默认0 0=修改时间 ; 1=制单日期; 2=出库时间","value":"2"}
],
“autoFillResponse”: true,
“condition”: [
[{"field”:”items.is_gift”,”logic”:”neqv2”,”value”:”true”}],
[]
]
}
```
#### 请求参数详解
- `page_index`: 页数，从第一页开始。默认值为1。
- `page_size`: 每页行数，默认25条，最大25条。
- `start_time` 和 `end_time`: 修改起始和结束时间，这两个字段必须同时存在且间隔不超过七天。
- `status`: 单据状态，此处我们选择“已出库”的状态，即`Confirmed`。
- `date_type`: 时间类型，此处选择出库时间，即值为2。
这些参数确保我们能够准确地获取到符合条件的销售出库单数据。
#### 数据请求与清洗
在发送请求后，我们会得到一个包含多个销售出库单信息的响应。由于轻易云平台支持自动填充响应（autoFillResponse），我们可以直接处理返回的数据。
示例响应数据结构可能如下：
```json
{
“code”:0,
“msg”:”success”,
“data”:[
{
“io_id”:”1234567890”,
“order_no”:”SO20231001”,
“warehouse_code”:”WH001”,
“items”:[
{
“sku_code”:”SKU001”,
“quantity”:10,
“is_gift”:false
},
{
“sku_code”:”SKU002”,
“quantity”:5,
“is_gift”:true
}
],
...
},
...
]
}
```
根据元数据配置中的条件，我们需要过滤掉赠品（`is_gift=true`）的商品项。具体操作如下：
1. 遍历每个销售出库单（`data`数组中的每个对象）。
2. 对于每个销售出库单中的商品项（`items`数组），过滤掉赠品项。
3. 将处理后的结果存储或进一步处理。
示例代码（伪代码）：
```python
def filter_gift_items(sale_out_list):
for sale_out in sale_out_list:
sale_out['items'] = [item for item in sale_out['items'] if not item['is_gift']]
return sale_out_list
response_data = api_call() # 假设这是调用API后的响应数据
filtered_data = filter_gift_items(response_data['data'])
```
通过上述步骤，我们可以确保最终的数据集中仅包含非赠品的商品项，从而提高数据质量，为后续的数据转换与写入阶段打下坚实基础。
#### 总结
本文详细介绍了如何通过轻易云数据集成平台调用聚水潭·奇门接口获取销售出库单，并对返回的数据进行初步清洗和加工。通过合理配置请求参数和过滤条件，我们能够高效地提取所需的业务数据，为后续的数据处理提供可靠支持。这一过程展示了轻易云平台在异构系统集成中的强大能力和灵活性。
### 使用轻易云数据集成平台将源数据转换并写入金蝶云星辰V2 API接口
在数据集成的生命周期中，ETL（提取、转换、加载）过程是至关重要的一环。本文将详细介绍如何使用轻易云数据集成平台，将源平台的销售出库单数据转换为金蝶云星辰V2 API接口所能接收的格式，并最终写入目标平台。
#### 1. 配置API接口
首先，我们需要配置金蝶云星辰V2 API接口的元数据。根据提供的元数据配置，我们可以看到该接口采用`POST`方法，路径为`/jdy/v2/scm/sal_out_bound`，并且需要进行ID检查（idCheck: true）。以下是具体的请求字段配置：
```json
{
"api": "/jdy/v2/scm/sal_out_bound",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{"field": "bill_source", "label": "单据来源，固定传入ISV", "type": "string", "describe": "单据来源，固定传入APP", "value": "ISV"},
{"field": "bill_date", "label": "出库日期,格式：2019-01-01", "type": "datetime", "describe": "出库日期,格式：2019-01-01", "value": "{pay_date}"},
{"field": "bill_no", "label": "单据编号", "type": "string", "describe": "单据编号", "value": "{io_id}"},
{"field": "customer_number", "label": "客户信息", "type": "string", "describe": "客户信息", "value": "{shop_id}"},
{"field": ...}
]
}
```
#### 2. 数据字段映射与转换
在ETL过程中，关键步骤是将源平台的数据字段映射到目标平台所需的字段，并进行必要的转换。以下是一些主要字段的映射和转换规则：
- **单据来源**：固定值为`ISV`。
- **出库日期**：从源数据中提取`pay_date`字段。
- **单据编号**：从源数据中提取`io_id`字段。
- **客户信息**：从源数据中提取`shop_id`字段。
- **商品分录**：这是一个数组类型，需要对每个商品条目进行处理。
对于商品分录中的每个子字段，例如商品编号、仓库、数量、单位、含税单价等，都需要根据具体业务逻辑进行转换。例如：
```json
{
...
{
field: 'material_number',
label: '商品',
type: 'string',
describe: '商品',
value: '{{items.i_id}}'
},
{
field: 'qty',
label: '数量',
type: 'string',
describe: '数量',
value: '_function case \'{{items.i_id}}\' when \'00191\' then \'{qty}\' else \'{{items.qty}}\'/1000 end'
},
...
}
```
#### 3. 特殊处理逻辑
在实际业务场景中，可能会遇到一些特殊处理逻辑。例如，对于不同商品ID，需要按照不同的规则计算数量和含税单价。这时可以使用条件表达式来实现：
```json
{
field: 'tax_price',
label: '含税单价',
type: 'string',
describe: '单价（如果在“系统参数”的“基础资料参数”中勾选了“商品价格为含税单价”，则price指示含税单价）',
value: '_function case \'{{items.i_id}}\' when \'574\' then \'{{items.sale_amount}}\'/\'{{items.qty}}\' else \'{{items.sale_amount}}\'/\'{{items.qty}}\'*1000 end'
}
```
#### 4. 数据写入目标平台
完成所有字段的映射和转换后，即可通过API接口将处理后的数据写入金蝶云星辰V2。使用轻易云数据集成平台，可以简化这一过程，通过可视化界面配置和实时监控，确保数据准确无误地传输到目标系统。
```json
{
method: 'POST',
url: '/jdy/v2/scm/sal_out_bound',
headers: {
'Content-Type': 'application/json'
},
data: transformedData
}
```
通过上述步骤，我们实现了从源平台到金蝶云星辰V2 API接口的数据ETL过程。这不仅提高了数据处理效率，也确保了业务流程的透明性和可追溯性。
