### 吉客云·奇门数据集成到用友BIP：技术实践分享
在企业信息化建设中，系统对接和数据集成是核心环节。本案例将详细探讨如何通过吉客云·奇门API将销售单数据高效地集成到用友BIP系统。我们的实际运行方案命名为“2B吉客云-销售单--->YS-销售出库单蓝字”，并已成功实施。这一过程展示了如何利用轻易云的数据集成平台，实现跨系统的无缝数据流转。
#### 系统对接概要
**源端**：
- **接口名称**：jackyun.tradenotsensitiveinfos.list.get
- **功能描述**：从吉客云·奇门获取不含敏感信息的销售订单列表，包括基础交易信息、商品详情等内容。
**目标端**：
- **接口名称**:/yonbip/scm/salesout/mergeSourceData/save
- **功能描述**：向用友BIP提交合并后的源数据信息，以生成相应的销售出库单记录。
#### 核心技术点概览
1. **高吞吐量写入能力**
- 实现大量订单快速导入，从而提升整体处理时效性。
2. **集中监控与告警**
- 通过实时跟踪任务状态和性能指标，确保每一步操作透明可见，并在异常情况发生时及时响应。
3. **自定义数据转换逻辑**
- 针对不同业务需求，将吉客云·奇门的数据格式灵活映射至用友BIP标准结构，以保证兼容性和准确性。
4. **分页与限流管理**
- 解决海量数据分页读取及调用频次限制的问题，有效防止因超负荷请求导致的服务拒绝。
5. **错误重试机制**
- 当出现网络故障或其他临时异常情况时，通过自动重试功能最大限度保证任务执行成功率。
基于以上核心技术特征，我们开创了一套智能高效的数据集成流程，使得企业能够从容应对复杂多变的数据交互需求。在本文后续章节中，我们将在具体实现步骤、代码示例以及实战经验上进行深入剖析，帮助读者更好地掌握相关技术要点。
### 调用吉客云·奇门接口获取并加工数据
在轻易云数据集成平台的生命周期中，调用源系统接口是至关重要的一步。本文将深入探讨如何通过调用吉客云·奇门接口`jackyun.tradenotsensitiveinfos.list.get`来获取并加工数据。
#### 接口配置与请求参数
在元数据配置中，接口的基本信息和请求参数已经详细列出。以下是关键参数及其配置：
- **API名称**: `jackyun.tradenotsensitiveinfos.list.get`
- **请求方法**: `POST`
- **分页配置**: 每页记录数为20
- **ID检查**: 启用
请求参数包括但不限于以下字段：
- `modified_begin` 和 `modified_end`: 修改起始时间和结束时间，必须同时存在且间隔不超过七天。
- `tradeNo`: 销售单号，可以传多个，用半角逗号分隔。
- `pageSize` 和 `pageIndex`: 分别表示每页记录数和页码。
- `startConsignTime` 和 `endConsignTime`: 发货时间区间，默认值分别为一天前和当前时间。
这些参数确保了我们能够灵活地控制数据的获取范围和分页处理。
#### 数据请求与清洗
在实际操作中，我们首先需要构建一个有效的API请求。以下是一个示例请求体：
```json
{
"modified_begin": "2023-09-01T00:00:00",
"modified_end": "2023-09-07T23:59:59",
"tradeNo": "12345,67890",
"pageSize": 20,
"pageIndex": 0,
"startConsignTime": "{{DAYS_AGO_1|datetime}}",
"endConsignTime": "{{CURRENT_TIME|datetime}}"
}
```
这个请求体指定了查询的时间范围、销售单号以及分页信息。通过这种方式，我们可以精确地控制要获取的数据量和范围。
#### 数据转换与写入
在获取到数据后，需要对其进行清洗和转换。根据元数据配置中的`fields`字段，我们可以选择性地提取需要的字段。例如：
```json
{
"fields": "tradeNo,postFee,otherFee,goodsDetail.goodsNo,goodsDetail.sellCount"
}
```
这些字段包括销售单号、邮费、其他费用以及商品详情等信息。在清洗过程中，可以根据业务需求对这些字段进行进一步处理，例如格式化日期、计算总费用等。
#### 条件过滤与自动填充
元数据配置中还包含了条件过滤和自动填充功能。例如，条件过滤可以确保只处理订单状态大于等于6000且店铺代码在指定列表中的记录：
```json
"condition":[
[
{"field":"tradeStatus","logic":"egt","value":"6000"},
{"field":"shopCode","logic":"in","value":"NBKH,ZYDP,BJKH,TYKH,HWKH,HYKH,XSKH,XXKH,CTQD0001"}
]
]
```
自动填充功能则可以根据预定义规则自动补全某些字段值，提高数据处理效率。
#### 异常处理与补偿机制
为了确保数据集成过程的可靠性，平台提供了异常处理与补偿机制。例如，通过定时任务（crontab）来定期检查并补偿遗漏的数据：
```json
"omissionRemedy":{
"crontab":"20 */2 * * *",
"takeOverRequest":[
{"field":"startConsignTime","value":"{{HOURE_AGO_5|datetime}}"},
{"field":"endConsignTime","value":"{{CURRENT_TIME|datetime}}"}
]
}
```
这种机制确保即使在网络波动或系统故障情况下，也能及时恢复并补偿丢失的数据。
通过以上步骤，我们可以高效地调用吉客云·奇门接口获取并加工所需的数据，为后续的数据转换与写入打下坚实基础。这种全面而细致的操作流程不仅提高了业务透明度，还极大提升了数据处理效率。
### 轻易云数据集成平台：将销售单数据转换并写入用友BIPAPI接口
在轻易云数据集成平台中，完成数据生命周期的第二步——将已经集成的源平台数据进行ETL转换，并写入目标平台用友BIPAPI接口，是一个关键环节。本文将详细介绍如何利用元数据配置，将2B吉客云的销售单数据转换为用友BIPAPI接口所能接收的格式，并成功写入目标平台。
#### 数据请求与清洗
在进行ETL转换之前，首先需要从源系统获取销售单的数据，并对其进行清洗和预处理。这一步骤确保了数据的准确性和一致性，为后续的转换和写入奠定基础。
#### 数据转换与写入
接下来，我们重点关注如何使用提供的元数据配置，将清洗后的销售单数据转换为用友BIPAPI接口所需的格式，并通过API接口将其写入目标系统。
元数据配置如下：
```json
{
"api": "/yonbip/scm/salesout/mergeSourceData/save",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{"field":"mergeSourceData","label":"是否合并上游数据","type":"string","describe":"是否合并上游数据。值为true的话则sourceid：来源单据主表id，sourceautoid：来源单据行id，makeRuleCode：单据转换规则，_status：操作标识，不可为空。 示例：true","value":"true"},
{"field":"vouchdate","label":"单据日期","type":"string","describe":"单据日期 示例：2020-11-30 00:00:00","value":"{consignTime}"},
{"field":"warehouse","label":"仓库id或编码","type":"string","describe":"仓库id或编码 示例：Z001","value":"{warehouseCode}"},
{"field":"bizFlow","label":"bizFlow","type":"string","value":"1082e4bb-38e0-494f-8728-778fd4ab6307"},
{"field":"bizFlow_version","label":"bizFlow_version","type":"string","value":"V1.0"},
{"field":"code","label":"单据编号","type":"string","describe":"单据编号 示例:XSCK20201130000002 自动编码可以不携带","value":"{orderNo}"},
{"field":"bustype","label":"交易类型id或编码","type":"string","describe":"交易类型id或编码 示例:A30001","value":"1622818252411895944"},
{
"field": "details",
"label": "销售出库单子表",
"type": "array",
"describe": "销售出库单子表[st.salesout.SalesOuts]",
"value": "goodsDetail",
"children": [
{"field": "_status", "label": "操作标识", "type": "string", "describe": "Insert:新增 示例：Insert", "value": "Insert"},
{"field": "qty", "label": "数量", "type": "string", "value": "{{goodsDetail.sellCount}}"},
{"field": "sourceid",
"label":
"来源单据主表id",
"type":
"string",
"value":
"_mongoQuery 965d8d1e-5838-3165-a1a0-1dcd598eeb96 findField=content.new_id where={\"content.code\":{\"$eq\":\"{onlineTradeNo}\"}}"
},
{
"field":
"sourceautoid",
"label":
"来源单据行id",
"type":
"string",
"value":
"_mongoQuery 965d8d1e-5838-3165-a1a0-1dcd598eeb96 findField=content.new_orderDetailId where={\"content.code\":{\"$eq\":\"{onlineTradeNo}\"},\"content.skuCode\":{\"$eq\":\"{{goodsDetail.goodsNo}}\"},\"content.new_oriTaxUnitPrice\":{\"$eq\":\"{{goodsDetail.sellPrice}}\"}}"
},
{
"field":
"batchno",
"label":
"批次号",
"type":
"string",
"describe":
"仓库商品均开启批次管理则必填",
"value":
"_function case _findCollection find detail.batchManage from 7aed2c28-cc02-35c8-aa6a-2d750373f9e1 where code={goodsNo} _endFind when false then '' else '001' end"
},
{
"field":
"makeRuleCode",
"label":
"单据转换规则",
"type":
"string",
"describe":
"deliveryTostoreout：发货单生销售出库，salereturnTosalesout：退货单生销售出库，orderTosalesout：销售订单生销售出库",
"value":
"orderTosalesout"
},
{
“字段”：
“salesOutsSNs”，
“标签”：
“销售出库孙表”，
“类型”：
“数组”，
“值”：
“sns”，
“孩子”：
{
“字段”：
“_status”，
“标签”：
“操作标识”，
“类型”：
“字符串”，
“描述”：
“插入：新增”，
“值”：
“插入”
}
]
},
{
"_status",
label:
操作标识, Insert:新增 示例：Insert,
value: Insert
}
],
enforcedAssociation: true,
buildModel: true
}
```
#### 元数据配置解析
##### 基本字段配置
1. **mergeSourceData**:
- 字段描述：“是否合并上游数据”
- 类型：“字符串”
- 示例值：“true”
2. **vouchdate**:
- 字段描述：“单据日期”
- 类型：“字符串”
- 示例值：“2020-11-30 00:00:00”
3. **warehouse**:
- 字段描述：“仓库ID或编码”
- 类型：“字符串”
- 示例值：“Z001”
4. **code**:
- 字段描述：“单据编号”
- 类型：“字符串”
- 示例值：“XSCK20201130000002”
##### 子表字段配置
1. **details**:
- 字段描述：“销售出库单子表”
- 类型：“数组”
2. **_status**:
- 字段描述：“操作标识”
- 类型：“字符串”
- 示例值：“Insert”
3. **qty**:
- 字段描述：“数量”
- 类型：“字符串”
4. **sourceid**:
- 字段描述：“来源单据主表ID”
5. **sourceautoid**:
- 字段描述：“来源单据行ID”
6. **batchno**:
- 字段描述：“批次号”
7. **makeRuleCode**:
- 字段描述：“单据转换规则”
##### 孙表字段配置
1. **salesOutsSNs**:
- 字段描述：“销售出库孙表”
2. **sn**:
- 字段描述：“序列号”
#### 数据写入过程
在完成上述字段的映射和配置后，通过POST方法调用`/yonbip/scm/salesout/mergeSourceData/save` API接口，将处理后的数据提交到用友BIP系统。确保每个字段的数据都符合目标系统的要求，以实现无缝的数据对接。
通过这种方式，可以高效地将2B吉客云中的销售订单转化为用友BIP系统能够接受的格式，实现跨系统的数据集成和业务流程自动化。
