### 系统对接集成案例分享：汤臣倍健营销云数据集成到金蝶云星辰V2
为了进一步优化企业内部的数据处理流程和提高业务效率，我们针对汤臣倍健的营销云与金蝶云星辰V2系统之间的数据集成需求，开发了一套高效、可靠且可扩展的解决方案。本技术案例将详细介绍该解决方案，其中涉及多个关键技术点，包括API调用、分页处理、异常重试机制等。
在此次实施中，我们主要利用了轻易云数据集成平台提供的集中监控和告警功能，以确保整个数据流动过程中的透明性和可控性。首先，通过调用汤臣倍健营销云接口`/api/openapi/v1/erp/order/honour/agreement/header`定时抓取订单头信息。为应对潜在的大量数据写入需求，该接口支持高吞吐量的数据获取能力，有助于避免漏单现象。
在完成从汤臣倍健营销云端获取数据后，需进行自定义转换逻辑，以适应金蝶云星辰V2要求的数据格式。在这部分转换过程中，充分利用了轻易云平台所提供的可视化设计工具，使得各字段映射关系一目了然，从而减少人为错误并简化操作步骤。
紧接着，将转换后的有效数据批量插入到金蝶云星辰V2系统，对接使用的是其标准写入API `/jdy/v2/scm/sal_out_bound`。这里需要注意的是，由于两者间存在一定程度的限流问题，对于大批量同步而言，需要细致设计分片和限速策略，实现高效但平稳的推送模式。此外，还实现了一整套完善的错误日志记录及自动重试机制，以保障即便发生网络抖动或其他意外情况，也能确保最终所有有价值的数据都精确传输至目标系统里。
通过这样的精细化管理，不仅使得整个项目顺利落地，更大幅提升了两个复杂系统之间互联互动能力，为企业今后的数字资产运营打下坚实基础。
### 调用汤臣倍健营销云接口获取并加工数据
在数据集成的生命周期中，第一步是从源系统获取数据。本文将详细探讨如何通过调用汤臣倍健营销云的接口`/api/openapi/v1/erp/order/honour/agreement/header`来获取订单数据，并对其进行初步加工。
#### 接口调用配置
首先，我们需要配置API调用的元数据。以下是该接口的元数据配置细节：
```json
{
"api": "/api/openapi/v1/erp/order/honour/agreement/header",
"effect": "QUERY",
"method": "POST",
"number": "no",
"id": "id",
"idCheck": true,
"request": [
{"field":"orgId","label":"组织ID","type":"string","describe":"111","value":"da9e0f31ee8f480585ecaff6376e3592"},
{"field":"page","label":"页码","type":"string","describe":"111","value":"1"},
{"field":"id","label":"订单id","type":"string","describe":"111"},
{"field":"applyerId","label":"要货方id","type":"string","describe":"111"},
{"field":"supplierId","label":"供货方id","type":"string","describe":"111"},
{"field":"no","label":"订单号","type":"string","describe":"111"},
{"field":"distributionType","label":"分销类型","type":"string","describe":"111"},
{"field":"distributorId","label":"分销商id","type":"string","describe":"111"},
{"field":"orderStatus","label":"订单状态","type":"string","describe":"111", "value": "WAIT_DELIVERY,PART_DELIVERY,ALL_DELIVERY,WAIT_OUT_STORAGE,PART_OUT_STORAGE,ALL_OUT_STORAGE,PART_CONFIRM,CONFIRM,AUDIT_SUCCESS,FINISH"},
{"field":"createDt","label":"创建时间","type":"string","describe":"111"},
{"field":"orderTypeCode","label":"订单类型,如普通订单、直运销售","type": "string", "describe": "111"},
{"field": "isDeliveryFreezed", "label": "是否暂停发货", "type": "string", "describe": "111"},
{"field": "nature", "label": "单据类型1订单、2退货", "type": "string", "describe": "111", "value": "1"},
{"field": "relatedApplyerId", "label": "关联交易经销商id", "type": "string", "describe": "111"},
{"field": "saleDistribution", "label": "销售渠道", "type": "string", "describe": "111"},
{"field": "disApplyerId", "label": "分销商id", "type": "string", "describe": "111"},
{"field": "startDt", "label": "订单时间（开始）", "type": "string", "describe": "111"},
{"field": "endDt", "label": "订单时间（结束）", "type": "string", "describe：""},
{"field：""appStartDt"，""标签：""审批时间（开始）"，""类型：""字符串"，""描述：""},
{“字段”： “appEndDt”，“标签”： “审批时间（结束）”，“类型”： “字符串”，“描述”： “”},
{“字段”： “lastStartDt”，“标签”： “最后修改时间（开始）”，“类型”： “字符串”，“描述”： “”， “值”： “{{LAST_SYNC_TIME|datetime}}”},
{“字段”： “lastEndDt”，“标签”： “最后修改时间（结束）”，“类型”： “字符串”，“描述”： “”， “值”： “{{CURRENT_TIME|datetime}}”}
],
autoFillResponse: true
}
```
#### 请求参数解析
在配置中，`request`部分定义了请求参数，包括组织ID、页码、订单ID等。这些参数用于过滤和分页查询，确保我们能够获取到符合条件的数据。
- `orgId`: 固定值，用于标识组织。
- `page`: 页码，默认从第一页开始。
- `orderStatus`: 多种状态组合，用于筛选不同状态的订单。
- `lastStartDt` 和 `lastEndDt`: 分别表示上次同步时间和当前时间，用于增量同步。
#### 数据请求与清洗
通过上述配置，我们可以构建一个POST请求来获取数据。以下是一个示例请求体：
```json
{
"orgId": "da9e0f31ee8f480585ecaff6376e3592",
"page": 1,
...
// 其他参数根据需求填写
}
```
发送请求后，我们会收到一个包含多个订单信息的响应。接下来，需要对这些数据进行清洗和初步加工。
#### 数据转换与写入
在清洗过程中，我们需要关注以下几点：
1. **字段映射**: 确保源系统中的字段与目标系统中的字段一一对应。例如，将`orderStatus`映射到目标系统中的相应状态字段。
2. **数据格式转换**: 将日期格式统一为目标系统要求的格式。
3. **增量更新**: 使用`lastStartDt`和`lastEndDt`确保只处理自上次同步以来的新数据或更新的数据。
清洗后的数据可以直接写入目标系统，或者进一步处理后再写入。
#### 实时监控与异常处理
在整个过程中，实时监控和异常处理至关重要。我们需要确保每个步骤都能被追踪，并在出现异常时及时报警和处理。例如：
- **日志记录**: 每次API调用及其响应都应记录日志，以便后续分析和排查问题。
- **错误处理**: 对于API返回的错误信息，应有相应的处理机制，如重试或告警。
通过以上步骤，我们可以高效地从汤臣倍健营销云获取并加工所需的数据，为后续的数据集成奠定基础。
### 利用轻易云数据集成平台实现金蝶云星辰V2 API接口的数据转换与写入
在数据集成的生命周期中，第二步至关重要，即将已集成的源平台数据进行ETL（Extract, Transform, Load）转换，并转为目标平台所能接收的格式。本文将详细探讨如何利用轻易云数据集成平台，将订单数据转换为金蝶云星辰V2 API接口所需的格式，并最终写入目标平台。
#### 数据请求与清洗
首先，我们需要从源系统获取原始订单数据。这个过程涉及到对源数据进行初步清洗和预处理，以确保数据质量。此步骤通常包括去除重复记录、处理缺失值以及标准化字段格式等操作。
#### 数据转换与写入
一旦我们获得了清洗后的源数据，接下来就是将这些数据转换为金蝶云星辰V2 API接口所能接收的格式。根据提供的元数据配置，我们需要构建一个符合API要求的数据结构。
以下是关键字段及其对应的配置：
1. **单据来源**：
```json
{"field":"bill_source","label":"单据来源，固定传入ISV","type":"string","describe":"单据来源，固定传入APP","value":"ISV"}
```
该字段固定传入值`ISV`，用于标识单据来源。
2. **出库日期**：
```json
{"field":"bill_date","label":"出库日期,格式：2019-01-01","type":"datetime","describe":"出库日期,格式：2019-01-01","value":"{{approveDt|date}}"}
```
出库日期需要按照`YYYY-MM-DD`格式传递，可以通过模板引擎将原始日期字段转换为指定格式。
3. **客户ID**：
```json
{"field":"customer_id","label":"客户id","type":"string","describe":"客户信息","value":"_findCollection find id from c2313f31-6597-3ad7-8314-129e3cfa851a where number={clientAppNo}"}
```
客户ID通过查询集合来获取，具体方法是根据`clientAppNo`查找对应的客户ID。
4. **商品分录**：
商品分录是一个数组，每个商品条目包含多个字段，如下所示：
```json
{"field":"material_entity","label":"商品分录","type":"array","describe":"商品分录","value":"details","children":[{"field":"material_number","label":"商品","type":"string","describe":"商品","value":"{{details.extNo}}"},{"field":"stock_id","label":"仓库","type":"string","describe":"仓库","value":"1537061721468863488"},{"field":"qty","label":"数量","type":"string","describe":"数量","value":"{{details.quantity}}"},{"field":"unit_id","label":"单位id","type":"","describe":"","value":""},{"field":"","label":"","type":"","describe":"","value":""}]}
```
每个商品条目包含以下关键字段：
- **material_number**: 商品编号，通过模板引擎从`details.extNo`中提取。
- **stock_id**: 仓库ID，这里使用固定值`1537061721468863488`。
- **qty**: 商品数量，通过模板引擎从`details.quantity`中提取。
- **unit_id**: 单位ID，需要通过查询集合来获取，例如：
```json
{"field": "unit_id", "label": "单位id", "type": "string", "describe": "单位", "value": "_findCollection find base_unit_id from 498e7562-ac4a-3ba3-a3bb-ccdacd6dc8f0 where number={{details.extNo}}"}
```
5. **自定义字段**：
自定义字段可以根据业务需求进行扩展，例如营销云单号和下单人信息：
```json
{"field": "custom_field", "label": "自定义字段", "type": "object", "children":[{"field": "custom_field__1__2uvhrxiedyh3hl45", "label": "营销云单号", "type": "string", "value": "{no}"},{"field": "custom_field__1__2xf85kb8edyhyb", "label": "下单人", "type": "string", "value": "{salesmanName}"}]}
```
#### 实际应用案例
假设我们已经从源系统获取了如下订单数据：
```json
{
"approveDt": "2023-10-01",
"clientAppNo": "C12345",
...
// 其他订单相关信息
}
```
我们需要将其转换为金蝶云星辰V2 API接口所需的数据结构：
```json
{
"bill_source": "ISV",
"bill_date": "{{approveDt|date}}",
...
// 其他必要字段
}
```
通过轻易云的数据集成平台，我们可以配置并执行上述转换规则，将订单数据成功写入金蝶云星辰V2系统，实现跨系统的数据无缝对接。
以上即是利用轻易云数据集成平台实现金蝶云星辰V2 API接口的数据转换与写入的详细技术过程。希望本文能够为您在实际项目中提供有价值的参考。
