### 系统对接集成案例分享：旺店通·企业奇门数据集成到金蝶云星空——销售出库
在实现精细化管理和智能化运营的过程中，数据集成扮演着至关重要的角色。在本文中，我们将深入探讨如何通过配置和调用API，实现旺店通·企业奇门系统与金蝶云星空之间“销售出库”业务的数据对接。本次案例采用了高效、稳定的轻易云数据集成平台，并重点关注于以下技术要点：
1. **大规模数据写入能力**：利用轻易云平台支持的大量数据快速写入机制，确保从旺店通·企业奇门系统获取的大量销售出库订单能够迅速、安全地传输至金蝶云星空。
2. **实时监控与告警系统**：为保证整个数据处理过程透明可见，对任务状态和性能进行全程跟踪。一旦出现异常情况，系统能及时发出告警信息进行响应。
3. **接口调用与分页处理**：
- 对于获取销售订单，我们使用`wdt.stockout.order.query.trade` API，通过分页机制抓取大量订单，以避免单次请求的数据过多导致延迟或失败。
- 数据上传到金蝶云星空时，则利用其提供的`batchSave` API，将整理好的批量数据高效写入目标数据库。
4. **自定义转换逻辑及格式兼容**：针对两大系统间存在的数据结构差异问题，通过配置灵活的自定义转换规则来适应不同需求，从而保证每条记录准确无误地映射至目标字段。
5. **异常处理和错误重试机制**：实施严谨的错误捕获及重试逻辑，在意外情况下能自动恢复并继续执行未完成的任务，有效提升总体成功率。
以上五个核心要点将贯穿本案中各个步骤，为顺利实现两大系统间的数据无缝流动奠定基础。以下章节我们将详细展开具体操作方法及注意事项，希望能够为读者同样面临类似业务挑战时提供有益参考。
### 调用源系统旺店通·企业奇门接口wdt.stockout.order.query.trade获取并加工数据
在数据集成的生命周期中，第一步是从源系统获取数据。本文将详细探讨如何使用轻易云数据集成平台调用旺店通·企业奇门接口`wdt.stockout.order.query.trade`，并对获取的数据进行初步加工。
#### 接口调用配置
首先，我们需要配置接口调用的元数据。根据提供的元数据配置，可以看到该接口采用POST方法，并且支持分页查询。以下是具体的请求参数配置：
- **start_time** 和 **end_time**：用于增量获取数据，分别表示开始时间和结束时间，格式为`yyyy-MM-dd HH:mm:ss`。这两个参数通常会动态赋值，例如`start_time`可以设置为上次同步时间（`{{LAST_SYNC_TIME|datetime}}`），而`end_time`可以设置为当前时间（`{{CURRENT_TIME|datetime}}`）。
- **status**：表示订单状态，包括已取消、已审核、已发货等多种状态。
- **src_order_no** 和 **src_tid**：分别表示系统订单编号和原始单号。
- **stockout_no**：出库单号。
- **shop_no**：店铺编号，用于区分不同店铺的数据。
- **warehouse_no**：仓库编号，用于区分不同仓库的数据。
此外，还有分页参数：
- **page_size**：每页返回的数据条数，范围1~100，默认值为40。
- **page_no**：页号，不传值时默认从0页开始。
#### 请求示例
以下是一个完整的请求示例：
```json
{
"api": "wdt.stockout.order.query.trade",
"method": "POST",
"number": "order_no",
"id": "stockout_id",
"pagination": {
"pageSize": 100
},
"idCheck": true,
"request": [
{
"field": "start_time",
"label": "开始时间",
"type": "datetime",
"describe": "增量获取数据，start_time作为开始时间，格式：yyyy-MM-dd HH:mm:ss",
"value": "{{LAST_SYNC_TIME|datetime}}"
},
{
"field": "end_time",
"label": "结束时间",
"type": "datetime",
"describe": "增量获取数据，end_time作为结束时间，格式：yyyy-MM-dd HH:mm:ss",
"value": "{{CURRENT_TIME|datetime}}"
},
{
"field": "status",
"label": "状态",
"type": "string"
},
{
"field": "src_order_no",
"label": "系统订单编号",
"type": "string"
},
{
"field": "src_tid",
"label": "原始单号",
"type": "string"
},
{
"field": "stockout_no",
"label": "出库单号",
'type': 'string'
},
{
'field': 'shop_no',
'label': '店铺编号',
'type': 'string',
'describe': '代表店铺所有属性的唯一编码，用于店铺区分'
},
{
'field': 'warehouse_no',
'label': '仓库编号',
'type': 'string',
'describe': '代表仓库所有属性的唯一编码，用于仓库区分'
}
],
'otherRequest': [
{
'field': 'page_size',
'label': '分页大小',
'type': 'string',
'describe': '每页返回的数据条数',
'value': '{PAGINATION_PAGE_SIZE}'
},
{
'field': 'page_no',
'label': '页号',
'type': 'string',
‘describe’: ‘不传值默认从0页开始’,
‘value’: ‘{PAGINATION_START_PAGE}’
}
]
}
```
#### 数据清洗与转换
在成功调用接口并获取到原始数据后，需要对数据进行清洗与转换，以便后续处理和存储。以下是一些常见的数据清洗与转换操作：
1. **字段映射与重命名**：
- 将源系统中的字段映射到目标系统中的字段。例如，将源系统中的`order_no`映射到目标系统中的`order_number`。
2. **数据类型转换**：
- 确保所有字段的数据类型符合目标系统的要求。例如，将字符串类型的日期字段转换为日期类型。
3. **缺失值处理**：
- 对于缺失值，可以选择填充默认值、删除记录或进行其他处理。
4. **去重操作**：
- 如果源系统中存在重复记录，需要进行去重处理，以确保数据的一致性和准确性。
#### 示例代码
以下是一个简单的数据清洗示例代码：
```python
import pandas as pd
from datetime import datetime
# 假设我们已经通过API获取了原始数据
raw_data = [
{"order_no":"123", ...},
{"order_no":"124", ...},
]
# 将原始数据加载到DataFrame中
df = pd.DataFrame(raw_data)
# 字段映射
df.rename(columns={
“order_no”: “order_number”,
}, inplace=True)
# 数据类型转换
df[‘start_time’] = pd.to_datetime(df[‘start_time’])
df[‘end_time’] = pd.to_datetime(df[‘end_time’])
# 缺失值处理
df.fillna({“status”: “unknown”}, inplace=True)
# 去重操作
df.drop_duplicates(subset=[“order_number”], inplace=True)
print(df)
```
通过上述步骤，我们可以高效地调用旺店通·企业奇门接口获取销售出库相关的数据，并对其进行初步清洗和转换，为后续的数据处理和分析打下坚实基础。
### 轻易云数据集成平台：将销售出库数据转换并写入金蝶云星空
在使用轻易云数据集成平台进行数据集成时，第二步是将已经集成的源平台数据进行ETL转换，转为目标平台——金蝶云星空API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨如何利用元数据配置，将销售出库数据转换并写入金蝶云星空。
#### 配置API接口
在本案例中，我们使用的是金蝶云星空的`batchSave` API接口。该接口采用POST方法，支持批量保存操作。具体配置如下：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 10,
"method": "batchArraySave"
}
}
```
#### 请求参数配置
请求参数配置是ETL过程中的关键步骤。以下是主要字段及其配置说明：
1. **单据类型（FBillTypeID）**
- 类型：string
- 描述：单据类型
- 转换规则：使用`ConvertObjectParser`解析器，将固定值`XSCKD07_SYS`转换为目标格式。
```json
{
"field": "FBillTypeID",
"label": "单据类型",
"type": "string",
"describe": "单据类型",
"parser": {
"name": "ConvertObjectParser",
"params": "FNumber"
},
"value": "XSCKD07_SYS"
}
```
2. **单据编号（FBillNo）**
- 类型：string
- 描述：单据编号
- 转换规则：直接映射源数据中的订单编号。
```json
{
"field": "FBillNo",
"label": "单据编号",
"type": "string",
"describe": "单据编号",
"value": "{order_no}"
}
```
3. **原始订单号（F_JSJT_Text_YSDDH）**
- 类型：string
- 描述：原始订单号
- 转换规则：截取源订单号的前50个字符。
```json
{
"parent": "FEntity",
"label": "原始订单号",
"field": "F_JSJT_Text_YSDDH",
"type": "string",
"value": "_function left(\"{src_trade_no}\",50)"
}
```
4. **日期（FDate）**
- 类型：string
- 描述：日期
- 转换规则：将发货时间格式化为日期格式。
```json
{
"field": "FDate",
"label": "日期",
"type": "string",
"describe":"日期",
*"value":"{{consign_time|date}}"
}
```
5. **发货组织、销售组织、货主（FStockOrgId、FSaleOrgId、FOwnerIdHead）**
- 类型：string
- 描述：组织或货主信息
- 转换规则：通过`ConvertObjectParser`解析器，根据店铺编号从指定集合中查找对应的组织或货主信息。
```json
{
*"field":"FStockOrgId","label":"发货组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"_findCollection find email from 4cf40fbb-7205-39f0-98f2-b2d1cd4e15cf where shop_no={shop_no}"
}
```
6. **客户（FCustomerID）**
- 类型：string
- 描述：基础资料
- 转换规则：通过`ConvertObjectParser`解析器，将店铺编号转换为客户信息。
```json
{
*"field":"FCustomerID","label":"客户","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{shop_no}"
}
```
7. **物流信息（运输单号、联系电话、收货人姓名等）**
- 类型：string
- 描述：文本信息
- 转换规则：直接映射源数据中的相应字段。
```json
{
*"field":"FCarriageNO","label":"运输单号","type":"string","describe":"文本","value":"{logistics_no}"
*"field":"FLinkPhone","label":"联系电话","type":"string","describe":"文本","value":"{receiver_mobile}"
*"field":"FLinkMan","label":"收货人姓名","type":"string","describe":"文本","value":"{receiver_name}"
*"field:"FNote", label:"备注", type:"string", describe:"多行文本", value:"{cs_remark}原始订单号:{src_trade_no}"
```
8. **财务信息（结算组织、结算币别等）**
- 类型:object
- 描述:子对象
- 转换规则:通过 ConvertObjectParser 解析器,根据店铺编号从指定集合中查找对应的结算组织,并设置结算币别为固定值 PRE001。
```json
{
*“SubHeadEntity”, “label”:”财务信息”, “type”:”object”, “children”:[
{
*“field”:”FSettleOrgID”, “label”:”结算组织”, “type”:”string”, “describe”:”组织”, “parser”:{“name”:”ConvertObjectParser”, “params”:”FNumber”}, “value”:”_findCollection find email from 4cf40fbb-7205-39f0-98f2-b2d1cd4e15cf where shop_no={shop_no}”
},
{
*“field”:”FSETTLECURRID”, “label”:”结算币别”, “type”:”string”, “describe”:”文本”, “parser”:{“name”:”ConvertObjectParser”, “params”:”FNumber”}, “value”:PRE001”
}
]
}
```
9.**明细信息(物料编码,实发数量,含税单价等)**
- 类型:array
- 描述:数组对象
- 转换规则:通过 ConvertObjectParser 和自定义函数进行多重转换和计算,确保每个字段符合目标平台要求。
```json
{
*“field:” FEntity ”,“ label ”:“ 明细信息 ”,“ type ”:“ array ”,“ children ”:[
{
*“ field ”:“ FMaterialID ”,“ label ”:“ 物料编码 ”,“ type ”:“ string ”,“ describe ”:“ 基础资料 ”,“ parser ”:{“ name ”:“ ConvertObjectParser ”,“ params ”:“ FNumber ”},“ value ”:“ _findCollection find FNumber from cdb4b806-7ece-3e84-b575-0d30a831abd4 where FOldNumber={{details_list.goods_no}} ”
},
{
*“ field ”:“ FRealQty ”,“ label ”:“ 实发数量 ”,“ type ”:“ string ”,“ describe ”:“ 数量 ”,“ value:” {{details_list.goods_count}} ”
},
{
*“ field:” FTaxPrice ,“ label : 含税单价 ,“ type : string ,“ describe : 单价 ,“ value : _function round((({{details_list.paid}}+{{details_list.share_post}})/{{details_list.goods_count}}),6)”
},
{
*“ field : FOwnerTypeId ,“ label : 货主类型 ,“ type : string ,“ value : BD_OwnerOrg ”
},
{
*“ field : FOwnerId ,“ label : 货主 ,“ type : string ,“ parser : { name : ConvertObjectParser , params : FNumber }, value : _findCollection find email from 4cf40fbb-7205-39f0-98f2-b2d1cd4e15cf where shop_no={shop_no}”
},
{
* field:FStockID,label:仓库,type:string,describe:基础资料,parser:{name:ConvertObjectParser,params:FNumber},value:{warehouse_no}
},
{
* field:FIsFree,label:是否赠品,type:string,value:_function case '{{details_list.paid}}' when '0.0000' then true else false end,parent:FEntity}
],
"value ":" details_list "
}
```
10 .**其他请求参数**
最后，我们需要配置一些其他必要的请求参数，如业务对象表单 ID、执行操作、是否自动提交并审核等。
``` json
[
{" 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"}
]
```
通过上述详细配置，我们能够将源平台的数据经过 ETL 转换后，成功写入到金蝶云星空系统中。这不仅实现了不同系统间的数据无缝对接，也确保了数据的一致性和准确性。
