### 聚水潭·奇门数据集成到金蝶云星空：销售出库单同步案例分享
在系统对接项目中，如何高效地将聚水潭·奇门（以下简称“奇门”）的销售订单数据同步至金蝶云星空平台（以下简称“金蝶”），是一个典型而复杂的问题。本文将针对这一问题，详细介绍在轻易云数据集成平台上配置与实现此方案的具体技术过程。
为了确保从奇门获取的数据能够无缝写入到金蝶，我们首先需要解决以以下几项关键技术挑战：
1. **定时可靠抓取接口数据**：
使用`jushuitan.saleout.list.query`接口从奇门系统中抓取最新的销售出库单。通过设置合理的调度策略，实现定时任务，以确保数据信息不漏单、不错失。
2. **处理分页和限流问题**：
奇门的API调用通常会涉及分页和限流，为了有效处理大批量数据，需要设计一种稳健的方法来逐步获取所有待处理订单，并且避免因超额调用导致被限速或封禁。
3. **快速写入大量数据**：
收集到所需的数据后，通过使用金蝶提供的`batchSave` API，将这些订单信息批量快速导入至金蝶系统中。这不仅提高了传输效率，还减少了网络延迟带来的影响。
4. **应对格式差异与异常机制**:
不同系统间的数据格式常有较大差异，因此实现自定义映射与转换尤为重要。此外，应完善异常处理机制，当出现错误时自动重试提交操作，以保证业务的不间断进行。
5. **实时监控与日志记录**:
配置实时监控功能以及详细日志记录，以便运维人员及时发现并解决潜在问题，有效提升整个流程透明度和可追溯性。
下面我们具体展开上述几个步骤，在实际实施过程中我们还会遇到哪些细节问题，以及怎样利用轻易云平台更好地完成这项工作。
### 调用聚水潭·奇门接口获取并加工销售出库单数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将深入探讨如何通过轻易云数据集成平台调用聚水潭·奇门接口`jushuitan.saleout.list.query`，并对获取的数据进行加工处理。
#### 接口调用配置
首先，我们需要配置接口调用的元数据。根据提供的metadata，我们可以看到该接口使用POST方法，主要参数包括页数、每页行数、修改开始时间、修改结束时间、单据状态和线上单号。
```json
{
"api": "jushuitan.saleout.list.query",
"method": "POST",
"number": "io_id",
"id": "io_id",
"pagination": {
"pageSize": 25
},
"idCheck": true,
"request": [
{
"field": "page_index",
"label": "页数",
"type": "string",
"describe": "第几页，从第一页开始，默认1",
"value": "1"
},
{
"field": "page_size",
"label": "每页行数",
"type": "string",
"describe": "每页多少条，默认25，最大50",
"value": "50"
},
{
"field": "start_time",
...
}
]
}
```
#### 参数设置
- `page_index`：用于分页请求，从第一页开始。
- `page_size`：每页返回的数据条数，默认值为25。
- `start_time`和`end_time`：用于指定数据的时间范围，这两个参数必须同时存在且时间间隔不能超过七天。
- `status`：指定单据状态，此处我们选择已出库的状态（Confirmed）。
这些参数确保了我们能够精确地获取所需的数据，并且通过分页机制可以处理大量数据。
#### 数据请求与清洗
在实际操作中，我们会根据业务需求动态设置这些参数。例如，通过模板变量设置时间范围：
```json
{
...
{
"field": "start_time",
...
"value":"{{LAST_SYNC_TIME|datetime}}"
},
{
...
...
...
}
```
这样可以确保每次同步时都能获取到最新的数据。
#### 数据转换与写入
在获取到原始数据后，需要对其进行清洗和转换，以便后续写入目标系统。假设我们需要过滤掉数量为0的记录，可以通过以下条件实现：
```json
"condition":[[{"field":"items.qty","logic":"gt","value":"0"}]]
```
这个条件确保了只有数量大于0的记录才会被保留。
#### 异常处理与补偿机制
为了保证数据同步的可靠性，我们还需要设置异常处理和补偿机制。例如，通过定时任务（crontab）来定期检查并补偿遗漏的数据：
```json
"omissionRemedy":{
...
{"crontab":"2 5 * * *"}
}
```
这个配置表示每天凌晨5点2分执行一次补偿任务，确保任何遗漏的数据都能被及时同步。
#### 实际案例应用
假设我们在某个项目中需要同步过去三天内所有已出库的销售订单，可以通过以下配置实现：
```json
{
...
{
...
{"field":"start_time","value":"{{DAYS_AGO_3|datetime}}"},
{"field":"end_time","value":"{{CURRENT_TIME|datetime}}"},
{"field":"status","value":"Confirmed"}
}
}
```
这种灵活的配置方式使得我们能够根据具体需求调整同步策略，从而确保数据的一致性和完整性。
综上所述，通过合理配置聚水潭·奇门接口调用参数，并结合轻易云数据集成平台提供的强大功能，我们能够高效地完成销售出库单数据的同步与加工。这不仅提升了业务透明度，也极大地提高了工作效率。
### 使用轻易云数据集成平台将销售出库单同步至金蝶云星空API接口
在数据集成生命周期的第二步，我们需要将已经集成的源平台数据进行ETL转换，并转为目标平台金蝶云星空API接口所能够接收的格式，最终写入目标平台。本文将详细介绍如何利用轻易云数据集成平台完成这一任务。
#### 配置元数据
首先，我们需要根据元数据配置来设置API接口参数。以下是元数据配置的详细信息：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 20,
"method": "batchArraySave"
},
"request": [
{"field":"FBillTypeID","label":"单据类型","type":"string","describe":"单据类型","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"XSCKD01_SYS"},
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","value":"{io_id}"},
{"field":"FDate","label":"日期","type":"string","describe":"日期","value":"{io_date}"},
{"field":"FSaleOrgId","label":"销售组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"100"},
{"field":"FCustomerID","label":"客户","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{shop_id}"},
{"field":"FCarriageNO","label":"运输单号","type":"string","describe":"文本","value":"{l_id}"},
{"field":"FStockOrgId","label":"发货组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"}},
{"field":"FLinkPhone","label":"联系电话","type":"string","describe":""},
{"field": "FLinkMan", "label": "收货人姓名", "type": "string", "describe": ""},
{"field": "FReceiveAddress", "label": "收货方地址", "type": "string", "describe": ""},
{
"field": "FEntity",
"label": "明细信息",
"type": "array",
"children": [
{"field": "FMaterialID", "label": "物料编码", "type": "string",
"describe": "",
"parser":{"name":
"ConvertObjectParser",
"params":
"FNumber"},
"value":
"{{items.i_id}}"
},
{"parent":
"FEntity",
"label":
"实发数量",
"field":
"FRealQty",
"type":
"string",
"value":
"{{items.qty}}"
},
{
...
}
],
...
},
{
...
}
],
...
}
```
#### 数据转换与写入
1. **API 接口配置**：
- `api` 字段指定了调用的 API 接口名称，这里为 `batchSave`。
- `method` 字段指定了 HTTP 请求方法，这里为 `POST`。
2. **请求参数配置**：
- 每个请求字段都包含 `field`, `label`, `type`, `describe`, 和 `value` 等属性。
- 使用 `parser` 对某些字段进行特定转换，例如：`FBillTypeID` 和 `FSaleOrgId` 使用了 `ConvertObjectParser`，并传递了参数 `FNumber`。
3. **嵌套数组和对象**：
- 在请求参数中，有些字段是嵌套数组或对象，例如：`FEntity` 和 `SubHeadEntity`。
- 对于嵌套数组，需要使用 `"children"` 字段定义其内部结构。例如，`FEntity` 包含多个子字段，如 `FMaterialID`, `FTaxPrice`, 和 `FAmount` 等。
4. **动态值映射**：
- 使用 `{}` 和 `{{}}` 来引用动态值。例如， `{io_id}` 映射到输入数据中的订单编号，`{{items.i_id}}` 映射到物料编码。
- 特殊处理逻辑可以通过 `_function case ... end` 实现，例如：判断是否赠品。
5. **其他请求参数**：
- 除了主要的业务数据，还需要一些额外的请求参数，如表单 ID (`FormId`) 和操作类型 (`Operation`) 等。这些参数确保 API 调用能够正确执行。
#### 实际应用案例
假设我们有以下源平台的数据：
```json
{
...
}
```
通过轻易云数据集成平台，我们将这些源数据转换为目标格式，并通过上述配置发送到金蝶云星空 API 接口。具体步骤如下：
1. **读取源数据**：从源系统中提取销售出库单的数据。
2. **数据清洗与转换**：根据元数据配置，将源数据清洗并转换为目标格式。
3. **发送 API 请求**：使用 HTTP POST 方法，将转换后的数据发送到金蝶云星空的 API 接口。
通过这种方式，我们可以实现不同系统间的数据无缝对接，确保业务流程顺畅运行。
