轻易云平台实现ETL转换与写入金蝶云星辰V2API接口
### 案例分享：退货入库-广州闽福——从汤臣倍健营销云到金蝶云星辰V2的数据集成实战
在现代企业信息化进程中，实现多系统之间的数据无缝对接是一个普遍且重要的课题。本案例将详细讲述怎样通过高效解决方案实现汤臣倍健营销云数据与金蝶云星辰V2之间的自动化集成，特别是在"退货入库-广州闽福"业务场景下的成功实践。
在这个项目中，我们主要面临以下技术挑战：
1. **确保数据不漏单**：如何确保从汤臣倍健营销云接口/api/order/query/saleReturnOrder获取到的每一笔订单能够准确地写入到金蝶云星辰V2，并避免出现丢失或重复。
2. **处理分页和限流问题**：由于API接口返回数据具有分页特性，同时存在并发访问限制，需要合理规划调用策略，以保证数据完整性及有效集成。
3. **大量数据快速写入**：如何高效地批量处理和传输大规模订单数据，提升整个流程效率。
4. **实时监控与日志记录**：在整个过程中实现对各步骤状态的实时监控以及完备的日志记录，用于故障排查和性能优化。
首先，我们采用定时任务机制，通过轻易云平台可靠地抓取汤臣倍健营销云提供的数据。针对其API接口返回的大量订单信息（/erp/api/order/query/saleReturnOrder），我们设计了智能分页读取策略，有效规避了因频繁调用遭遇限流的问题。
接下来，为了解决两者间的数据格式差异，我们制作了一套自定义映射规则，使得接口返回结果能够精准映射至金蝶云星辰V2要求的字段形式。同时，通过使用批量操作功能，我们能迅速将整理后的退货订单推送至目标系统（/jdy/v2/scm/sal_in_bound），这一过程不仅提升了传输速度，还减少了潜在出错机会。
此外，在面向生产环境运行时，整合异常处理与错误重试机制尤为重要。当出现网络波动或其他非预期事件导致请求失败时，这一机制保障了系统具备良好的恢复能力，不会因为个别错误而影响整体流程。所有关键节点均配置有详细日志及报警通知功能，以便管理员可以随时掌握运行动态并及时应对突发情况。
通过本次分享，希望大家能更好理解如何借助先进工具及方法论，高效完成复杂系统间的数据集成任务。接下来的文章部分，将深入剖析具体代码实现细节、核心逻辑以及优化经验敬请
### 调用源系统汤臣倍健营销云接口获取并加工数据
在数据集成的生命周期中，第一步是调用源系统的API接口获取数据。本文将详细探讨如何通过调用汤臣倍健营销云的`/erp/api/order/query/saleReturnOrder`接口，获取退货入库相关的数据，并进行初步加工。
#### 接口配置与请求参数
首先，我们需要了解该API接口的基本配置和请求参数。根据元数据配置，该接口使用POST方法进行数据请求，主要参数如下：
- `tenantId`: 经销商ID（必填）
- `yxyNumber`: 营销云销售订单号
- `number`: 系统订单号
- `status`: 订单状态（0:未审核, 1:已审核）
- `beginTime`: 开始时间（格式：0000-00-00或0000-00-00 00:00:00）
- `endTime`: 结束时间（格式：0000-00-00或0000-00-00 00:00:00）
- `pageNo`: 页码（默认1）
- `pageSize`: 每页条数（默认30）
- `timeType`: 时间段标志（0:创建时间, 1:最后更新时间）
这些参数中的某些是必填项，例如`tenantId`、`beginTime`和`endTime`，而其他参数则根据具体需求进行填写。
#### 请求示例
为了更好地理解如何调用该API接口，我们可以参考以下示例请求：
```json
{
"tenantId": "34cc4109705e4c058b7b3b0352e57d31",
"status": "1",
"beginTime": "2023-01-01 00:00:00",
"endTime": "2023-01-31 23:59:59",
"pageNo": "1",
"pageSize": "30",
"timeType": "1"
}
```
在这个示例中，我们查询的是2023年1月内已审核的退货订单。
#### 数据清洗与转换
获取到原始数据后，需要对其进行清洗和转换，以便后续处理和分析。以下是一些常见的数据清洗步骤：
1. **字段映射**：将API返回的数据字段映射到内部系统所需的字段。例如，将API返回的`number`字段映射为内部系统的订单编号。
2. **数据类型转换**：确保所有字段的数据类型符合内部系统要求。例如，将字符串类型的日期转换为日期对象。
3. **缺失值处理**：处理缺失值或异常值。例如，对于某些关键字段，如果存在缺失值，可以设置默认值或进行补全。
#### 数据写入
完成数据清洗和转换后，下一步是将处理后的数据写入目标系统。这一步通常涉及数据库操作，例如插入或更新记录。以下是一个简单的示例代码片段，展示如何将处理后的数据写入数据库：
```python
import pymysql
# 假设已经获取并清洗了数据
processed_data = [
{"order_id": "XOUT0000000293", "status": "已审核", "created_at": "2023-01-15 10:30:45"},
# 更多记录...
]
# 数据库连接配置
db_config = {
'host': 'localhost',
'user': 'root',
'password': 'password',
'database': 'orders_db'
}
# 插入数据到数据库
connection = pymysql.connect(**db_config)
cursor = connection.cursor()
for record in processed_data:
sql = """
INSERT INTO sale_return_orders (order_id, status, created_at)
VALUES (%s, %s, %s)
ON DUPLICATE KEY UPDATE status=VALUES(status), created_at=VALUES(created_at)
"""
cursor.execute(sql, (record['order_id'], record['status'], record['created_at']))
connection.commit()
cursor.close()
connection.close()
```
上述代码片段展示了如何将处理后的退货订单数据插入到MySQL数据库中，并在主键冲突时更新现有记录。
通过以上步骤，我们实现了从调用汤臣倍健营销云接口获取退货订单数据，到清洗、转换并写入目标系统的全过程。这不仅提高了数据处理效率，还确保了数据的一致性和准确性。
### 轻易云数据集成平台ETL转换与写入金蝶云星辰V2API接口
在数据集成的生命周期中，第二步是将已经集成的源平台数据进行ETL（提取、转换、加载）转换，并转为目标平台金蝶云星辰V2API接口所能够接收的格式，最终写入目标平台。本文将详细探讨如何利用元数据配置，实现这一过程。
#### API接口配置
我们需要将数据写入金蝶云星辰V2的`/jdy/v2/scm/sal_in_bound`接口。该接口采用POST方法，支持多种字段类型，包括字符串、数组和对象等。以下是元数据配置的详细说明：
```json
{
"api": "/jdy/v2/scm/sal_in_bound",
"effect": "EXECUTE",
"method": "POST",
"number": "id",
"id": "id",
"name": "id",
"idCheck": true,
"request": [
{"field":"bill_source","label":"来源","type":"string","value":"ISV"},
{"field":"bill_date","label":"出库日期","type":"string","describe":"出库日期,格式：2019-01-01","value":"{{auditTime|date}}"},
{"field":"customer_id","label":"客户","type":"string","describe":"客户","value":"_findCollection find id from e4226d8c-6924-3a9d-8fd9-3503bbca47df where number={extCusCode}"},
{"field":"remark","label":"单据备注","type":"string","describe":"上传的附件url","value":"{remark}-来自营销云-{number}"},
{"field":"contact_address","label":"联系信息-详细地址","type":"string","describe":"联系信息-详细地址","value":"{shippingAddress}"},
{"field":"contact_linkman","label":"联系信息-联系人","type":"string","describe":"联系信息-联系人","value":"{contacts}"},
{"field":"contact_phone","label":"联系信息-联系方式","type":"string","describe":"联系信息-联系方式","value":"{phone}"},
{"field":"dept_number","label":"部门编码","type":"string","describe":"业务员","value":"100000"},
{
"field": "material_entity",
"label": "商品分录",
"type": "array",
"describe": "商品分录",
"value": "itemList",
"children": [
{"field": "material_id", "label": "商品id", "type": "string", "describe": "商品id",
"value": "_findCollection find id from d34b034c-bf37-3451-bb0a-b9693a86279a where number={extMaterialNo}"},
{"field": "stock_id", "label": "仓库id",
"type": "string",
describe: “仓库id”,
value: “1545748424274516992”},
{"field": “qty”, “label”: “数量”, “type”: “int”, “describe”: “数量”, “value”: “{{itemList.opernumber}}”},
{"field”: “tax_price”, “label”: “含税单价”, “type”: “int”, “describe”:“含税单价”,“value”:“{{itemList.taxunitprice}}”},
{"field”:“is_free”,“label”:“是否赠品”,“type”:“bool”,“describe”:“是否赠品”,“value”:“false”},
{"field”："unit_id”，"label”："单位id"，"type”："string"，"describe”："单位id"，"value”："_findCollection find base_unit_id from d34b034c-bf37-3451-bb0a-b9693a86279a where number={extMaterialNo}"},
{"field”："batch_no"，"label”："批次号"，"type”："string"，"describe”："批次号"，"value”："{{itemList._Flot}}"},
{"field”："comment"，"label”："行备注"，"type”："string"，"describe”："行备注"，"value”："{{itemList.remark}}"},
{"field”："kf_date”，”label”：”生产日期”，”type”：”string”，”describe”：”生产日期”，”value”：”{{itemList._Fmfg}}”},
{"field”，“valid_date”，“label”，“有效日期”，“type”，“string”，“describe”，“有效日期”，“value”，“{{itemList._Fexp}}”},
{“field”，“kf_period”，“label”，“保质期天数”，“type”，“string”，“describe”，“保质期天数”，“value”，“2”},
{“field”，“kf_type”，“label”，“保质期类型，1：天，2：月，3：年”，” type ”：“ string ”，“ describe ”：“ 保质期类型，1：天，2：月，3：年 ”，“ value ”：“ 3 ” }
]
},
{
field: custom_field,
label: 自定义字段,
type: object,
children: [
{ field: custom_field__1__2uvipsxiexanc2, label: 营销云单号, type: string, value: {number}},
{ field: custom_field__1__2xf7eyoonezx, label: 下单人, type: string}
]
}
]
}
```
#### 数据转换与写入
在实际操作中，我们需要对源数据进行提取、清洗和转换，以符合目标API接口的要求。以下是关键字段的处理方式：
1. **bill_source**：固定值为`ISV`。
2. **bill_date**：通过模板语法将审核时间`auditTime`格式化为`YYYY-MM-DD`。
3. **customer_id**：通过查找集合方法，从指定ID集合中查找客户编号`extCusCode`对应的ID。
4. **remark**：拼接备注字段和营销云单号。
5. **contact_address**、**contact_linkman**、**contact_phone**：直接映射对应的源字段。
6. **material_entity**：处理商品分录数组，其中每个子项包括多个字段，如商品ID、仓库ID、数量等。
例如，对于商品分录中的每个子项，我们需要：
- 根据外部物料编号`extMaterialNo`查找对应的商品ID和单位ID。
- 将数量和含税单价直接映射。
- 固定赠品标识为`false`。
- 映射批次号、行备注、生产日期和有效日期等。
#### 实际应用
在实际应用中，我们可以通过轻易云的数据处理功能，将以上配置应用于具体的数据流中。例如：
```json
{
"_findCollection find id from e4226d8c-6924-3a9d-8fd9-3503bbca47df where number={extCusCode}": {
"_findCollection find id from d34b034c-bf37-3451-bb0a-b9693a86279a where number={extMaterialNo}":{
"_findCollection find base_unit_id from d34b034c-bf37-3451-bb0a-b9693a86279a where number={extMaterialNo}"
}
}
}
```
通过这种方式，我们可以实现对复杂数据结构的精确转换和映射，确保数据能够无缝对接到金蝶云星辰V2平台。
总之，通过合理配置元数据和利用轻易云的数据处理能力，可以高效地完成从源平台到目标平台的数据ETL转换与写入过程。这不仅提高了数据集成效率，也确保了数据的一致性和准确性。
