### 吉客云数据集成到金蝶云星空的技术实现
在本次系统对接项目中，我们专注于将吉客云的数据高效、准确地集成到金蝶云星空环境中，具体实施方案为“其他出库(菜鸟)(负数)对接-其他入库单”。为了达到这一目标，我们利用了轻易云数据集成平台的多种功能，包括API调用管理、高吞吐量的数据写入能力和实时监控机制。
首先，在获取吉客云的出库单数据时，采用了`erp.storage.goodsdocout.v2`接口。此步骤需要考虑接口分页和限流问题，以确保不会漏单。在实际操作中，通过定时任务可靠地抓取该接口的数据，并设置分页逻辑来逐页处理返回结果。同时，为了提升效率并避免影响系统性能，需要设定合理的限流策略。
其次，在将这些获取的数据写入到金蝶云星空时，我们使用了其提供的批量保存API `batchSave`。由于吉客云与金蝶云星空之间存在一定的数据格式差异，因此需要通过自定义数据转换逻辑对数据进行映射，以保证两边系统所要求的数据结构一致。在这个过程中，还特别注意到了如何应对可能出现的异常情况及其重试机制，从而确保整个集成过程的稳定性和可靠性。
此外，为进一步保障数据质量，我们借助轻易云的平台提供集中监控功能，对每一个任务执行状态进行实时跟踪。一旦发现任何异常或潜在问题，可以即时响应并解决。这不仅提高了业务透明度，还极大程度上减少了人工干预，提高整体运作效率。
本文后续部分将详细描述包括详细代码示例在内的一系列具体实施步骤，以及如何利用上述提到的平台特性，实现从吉客云到金蝶云星空无缝衔接的大规模数据处理。
### 调用吉客云接口获取并加工数据的技术实现
在轻易云数据集成平台的生命周期中，调用源系统接口是至关重要的一步。本文将深入探讨如何通过吉客云接口`erp.storage.goodsdocout.v2`获取并加工数据，以实现其他出库(菜鸟)(负数)对接其他入库单的集成方案。
#### 接口调用配置
首先，我们需要配置元数据以便调用吉客云的接口。以下是元数据配置的关键部分：
```json
{
"api": "erp.storage.goodsdocout.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":"goodsDocNo","label":"出库单号","type":"string"},
{"field":"startDate","label":"创建时间的起始时间","type":"string","value":"{{LAST_SYNC_TIME|datetime}}"},
{"field":"endDate","label":"创建时间的结束时间","type":"string","value":"{{CURRENT_TIME|datetime}}"},
{"field":"inouttype","label":"类型","type":"string","describe":"201-销售出库 202调拨出库 203 = 盘亏出库 204-其他出库 205采购退货 206生产领料 207组装拆卸出库 208翻新出库 209报废出库 210残次品出库 211倒冲出库 212 包材出库 215维修还厂 231成本调整出库","value":"204"},
{"field":"sourceBillNo","label":"来源单号","type":"string"},
{"field":"warehouseCode","label":"仓库编号","type":"string"},
{"field":"vendCode","label":"供应商编号(往来单位)","type":"string"},
{"field":"billNo","label":"上游单据号(关联单号)","type":"string"},
{"field":"userName","label":"创建人名称","type":"string"},
{"field":"outBillNo","label":"外部单号（全模糊匹配）","type":"string"},
{"field":"gmtModifiedStart","label":"主表更新时间起始","type":"string"},
{"field":"gmtModifiedEnd","label":"主表更新时间截至","type":"string"},
{"field": "selelctFields", "label": "返回参数", "type": "string", "value": "goodsdocNo,inOutDate,gmtCreate,userName,inouttype,vendCustomerCode,warehouseCode,warehouseName,inOutReason,redStatus,financeBillStatus,goodsDocDetailList.goodsNo,goodsDocDetailList.goodsName,goodsDocDetailList.quantity,goodsDocDetailList"}
],
...
}
```
#### 请求参数详解
1. **分页参数**：`pageIndex`和`pageSize`用于控制分页，确保一次请求不会返回过多数据。
2. **时间参数**：`startDate`和`endDate`用于限定查询的数据范围，分别使用上次同步时间和当前时间。
3. **类型参数**：`inouttype`设置为204，表示查询的是“其他出库”类型的数据。
4. **返回字段**：通过`selelctFields`指定需要返回的字段，包括基本信息和详细商品信息。
#### 数据过滤与条件设置
为了确保获取的数据符合业务需求，我们需要设置特定的过滤条件：
```json
"condition":[
[{"field": "inOutReason", "logic": "like", "value": "菜鸟"},
{"field": "userName", "logic": "notlike", "value": "外部"},
{"field": "goodsDocDetailList.quantity", "logic": "lt", "value": "-0"}]
]
```
这些条件确保：
- `inOutReason`包含“菜鸟”。
- `userName`不包含“外部”。
- `goodsDocDetailList.quantity`小于0，即为负数。
#### 自动填充与扁平化处理
为了简化后续的数据处理，我们启用了自动填充响应和扁平化处理：
```json
"autoFillResponse": true,
"beatFlat":["goodsDocDetailList"]
```
这意味着响应中的嵌套结构会被自动展开，使得每个商品明细成为独立记录，便于后续的数据转换与写入操作。
#### 异常处理与补偿机制
为了应对可能出现的数据遗漏或异常情况，我们配置了补偿机制：
```json
"omissionRemedy":{
...
,"takeOverRequest":[{"field":...}]
}
```
该机制通过定时任务（如每两小时执行一次）重新拉取最近三天的数据，以确保数据完整性。
### 实际调用示例
以下是一个实际调用该接口的示例代码片段：
```python
import requests
import datetime
url = 'https://api.jikecloud.com/erp.storage.goodsdocout.v2'
headers = {'Content-Type': 'application/json'}
payload = {
'pageIndex': '1',
'pageSize': '50',
'startDate': (datetime.datetime.now() - datetime.timedelta(days=1)).strftime('%Y-%m-%d %H:%M:%S'),
'endDate': datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
'inouttype': '204',
# ... other parameters ...
}
response = requests.post(url, headers=headers, json=payload)
data = response.json()
# Process the data as needed...
```
通过上述步骤，我们成功调用了吉客云接口并获取了所需数据，为后续的数据转换与写入奠定了基础。这一过程展示了如何利用轻易云数据集成平台实现高效、透明的数据集成。
### 使用轻易云数据集成平台进行ETL转换并写入金蝶云星空API接口的技术案例
在数据集成过程中，将源平台的数据转换为目标平台可接收的格式是关键步骤。本文将详细探讨如何使用轻易云数据集成平台，将源自菜鸟的出库数据转换为金蝶云星空API接口所能接收的格式，并最终写入目标平台。
#### 1. 数据请求与清洗
首先，我们需要从源平台（菜鸟）获取出库数据。这一步骤涉及到数据请求和清洗，确保获取的数据符合预期，并进行必要的预处理。由于本文重点在于ETL转换和写入，因此不再赘述此部分。
#### 2. 数据转换与写入
在获取并清洗完数据后，下一步是将这些数据通过ETL（Extract, Transform, Load）过程转换为金蝶云星空API接口所能接收的格式。以下是详细的元数据配置及其应用解析。
##### API接口配置
```json
{
"api": "batchSave",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 1,
"method": "merge",
"field": "goodsDocDetailList_ownerName,goodsdocNo",
"bodyName": "items",
"header": ["goodsdocNo", "inOutDate", "goodsDocDetailList_ownerName"],
"body": ["goodsDocDetailList_goodsNo", "goodsDocDetailList_quantity", "warehouseCode"]
},
...
}
```
该配置指定了使用`batchSave` API，通过POST方法执行操作，并进行ID检查。`operation`字段定义了如何处理行数据，包括合并字段、请求体结构等。
##### 请求参数配置
```json
[
{
"field": "FJKYNo",
"label": "吉客云单号",
"type": "string",
"value": "{goodsdocNo}"
},
{
...
},
{
...
}
]
```
这些字段定义了请求参数的映射关系，例如将源平台的`goodsdocNo`映射到目标平台的`FJKYNo`。
##### 明细信息配置
```json
{
...
{
"field": "FEntity",
...
"children": [
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
}
]
}
]
}
]
}
]
}
]
}
]
}
```
`FEntity`字段包含了明细信息，定义了物料编码、发货仓库、库存状态和实收数量等子字段。这些子字段通过解析器（如`ConvertObjectParser`）将源平台的数据转换为目标平台所需格式。
##### 特殊处理逻辑
在某些情况下，需要对特定字段进行特殊处理。例如，实收数量需要乘以-1：
```json
{
...
{
...
"_function {{items.goodsDocDetailList_quantity}} *(-1)"
}
}
```
这段代码通过函数处理，将数量转化为负数，以符合业务需求。
##### 最终请求体结构
根据上述配置，最终生成的请求体结构如下：
```json
{
...
items: [
...
{
...
FEntity: [
...
{
...
FMATERIALID: "...",
FSTOCKID: "...",
FStockStatusId: "...",
FQty: -123
}
]
}
]
}
```
#### 执行操作
最后，通过调用金蝶云星空API接口，将转换后的数据写入目标系统：
```json
{
...
Operation: {
... Save
}
}
```
确保操作成功执行，并验证返回结果，以确认数据已正确写入目标系统。
### 总结
通过上述步骤，我们实现了从源平台到目标平台的数据ETL转换，并成功将数据写入金蝶云星空API接口。此过程充分利用了轻易云数据集成平台提供的元数据配置功能，实现了高效、透明的数据集成。
