### 系统对接集成案例分享：吉客云·奇门数据集成到金蝶云星空
在当前高度信息化和复杂的商业环境中，高效、可靠的系统对接已成为企业运营的重要组成部分。本案例将详细介绍如何通过轻易云数据集成平台，实现吉客云·奇门的数据无缝对接至金蝶云星空，特别针对“销售单对接销售出库_类型2代发货(来自分销商)_容错”方案。
1. **确保吉客云·奇门数据不漏单**
集成过程中，为了防止遗漏订单，我们首先调用`jackyun.tradenotsensitiveinfos.list.get` API接口。这一接口支持分页获取订单信息，使我们能够全面覆盖所有订单。为处理限流问题，系统内置了重试机制，在请求频率达到限制时，可以按需延迟并重新发起。
2. **大量数据快速写入到金蝶云星空**
数据提取完成后，下一个关键步骤是将这些数据信息高效地批量写入金蝶云星空。利用其提供的`batchSave` API接口，我们能够实现大容量的数据快速同步。在此过程中，通过轻易运用批处理技术，提高整体操作效率，并减少服务器压力。
3. **定时抓取与实时监控**
为保证数据更新及时性和准确性，采用定时任务调度器，每隔固定时间间隔自动抓取新产生或修改过的订单。此外，通过配置实时监控模块，对整个数据处理过程进行全程记录和追踪，方便后期审查及异常排查。
4. **应对分页与限流问题**
吉客云·奇门API具有分页功能，以确保一次请求不会超出带宽限制。同时，根据实际运行情况制定合理的限流策略，以避免因过多请求导致被封禁。一旦出现错误，还可以借助内建容错机制进行自动恢复尝试，提高系统稳定性。
5. **解决数据格式差异**
不同系统之间经常存在着各种各样的数据格式差异。为了平滑过渡，必须先针对二者的数据结构做详细分析，然后使用自定义映射规则，将来源端（吉客云·奇门）的字段准确转换为目标端（金蝶云星空）所需字段。这不仅包括基本字段匹配，还涉及复杂数值计算以及特殊字符过滤等细节优化。
6. **异常处理与错误重试机制**
在实际业务操作中，不可避免会遇到各种故障情形。如网络波动、临时服务不可用等，此刻异常检测及响应尤为重要。具体实施方面，可以预设失败重试次数，同时记日志并发送告警通知，为
### 使用轻易云数据集成平台调用吉客云·奇门接口获取并加工数据
在数据集成的生命周期中，第一步是从源系统获取数据。本文将详细介绍如何通过轻易云数据集成平台调用吉客云·奇门接口`jackyun.tradenotsensitiveinfos.list.get`来获取并加工销售单数据。
#### 接口配置与请求参数
首先，我们需要配置接口的元数据，以确保请求参数的正确性和完整性。以下是该接口的元数据配置：
```json
{
"api": "jackyun.tradenotsensitiveinfos.list.get",
"method": "POST",
"number": "tradeNo",
"id": "tradeId",
"pagination": {
"pageSize": 20
},
"idCheck": true,
"condition": [
[
{
"field": "tradeStatus",
"logic": "egt",
"value": "6000"
}
]
],
"request": [
{"field":"modified_begin","label":"起始时间","type":"string","describe":"修改起始时间，和结束时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空"},
{"field":"modified_end","label":"结束时间","type":"string","describe":"修改结束时间，和起始时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空"},
{"field":"startModified","label":"最后修改时间（起始）","type":"string"},
{"field":"endModified","label":"最后修改时间（截止）","type":"string"},
{"field":"tradeNo","label":"销售单号，多个用半角逗号分隔","type":"string"},
{"field":"pageSize","label":"每页记录数，默认50，最大200","type":"string","value":"200"},
{"field":"pageIndex","label":"页码，0为第1页","type":"string"},
{"field":"hasTotal","label":"默认返回，首次调用时可以传1获取总记录数","type":"string","value":"1"},
{"field":"startCreated","label":"创建时间（起始）","type":"string"},
{"field":"endCreated","label":"创建时间（截止）","type":"string"},
{"field":"startAuditTime","label":"审核时间（起始）","type":"string"},
{"field":"endAuditTime","label":"审核时间（截止）","type":"string"},
{"field":"startConsignTime","label":"发货时间（起始）","type":"string", "value": "_function from_unixtime(({CURRENT_TIME}-86400),'%Y-%m-%d 00:00:00')"},
{"field":"endConsignTime","label":"发货时间（截止）","type":"string", "value": "_function from_unixtime(({CURRENT_TIME}-86400),'%Y-%m-%d 23:59:59')"},
{"field":"tradeStatus","label":"订单状态","type":"string"},
{"field":"tradeType","label":"订单类型", "type": "string", "value": "2"},
{"field": "sourceTradeNos", "label": "网店订单号", "type": "string"},
{
...
// 此处省略部分字段以保持简洁
...
}
],
...
}
```
#### 请求示例
根据上述元数据配置，我们可以构建一个请求示例：
```json
{
"modified_begin": "",
"modified_end": "",
...
}
```
在实际操作中，我们需要根据具体需求填充这些字段。例如，如果我们需要获取最近一天内的销售单信息，可以设置`startConsignTime`和`endConsignTime`为当前日期前一天的开始和结束时间。
#### 数据清洗与转换
在获取到原始数据后，需要进行清洗和转换，以便后续处理。以下是一些常见的数据清洗与转换操作：
1. **字段映射**：将源系统中的字段映射到目标系统中的字段。例如，将`tradeNo`映射到目标系统中的`orderNumber`。
2. **数据格式转换**：将日期格式从字符串转换为标准日期格式。
3. **过滤无效数据**：移除不符合业务规则的数据，例如状态不为6000的订单。
#### 容错机制
为了确保数据集成过程的可靠性，我们需要实现容错机制。以下是一些常见的容错策略：
1. **重试机制**：在请求失败时自动重试。
2. **错误日志记录**：记录所有错误信息，以便后续分析和处理。
3. **部分成功处理**：即使部分数据处理失败，也要确保其他成功的数据能够继续处理。
通过以上步骤，我们可以高效地从吉客云·奇门接口获取并加工销售单数据，为后续的数据处理和分析打下坚实基础。
### 轻易云数据集成平台生命周期第二步：ETL转换与写入金蝶云星空API接口
在数据集成的过程中，ETL（Extract, Transform, Load）转换是一个关键步骤。本文将详细探讨如何将源平台的数据通过轻易云数据集成平台进行ETL转换，并最终写入到金蝶云星空的API接口中。
#### 数据请求与清洗
在数据请求与清洗阶段，我们已经从源系统获取了原始数据，并进行了初步的清洗和整理。这些数据需要进一步转换为金蝶云星空API接口所能接收的格式。
#### 配置元数据
元数据配置是ETL过程中的重要环节。以下是我们针对销售单对接销售出库（类型2代发货）的元数据配置：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 10,
"method": "batchArraySave"
},
"request": [
{"field":"FBillTypeID","label":"单据类型","type":"string","describe":"单据类型","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"XSCKD01_SYS"},
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","value":"{tradeNo}"},
{"field":"FDate","label":"日期","type":"string","describe":"日期","value":"{consignTime}"},
{"field":"FSaleOrgId","label":"销售组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"_mongoQuery 38faaa66-9955-34e5-bd58-7c4099b53af5 findField=content.warehouseCompanyCode where={\"content.warehouseCode\" : {\"$eq\":\"{warehouseCode}\"}}"},
{"field":"FStockOrgId","label":"库存组织","type":"string","describe":"多类别基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"_mongoQuery 38faaa66-9955-34e5-bd58-7c4099b53af5 findField=content.warehouseCompanyCode where={\"content.warehouseCode\" : {\"$eq\":\"{warehouseCode}\"}}"},
{"field":"FOwnerIdHead","label":"货主","type":"string","describe":"多类别基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"_mongoQuery 38faaa66-9955-34e5-bd58-7c4099b53af5 findField=content.warehouseCompanyCode where={\"content.warehouseCode\" : {\"$eq\":\"{warehouseCode}\"}}"},
{"field":"FCustomerID","label":"客户","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{shopCode}"},
{"field":"FNote","label":"备注","type": "string", "describe": "多行文本", "value": "{sellerMemo}"},
{"field": "F_LSJC_Text", "label": "关联单号", "type": "string", "describe": "多行文本", "value": "{tradeNo}"},
{"field": "F_LSJC_Text1", "label": "来源单号", "type": "string", "describe": "多行文本"},
{"field": "F_LSJC_Text2", "label": "收货单号", "type": "string", "describe": "多行文本"},
{"field": "F_LSJC_Text4", "label": "入库类型", "type": "", describe: "", value: "{tradeType}"},
{"field": F_LSJC_Text11, label: "", type: "", describe: ""},
{
field: FEntity,
label: 明细信息,
type: array,
children: [
{
field: FMaterialId,
label: 物料编码,
type: string,
describe: 基础资料,
parser: { name: ConvertObjectParser, params: FNumber },
value: {{ goodsDetail.goodsNo }},
parent: FEntity
},
{
field: FRealQty,
label: 实退数量,
type: string,
describe: 数量,
value: {{ goodsDetail.sellCount }},
parent: FEntity
},
{
field: Flot,
label: 批号,
type: string,
describe: 批号,
value: 01,
parent: FEntity,
parser:{ name:"ConvertObjectParser", params:"FNumber"}
},
{
field:FPrice,label:"单价",type:"string",describe:"单价",
value:"_function round(({{goodsDetail.shareFavourableAfterFee}}\/{{goodsDetail.sellCount}}),4)",parent:"FEntity"
},
{
field:"FAmount",
label:"金额",
type:"string",
describe:"金额",
value:"{{goodsDetail.shareFavourableAfterFee}}",
parent:"FEntity"
},
{
field:FStockId,label:"仓库",type:string,describe:"基础资料",
parser:{ name:"ConvertObjectParser" , params :"FNumber"},
value:_mongoQuery 38faaa66-9955-34e5-bd58-7c4099b53af5 findField=content.warehouseCompanyCode where={"content.warehouseCode" : {$eq:{warehouseCode}}},
parent:FEntity
},
{
field:FEntrynote,label:"备注" , type:string , describe :"文本" ,
value:{goodsMemo},parent:FEntity
}
],
value : goodsDetail
}
],
otherRequest:[
{ field :"FormId" , label :"业务对象表单Id" , type :"string" , describe :"必须填写金蝶的表单ID如:PUR_PurchaseOrder" , value :"SAL_OUTSTOCK" } ,
{ field :"Operation" , label :"执行的操作" , type :"string" , value :"Save"} ,
{ field :"IsAutoSubmitAndAudit" , label :"提交并审核" , type :"bool" , value:true},
{ field :IsVerifyBaseDataField,label :验证基础资料,type :bool,describe :是否验证所有的基础资料有效性，布尔类，默认false（非必录）,value:true},
{ field :SubSystemId,label :系统模块,type:string,describe :默认仓库模块,value :21},
{ label :允许负库存,field :InterationFlags,type:string,value :'STK_InvCheckResult'},
{ label :'服务端开启的线程数',field :'BatchCount',type :'string',value :'5'}
]
}
```
#### 数据转换
1. **字段映射**：使用`ConvertObjectParser`进行字段值的转换。例如，将`FBillTypeID`字段映射为金蝶系统识别的值`XSCKD01_SYS`。
2. **动态查询**：利用`_mongoQuery`动态查询并填充字段值，如`FSaleOrgId`, `FStockOrgId`, `FOwnerIdHead`, `FStockId`等。
3. **计算字段**：使用函数计算字段值，例如计算商品单价时使用了 `_function round(({{goodsDetail.shareFavourableAfterFee}}/{{goodsDetail.sellCount}}),4)`。
4. **嵌套结构**：处理复杂嵌套结构，如明细信息（`FEntity`），包含多个子字段和子对象。
#### 数据写入
通过配置好的元数据，调用金蝶云星空API接口进行数据写入。以下是具体操作步骤：
1. **准备请求体**：根据元数据配置生成符合API要求的JSON请求体。
2. **调用API**：使用HTTP POST方法调用金蝶云星空的`batchSave` API接口。
3. **错误处理**：启用容错机制，确保在发生错误时能够捕获并处理，例如记录日志或重试机制。
#### 实践案例
假设我们有一笔订单，其原始数据如下：
```json
{
tradeNo: '123456',
consignTime:'2023-10-01',
warehouseCode:'WH001',
shopCode:'SHOP001',
sellerMemo:'紧急订单',
tradeType:'普通订单',
goodsDetail:[
{
goodsNo:'G001',
sellCount:'10',
shareFavourableAfterFee:'1000',
cost:'800'
}
]
}
```
根据上述原始数据，通过元数据配置和转换逻辑，可以生成如下请求体：
```json
{
FormId :'SAL_OUTSTOCK' ,
Operation :'Save' ,
IsAutoSubmitAndAudit:true ,
IsVerifyBaseDataField:true ,
SubSystemId:'21' ,
InterationFlags :'STK_InvCheckResult' ,
BatchCount :'5' ,
request:[
{
FBillTypeID :'XSCKD01_SYS' ,
FBillNo :'123456' ,
FDate :'2023-10-01' ,
FSaleOrgId :'WH001_COMPANY_CODE' ,
FStockOrgId :'WH001_COMPANY_CODE' ,
FOwnerIdHead :'WH001_COMPANY_CODE' ,
FCustomerID :'SHOP001' ,
FNote :'紧急订单' ,
F_LSJC_Text :'123456' ,
...
FEntity:[
{
FMaterialId :'G001_CODE' ,
FRealQty :'10' ,
Flot:'01_CODE',
...
}
]
}
]
}
```
通过上述步骤，我们成功地将源平台的数据转换为金蝶云星空API接口所能接收的格式，并完成了数据写入。
