吉客云到金蝶云星空的系统对接案例：销售出库红字-对接金蝶云销售退
在本技术案例中，我们将展示如何通过轻易云数据集成平台，实现吉客云和金蝶云星空之间的数据无缝对接，具体场景是处理"销售出库红字"到"金蝶云销售退"。此过程中，我们需要综合运用高吞吐量的数据写入能力、实时监控与日志记录、自定义数据转换逻辑等功能，以确保整个集成流程的可靠性和时效性。
API接口调用设计
首先，需要调用吉客云提供的API接口erp.storage.goodsdocout.v2来获取相关的销售出库红字数据。这一过程要求定时且可靠地抓取接口数据，并处理分页与限流问题，以确保不会遗漏任何条目。为了提高效率，轻易云平台支持批量数据提取，从而加速整体响应时间。
{
"api": "erp.storage.goodsdocout.v2",
"params": {
// 必要参数设置
}
}数据质量监控与自定义数据转换
从吉客云南提取的数据，在传输到金蝶云星空前可能存在格式上的差异。使用轻易云提供的数据质量监控工具，可以及时发现并解决可能的问题。此外，通过自定义转换逻辑，将源数据结构转化为目标系统所需格式。例如，将日期格式、字段名映射以及单位等进行必要调整。
数据写入与错误重试机制
当准备好的数据符合目标要求后，利用金蝶云星空的API batchSave 实现高效的数据写入。在这一环节，要特别注意异常处理和错误重试机制。如果第一次尝试失败，系统会自动记录对应日志并在合适的时候再次发起请求，直到成功或者超出预设次数上限为止。这些操作都在集中式监控和告警系统内实时跟踪，给予保障。
{
"api": "batchSave",
"data": [
// 转换后的表单内容
]
}通过这些步骤，可以保证集成框架下配置元数据信息不漏单，并能够快速处理大量业务交易，提高整体运营透明度及效率。在下一部分内容中，我们将详细介绍每个环节中的技术实现细节，包括如何调优性能以满足生产环境需求，以及进一步优化解决方案中的关键点。
调用吉客云接口erp.storage.goodsdocout.v2获取并加工数据
在数据集成生命周期的第一步中，我们需要调用吉客云的API接口erp.storage.goodsdocout.v2来获取销售出库红字的数据，并对其进行初步加工。以下是详细的技术步骤和实现细节。
API接口调用配置
首先，我们需要配置API接口的请求参数。根据元数据配置，API调用采用POST方法，主要参数如下：
pageIndex: 分页页码pageSize: 分页页数，默认值为50goodsDocNo: 出库单号startDate: 创建时间的起始时间，使用变量{{LAST_SYNC_TIME|datetime}}endDate: 创建时间的结束时间，使用变量{{CURRENT_TIME|datetime}}inouttype: 类型，固定值为201（销售出库）- 其他可选参数如：
sourceBillNo,warehouseCode,vendCode,billNo,userName,outBillNo,gmtModifiedStart,gmtModifiedEnd
以下是一个示例请求体：
{
"pageIndex": "1",
"pageSize": "50",
"startDate": "{{LAST_SYNC_TIME|datetime}}",
"endDate": "{{CURRENT_TIME|datetime}}",
"inouttype": "201"
}数据过滤与条件设置
为了确保获取的数据符合业务需求，我们需要设置一些过滤条件：
- 红字状态：根据元数据配置中的条件，红字状态字段
redStatus必须等于9。 - 数量大于0：在子表字段中，
goodsDocDetailList.quantity必须大于0。
这些条件可以在API请求后进行二次过滤，以确保数据的准确性。
数据加工与清洗
获取到原始数据后，需要对其进行初步加工和清洗。根据元数据配置，我们将返回的嵌套字段goodsDocDetailList拍平处理，以便后续的数据转换和写入操作。
示例返回数据结构：
{
"goodsdocNo": "12345",
"billNo": "67890",
"inOutDate": "2023-10-01",
"gmtCreate": "2023-10-01T12:00:00Z",
"inouttype": "201",
...
"goodsDocDetailList": [
{
"goodsNo": "A001",
"goodsName": "商品A",
"quantity": 10,
...
},
{
"goodsNo": "B002",
"goodsName": "商品B",
"quantity": -5,
...
}
]
}在拍平处理后，将每个子项作为独立记录，并保留主表信息：
[
{
"goodsdocNo": "12345",
"billNo": "67890",
...
"goodsNo": "A001",
"goodsName": "商品A",
...
"quantity": 10
},
{
...
"goodsNo": "-5"
}
]异常处理与补偿机制
为了确保数据集成过程中的稳定性和可靠性，我们需要设置异常处理和补偿机制。例如，当某次同步失败时，可以通过定时任务（crontab）重新发起请求，并调整时间范围以覆盖未成功同步的数据段。
元数据配置中的补偿机制示例：
{
"_function FROM_UNIXTIME( unix_timestamp() -259200 , '%Y-%m-%d %H:%i:%s' )"
}该配置表示在当前时间减去三天（259200秒），以此作为新的起始时间重新发起请求。
实时监控与日志记录
最后，为了确保整个过程透明可控，需要实时监控API调用状态和数据流动情况，并记录日志以便追踪问题。可以通过轻易云平台提供的可视化界面实现这一功能。
通过上述步骤，我们能够高效地调用吉客云接口获取销售出库红字的数据，并对其进行初步加工，为后续的数据转换与写入奠定基础。
轻易云数据集成平台：将销售出库红字数据转换并写入金蝶云星空API
在数据集成生命周期的第二步中，ETL（Extract, Transform, Load）转换是关键环节。本文将详细探讨如何使用轻易云数据集成平台，将已经集成的源平台数据转换为金蝶云星空API接口所能够接收的格式，并最终写入目标平台。
元数据配置解析
我们首先来看一下元数据配置中的关键字段和配置项：
{
"api": "batchSave",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"operation": {
"method": "merge",
"field": "goodsdocNo,goodsDocDetailList_ownerName",
"bodyName": "FEntity",
"header": ["channelCode", "inOutDate", "goodsDocDetailList_ownerName", "logisticNo", "goodsDocDetailList_ownerName"],
"body": ["goodsDocDetailList_goodsNo", "goodsDocDetailList_quantity", "goodsDocDetailList_ownerName", "warehouseCode"]
},
...
}数据请求与清洗
在ETL流程中，首先需要从源系统请求数据并进行清洗。这里我们假设已经完成了这一阶段，接下来重点关注数据的转换与写入。
数据转换
为了将数据转换为金蝶云星空API所能接受的格式，我们需要对每个字段进行适当的映射和处理。
-
单据类型 (FBillTypeID):
{ "field": "FBillTypeID", "label": "单据类型", "type": "string", "describe": "单据类型", ... "value": "XSTHD01_SYS" }此字段直接指定为"XSTHD01_SYS"，无需额外处理。
-
销售组织 (FSaleOrgId):
{ ... "value": "_mongoQuery 22b42e1b-f3d2-367a-b973-2d9dbe490454 findField=content.FBelongOrgId where={\"content.FJKYCustId\":{\"$eq\":\"{channelCode}\"}}" }使用MongoDB查询，根据
channelCode获取对应的销售组织ID。 -
日期 (FDate):
{ ... "value": "{inOutDate}" }日期直接从输入参数
inOutDate中获取。 -
库存组织 (FStockOrgId):
{ ... "value": "{goodsDocDetailList_ownerName}", ... "mapping": {"target":"6441f0214af70a2f240adb22","direction":"positive"} }库存组织通过
goodsDocDetailList_ownerName字段映射，并进行正向映射处理。 -
退货客户 (FRetcustId):
{ ... "_mongoQuery ... findField=content.FCUSTNUMBER where={\"content.FJKYCustId\":{\"$eq\":\"{channelCode}\"}}" }同样通过MongoDB查询，根据
channelCode获取对应的客户编号。 -
货主类型 (FOwnerTypeIdHead) 和 货主 (FOwnerIdHead):
{ ... {"field":"FOwnerTypeIdHead","label":"货主类型","type":"string","value":"BD_OwnerOrg"}, {"field":"FOwnerIdHead","label":"货主","type":"string","value":"{goodsDocDetailList_ownerName}","mapping":{"target":"6441f0214af70a2f240adb22","direction":"positive"}} }货主类型固定为"BD_OwnerOrg"，货主通过
goodsDocDetailList_ownerName字段映射。 -
财务信息 (SubHeadEntity): 财务信息包含结算组织等子字段，通过类似方式进行处理和映射。
-
明细信息 (FEntity): 明细信息是一个数组，需要对其中每个元素进行处理：
-
物料编码 (FMaterialId):
{"field":"FMaterialId","label":"物料编码","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{{FEntity.goodsDocDetailList_goodsNo}}"}使用物料编码字段并通过解析器转换。
-
实退数量 (FRealQty):
{"field":"FRealQty","label":"实退数量","type":"string","describe":"数量","value":"_function {{FEntity.goodsDocDetailList_quantity}}* -1"}实退数量取负值以表示退货。
-
仓库 (FStockId):
{"field":"FStockId","label":"仓库","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{warehouseCode}"}仓库通过仓库代码字段映射并解析。
-
数据写入
所有字段经过转换后，通过POST请求将数据写入金蝶云星空API：
{
...
{"field": "...", ...},
{"otherRequest":[{"field":...,"value"...}]}
}在此过程中，确保所有基础资料有效性，并设置自动提交和审核选项：
{
...
{"field":...,"value"...},
{"IsAutoSubmitAndAudit":{"label":"","type":"","value":true}},
{"IsVerifyBaseDataField":{"label":"","type":"","value":true}}
}总结
通过以上步骤，我们成功地将销售出库红字的数据转换为金蝶云星空API可接受的格式，并实现了数据的无缝写入。此过程充分利用了轻易云数据集成平台的元数据配置和异构系统支持能力，实现了高效、透明的数据集成。
