### 聚水潭其他入库（线下退货）对接金蝶销售退货实战案例
在本技术案例中，我们重点解析如何通过轻易云数据集成平台，将聚水潭的其他入库（线下退货）数据无缝对接至金蝶云星空，具体场景为处理聚水潭中的other.inout.query接口获取的退货数据，并批量写入到金蝶云星空销售退货模块(batchSave)中。
首先，我们需要解决以下几个关键技术点：
#### 1. 接口调用与数据抓取
为了确保从聚水潭系统中精准、及时地获取线下退货的数据，需要定期可靠地调用其提供的`other.inout.query` API。我们将设计一个调度任务，以固定时间间隔抓取最新的数据。同时，为了应对分页和限流问题，将实现多次请求组合完整返回结果集，防止数据遗漏。
#### 2. 数据转换与映射
由于聚水潭与金蝶云星空的数据结构不同，在实际操作过程中必须进行自定义的数据转换。利用轻易云平台提供的可视化数据流设计工具，可以直观且高效地完成这一过程。在此步骤中，将把从聚水潭拉取到的原始JSON格式转为符合金蝶要求的数据结构，以便后续写入操作。
#### 3. 高吞吐量写入能力
针对大量涌入的数据，为保证时效性和准确性，轻易云平台支持高吞吐量的批量写入功能。这种能力允许我们在短时间内将大批次数据一并导入到金蝶系统，有效提升整体流程效率。此外，通过实时监控和日志记录功能，可全程追踪每个节点上的性能状况及处理状态，一旦发生异常则自动告警。
#### 4. 异常处理机制
在对接过程中，不可避免会出现网络波动、API限制等导致连接失败或部分数据未成功推送的问题。因此需要构建健壮的错误重试机制：当检测到某一次API调用失败时，会触发相应重试逻辑；同时也会记录详细日志以供进一步诊断分析，同时保持整个流程顺畅运作。
通过以上四个主要环节，从接口调用开始，到最终成功推送至目标系统，每一步都做到规范严谨，这样才能真正实现两大业务系统之间稳定、高效的信息传递。
### 调用聚水潭接口other.inout.query获取并加工数据
在轻易云数据集成平台的生命周期中，第一步是调用源系统接口获取数据。本文将详细探讨如何通过调用聚水潭接口`other.inout.query`来获取并加工数据，以实现与金蝶销售退货系统的对接。
#### 接口配置与请求参数
首先，我们需要配置接口的元数据。根据提供的元数据配置，`other.inout.query`接口使用POST方法进行调用，主要参数包括修改时间范围、单据类型、单据状态等。以下是具体的请求参数配置：
```json
{
"api": "other.inout.query",
"method": "POST",
"number": "io_id",
"id": "io_id",
"pagination": {
"pageSize": 50
},
"idCheck": true,
"request": [
{
"field": "modified_begin",
"label": "修改起始时间",
"type": "string",
"value": "{{LAST_SYNC_TIME|datetime}}"
},
{
"field": "modified_end",
"label": "修改结束时间",
"type": "string",
"value": "{{CURRENT_TIME|datetime}}"
},
{
"field": "so_ids",
"label": "指定线上订单",
"type": "string"
},
{
"field": "types",
"label": "单据类型",
"type": "string",
"describe": "单据类型 :其它退货,其它出库,其它进仓"
},
{
"field": "status",
"label": "单据状态",
"type": "string",
"describe":"单据状态，Confirmed=生效，WaitConfirm待审核，Archive=归档，Cancelled=取消",
“value”: “Confirmed”
},
{
“field”: “page_index”,
“label”: “开始页码”,
“type”: “string”,
“value”: “1”
},
{
“field”: “page_size”,
“label”: “每页行数”,
“type”: “string”,
“value”: "{PAGINATION_PAGE_SIZE}"
}
],
...
}
```
#### 数据请求与清洗
在调用接口时，我们需要特别注意时间范围和分页参数。`modified_begin`和`modified_end`分别表示数据的起始和结束时间，这两个参数通常使用上次同步时间和当前时间来动态生成。此外，分页参数`page_index`和`page_size`确保我们能够逐页获取大批量的数据。
通过上述配置，我们可以发送一个POST请求到聚水潭API以获取符合条件的数据。以下是一个示例请求：
```json
{
“modified_begin”:“2023-01-01T00:00:00Z”,
“modified_end”:“2023-01-31T23:59:59Z”,
“types”:“其它退货”,
“status”:“Confirmed”,
“page_index”:“1”,
“page_size”:“50”
}
```
#### 数据转换与写入
在成功获取数据后，需要对数据进行清洗和转换，以便写入目标系统。在这个案例中，我们需要将聚水潭的其他入库（线下退货）数据转换为金蝶销售退货的数据格式。
例如，对于每一条记录，我们可能需要提取并转换以下字段：
- `io_id`: 聚水潭中的唯一标识符，需要映射到金蝶系统中的相应字段。
- `so_id`: 销售订单ID，需要进行格式化处理。
- `drop_co_name`: 固定值为"销售退货"，用于标识业务类型。
清洗和转换后的数据可以通过轻易云平台的内置工具进行处理，然后写入到金蝶系统中。
#### 条件过滤
为了确保只处理符合特定条件的数据，可以使用元数据中的条件过滤配置。例如：
```json
"condition":[
[
{"field":"drop_co_name","logic":"eq","value":"销售退货"},
{"field":"type","logic":"eq","value":"其它退货"},
{"field":"so_id","logic":"like","value":"THTZ"}
]
]
```
以上条件确保只处理业务类型为"销售退货"且单据类型为"其它退货"的数据，同时筛选出订单ID包含"THTZ"的记录。
通过以上步骤，我们能够高效地调用聚水潭接口获取所需数据，并进行必要的清洗和转换，以实现与金蝶销售退货系统的无缝对接。这不仅提高了数据处理效率，还确保了业务流程的透明度和准确性。
### 轻易云数据集成平台：ETL转换与写入金蝶云星空API接口
在轻易云数据集成平台中，数据处理的第二步是将已经集成的源平台数据进行ETL转换，并转为目标平台金蝶云星空API接口所能够接收的格式，最终写入目标平台。本文将详细探讨这一过程中的技术细节和实现方式。
#### API接口配置
在进行ETL转换时，首先需要配置好金蝶云星空的API接口。根据提供的元数据配置，我们使用`batchSave`接口，通过POST方法提交数据。以下是具体的配置细节：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 1,
"method": "batchArraySave"
},
"request": [
{"field":"FBillTypeID","label":"单据类型","type":"string","describe":"单据类型","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"XSTHD01_SYS"},
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","value":"{io_id}"},
{"field":"FSaleOrgId","label":"销售组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"_findCollection find FSALEORGID_Fnumber from 9927cdb8-2b99-31f1-a379-964ddc5c777f where FBillNo={so_id}"},
{"field":"FDate","label":"日期","type":"string","describe":"日期","value":"{modified}"},
{"field":"FStockOrgId","label":"库存组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"100"},
{"field":"FRetcustId","label":"退货客户","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"_findCollection find FRETCUSTID_Fnumber from 9927cdb8-2b99-31f1-a379-964ddc5c777f where FBillNo={so_id}"},
{"field":"FHeadNote","label":"备注","type":null,"describe":null},
{"field": ... }
],
...
}
```
#### 数据转换与解析
在数据转换过程中，需确保每个字段的数据格式符合金蝶云星空API的要求。以下是几个关键字段及其解析方式：
1. **FBillTypeID（单据类型）**：
- 使用`ConvertObjectParser`进行解析，将内部编码转换为金蝶系统识别的编码。
- 配置示例：`"parser":{"name": "ConvertObjectParser", "params": "FNumber"}, "value": "XSTHD01_SYS"`
2. **FSaleOrgId（销售组织）**：
- 从源系统中查找对应的销售组织编码，并通过`_findCollection`函数进行映射。
- 配置示例：`"value": "_findCollection find FSALEORGID_Fnumber from ... where FBillNo={so_id}"`
3. **FRetcustId（退货客户）**：
- 类似于销售组织，从源系统中查找对应的退货客户编码。
- 配置示例：`"value": "_findCollection find FRETCUSTID_Fnumber from ... where FBillNo={so_id}"`
4. **FEntity（明细信息）**：
- 明细信息是一个数组，其中每个元素代表一条具体的物料信息。
- 配置示例：
```json
{
"field": "FEntity",
"label": "明细信息",
"type": "array",
...
"children":[
{
"field": "FMaterialId",
...
"value": "{{items.sku_id}}"
},
...
]
}
```
#### 数据写入
在完成数据转换后，将数据通过POST请求写入到金蝶云星空API接口中。以下是一个简化的请求示例：
```json
{
"FormId": "SAL_RETURNSTOCK",
...
"Model":{
...
// 主表信息
...
// 明细表信息
...
}
}
```
其中，`FormId`表示业务对象表单ID，例如销售退货单为`SAL_RETURNSTOCK`。主表和明细表的信息按照前述配置逐一填充。
#### 自动提交与审核
为了提高效率，可以配置自动提交并审核功能：
```json
{
...
"IsAutoSubmitAndAudit": true,
...
}
```
这将确保在数据写入后，系统会自动提交并审核该单据，无需人工干预。
#### 验证基础资料有效性
为了确保所有基础资料字段的数据有效性，可以启用验证功能：
```json
{
...
"IsVerifyBaseDataField": false,
...
}
```
设置为false表示不验证所有基础资料字段的数据有效性，根据实际需求可以调整此参数。
通过上述步骤和配置，可以实现从源平台到金蝶云星空API接口的数据无缝对接和写入。这不仅提高了数据处理效率，还确保了数据的一致性和准确性。
