### 采购入库对接——红冲——已测试：吉客云数据集成到金蝶云星空案例分享
在本次技术案例中，我们将聚焦于如何高效地实现吉客云与金蝶云星空的系统对接，重点介绍通过API接口`erp.storage.goodsdocin.v2`从吉客云获取采购入库数据并批量写入到金蝶云星空中。我们成功实施了「采购入库对接--红冲--已测试」方案，实现了以下几大功能：
首先，通过调度机制定时可靠抓取吉客云接口数据，并确保按需求处理分页和限流问题，从而实现稳定的数据采集。利用轻易云提供的可视化数据流设计工具，有效管理和监控整个数据处理流程。
其次，为解决两套系统之间的数据格式差异，我们采用自定义的数据转换逻辑，使得每条记录能够完美匹配目标系统的要求。这一过程中借助轻易平台所提供的实时监控与告警功能，可以及时发现并修复潜在的问题，提高整体效率和准确性。
最后，在将整理后的大量采购入库数据快速写入到金蝶云星空时，我们使用其batchSave API进行批量操作。在此过程中，特别注意异常处理与错误重试机制，以保证最终所有有效数据都能正确进入目标系统。同时，通过统一视图全面掌握API资产使用情况，实现资源高效利用和优化配置。
该案例展示了一整套完整且经过验证的数据集成方案，不仅提升了业务透明度和效率，也为其他类似场景提供了宝贵参考。
### 使用轻易云数据集成平台调用吉客云接口获取并加工数据的技术案例
在数据集成过程中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用吉客云接口`erp.storage.goodsdocin.v2`，并对获取的数据进行加工处理。
#### 接口调用配置
首先，我们需要配置元数据，以便正确调用吉客云的API接口。以下是元数据配置的详细说明：
```json
{
"api": "erp.storage.goodsdocin.v2",
"effect": "QUERY",
"method": "POST",
"number": "goodsdocNo",
"id": "goodsdocNo",
"idCheck": true,
"request": [
{"field":"pageIndex","label":"分页页码","type":"string"},
{"field":"pageSize","label":"分页页数","type":"string","value":"50"},
{"field":"startDate","label":"创建时间的起始时间","type":"string","value":"{{LAST_SYNC_TIME|datetime}}"},
{"field":"endDate","label":"创建时间的结束时间","type":"string","value":"{{CURRENT_TIME|datetime}}"},
{"field":"selelctFields","label":"返回字段","type":"string","value":"goodsdocNo,gmtCreate,inOutDate,gmtCreate,inouttype,vendCustomerCode,vendCode,warehouseCode,warehouseName,redStatus,financeBillStatus,goodsDocDetailList.goodsNo,goodsDocDetailList.estCost,goodsDocDetailList.quantity,goodsDocDetailList"},
{"field":"inouttype","label":"入库类型","type":"string","value":"101"},
{"field":"vendCode","label":"往来供应商","type":"string"},
{"field":"gmtModifiedStart","label":"修改时间的起始时间","type":"string"},
{"field":"gmtModifiedEnd","label":"修改时间的结束时间","type":"string"}
],
"autoFillResponse": true,
"condition_bk": [
[{"field": "goodsdocNo", "logic": "eqv2", "value": "CRK202303306601"}]
],
"beatFlat": ["goodsDocDetailList"],
"condition": [
[{"field": "goodsDocDetailList.quantity", "logic": "lt", "value": "0"},
{"field": "warehouseName", "logic": "notlike", "value": "VMI"},
{"field": "warehouseName", "logic": "notlike", "value": "爱尚直发"}]
],
"omissionRemedy": {
"crontab": "1 2 * * *",
"takeOverRequest":[
{"field": "startDate",
"value": "_function FROM_UNIXTIME( unix_timestamp() -259200 , '%Y-%m-%d %H:%i:%s' )",
"type": "string",
"label": "接管字段",
formModel:{"enable":false},
tableModel:{"enable":false},
physicalModel:{"enable":false}
}
]
}
}
```
#### 请求参数详解
- **分页参数**：`pageIndex` 和 `pageSize` 用于控制每次请求的数据量，默认每页返回50条记录。
- **时间参数**：`startDate` 和 `endDate` 分别表示数据创建时间的起始和结束，用于增量同步。
- **选择字段**：`selelctFields` 指定了需要返回的字段列表，包括单据编号、创建时间、入库类型等。
- **入库类型**：通过 `inouttype` 字段指定为采购入库（值为101）。
- **供应商编码**：可选参数 `vendCode` 用于过滤特定供应商的数据。
- **修改时间**：`gmtModifiedStart` 和 `gmtModifiedEnd` 用于筛选在特定时间范围内修改的数据。
#### 数据过滤与处理
为了确保数据质量和业务需求，我们在元数据中设置了多种过滤条件和处理逻辑：
1. **条件过滤**：
- `condition_bk`: 基于单据编号进行精确匹配。
- `condition`: 对明细表中的数量小于0的数据进行过滤，并排除仓库名称包含“VMI”和“爱尚直发”的记录。
2. **自动填充响应**：
- 设置 `autoFillResponse: true`，确保返回的数据自动填充到相应的字段中。
3. **扁平化处理**：
- 使用 `beatFlat: ["goodsDocDetailList"]` 将嵌套结构中的明细列表扁平化，方便后续处理。
4. **遗漏补救机制**：
- 配置了定时任务（crontab），每天凌晨2点执行一次，确保遗漏的数据能够及时补救。通过 `_function FROM_UNIXTIME( unix_timestamp() -259200 , '%Y-%m-%d %H:%i:%s' )` 设置接管字段，将开始日期设为当前时间前3天。
#### 实际应用案例
在实际操作中，我们通过上述配置成功调用了吉客云接口，并获取了符合条件的采购入库单据及其明细信息。以下是一个具体示例：
```json
{
// 请求示例
{
pageIndex: '1',
pageSize: '50',
startDate: '2023-10-01T00:00:00',
endDate: '2023-10-02T00:00:00',
selelctFields: 'goodsdocNo,gmtCreate,inOutDate,gmtCreate,inouttype,vendCustomerCode,vendCode,warehouseCode,warehouseName,redStatus,financeBillStatus,goodsDocDetailList.goodsNo,goodsDocDetailList.estCost,goodsDocDetailList.quantity,goodsDocDetailList',
inouttype: '101'
}
}
// 响应示例
{
data:[
{
goodsdocNo: 'CRK202310010001',
gmtCreate: '2023-10-01T08:30:00',
inOutDate: '2023-10-01T08:30:00',
inouttype: '101',
vendCustomerCode: 'VEND001',
vendCode: 'VEND001',
warehouseCode: 'WH001',
warehouseName: '主仓库',
redStatus: '0',
financeBillStatus: '1',
goodsDocDetailList:[
{
goodsNo:'G001',
estCost:'100.00',
quantity:'10'
},
{
goodsNo:'G002',
estCost:'200.00',
quantity:'5'
}
]
}
// 更多记录...
]
}
```
通过上述配置和实际应用，我们不仅实现了对吉客云采购入库单据的高效获取，还保证了数据质量和业务需求的一致性。这一过程展示了轻易云数据集成平台在异构系统间无缝对接和高效处理方面的强大能力。
### 采购入库对接--红冲--已测试：ETL转换与写入金蝶云星空API接口
在数据集成生命周期的第二步，将已经集成的源平台数据进行ETL转换，并转为目标平台金蝶云星空API接口所能够接收的格式，最终写入目标平台。本文将详细探讨这一过程中的技术细节，特别是如何利用元数据配置完成这一任务。
#### 数据请求与清洗
在数据请求与清洗阶段，我们已经从源系统获取了采购入库的数据，并进行了初步的清洗和整理。接下来，我们需要将这些数据转换为金蝶云星空API接口所能接受的格式，并通过API接口将数据写入目标平台。
#### 数据转换与写入
轻易云数据集成平台提供了全异步、多种异构系统支持的能力，使得不同系统间的数据无缝对接成为可能。在本案例中，我们将使用以下元数据配置来实现这一过程：
```json
{
"api": "batchSave",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"operation": {
"method": "merge",
"field": "goodsDocDetailList_ownerName,goodsdocNo",
"bodyName": "Fentity",
"header": ["goodsdocNo", "inOutDate", "vendCustomerCode", "warehouseCode", "goodsDocDetailList_ownerName"],
"body": ["goodsDocDetailList_goodsNo", "goodsDocDetailList_quantity", "goodsDocDetailList_estPrice", "goodsDocDetailList_estCost"]
},
"request": [
{"field":"FJKYNo","label":"吉客云单号","type":"string","value":"{goodsdocNo}"},
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","mapping":{"target":"6441f0214af70a2f240adb22","direction":"positive"}},
{"field":"FDate","label":"退料日期","type":"string","describe":"日期","value":"{inOutDate}"},
{"field":"FSupplierID","label":"供应商","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{vendCustomerCode}"},
{"field":"FStockOrgId","label":"退料组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{goodsDocDetailList_ownerName}"},
{"field":"FSettleOrgId","label":"结算组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{goodsDocDetailList_ownerName}"},
{"field":"FPayOrgId","label":"付款组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{goodsDocDetailList_ownerName}"},
{"field": "FBusinessType", "label": "业务类型", "type": "string", "value": "CG"},
{
"field": "FPURMRBENTRY",
"label": "明细信息",
"type": "array",
"children": [
{"field": "FMATERIALID",
"label":
"物料编码",
"type":
"string",
"describe":
"基础资料",
"parser":
{"name":
"ConvertObjectParser",
"params":
"FNumber"
},
"value":
"{{Fentity.goodsDocDetailList_goodsNo}}"
},
{"field":
"FRMREALQTY",
"label":
"实退数量",
"type":
"string",
"value":
"_function {{Fentity.goodsDocDetailList_quantity}} *(-1)"
},
{"field":
"FSTOCKID",
"label":
"仓库",
"type":
"string",
"value":
"{warehouseCode}"
},
{"field":
"FTAXPRICE",
"label":
"含税单价",
"type":
"string",
value:
"{{Fentity.goodsDocDetailList_estPrice}}"
},
{
field:
FALLAMOUNT,
label:
价税合计,
type:
string,
value:
_function {{Fentity.goodsDocDetailList_estCost}} *(-1)
}
],
value: Fentity
}
],
otherRequest: [
{
field: FormId,
label: 业务对象表单Id,
type: string,
describe: 必须填写金蝶的表单ID如:PUR_PurchaseOrder,
value: PUR_MRB
},
{
field: Operation,
label: 执行的操作,
type: string,
value: batchSave
},
{
field: IsAutoSubmitAndAudit,
label: 提交并审核,
type: bool,
value: true
},
{
field: IsVerifyBaseDataField,
label: 验证基础资料,
type: bool,
describe: 是否验证所有的基础资料有效性，布尔类，默认false（非必录）,
value:true
},
{
field: SubSystemId,
label 系统模块，
type： string，
describe 默认仓库模块，
value：21
},
{
field InterationFlags，
label：允许负库存，
type： string，
value： STK_InvCheckResult
}
]
}
```
#### API接口调用
在上述元数据配置中，`api`字段指定了我们要调用的金蝶云星空API接口为`batchSave`。该接口用于批量保存采购入库红冲的数据。`method`字段指定了HTTP请求方法为POST。
##### 请求头部和主体配置
- `header`字段定义了请求头部需要包含的数据字段，如`goodsdocNo`, `inOutDate`, `vendCustomerCode`, `warehouseCode`, `goodsDocDetailList_ownerName`等。
- `body`字段定义了请求主体需要包含的数据字段，如`goodsDocDetailList_goodsNo`, `goodsDocDetailList_quantity`, `goodsDocDetailList_estPrice`, `goodsDocDetailList_estCost`等。
##### 数据映射和解析
- 在请求配置中，通过`mapping`和`parser`进行数据映射和解析。例如，供应商ID (`FSupplierID`) 使用了一个名为`ConvertObjectParser`的解析器，将其值从源系统格式转换为目标系统格式。
- 明细信息(`FPURMRBENTRY`)中的物料编码、实退数量、仓库、含税单价、价税合计等字段也进行了相应的映射和解析。
##### 特殊处理逻辑
- 实退数量(`FRMREALQTY`) 和价税合计(`FALLAMOUNT`) 的值通过 `_function {{...}} *(-1)` 表达式进行了特殊处理，以确保符合红冲业务逻辑。
##### 其他请求参数
- 表单ID (`FormId`) 指定为 `PUR_MRB`
- 执行操作 (`Operation`) 指定为 `batchSave`
- 提交并审核 (`IsAutoSubmitAndAudit`) 设置为 `true`
- 验证基础资料 (`IsVerifyBaseDataField`) 设置为 `true`
- 系统模块 (`SubSystemId`) 设置为默认仓库模块 (`21`)
- 允许负库存 (`InterationFlags`) 设置为 `STK_InvCheckResult`
#### 数据写入执行
通过上述配置，我们可以构建一个完整的HTTP POST请求，将采购入库红冲的数据批量保存到金蝶云星空平台。轻易云数据集成平台会根据配置自动生成并发送该请求，并实时监控其执行状态，确保数据成功写入目标平台。
以上即是通过轻易云数据集成平台实现采购入库对接--红冲--已测试场景下的数据ETL转换与写入金蝶云星空API接口的详细技术案例。
