### 汤臣倍健营销云数据集成到金蝶云星辰V2的案例分享
在当今复杂多变的商业环境中，企业的数据系统往往需要通过高效、可靠的数据集成方式，实现不同平台间的数据交互。本次分享的是一个以实际运行方案“采购入库同步（Life-Space）杭州益倍盛”为例的技术案例，其中主要涉及汤臣倍健营销云的数据如何集成到金蝶云星辰V2。
该项目利用了轻易云数据集成平台，重点解决了以下几个关键技术问题：
1. **API接口调用及分页处理**：首先，通过汤臣倍健营销云提供的/erp/api/order/query/purInWarehsOrder API接口获取采购入库单数据，在这一过程中需解决分页和限流的问题。为了确保不漏单，每个接口请求返回的数据都经过严格校验，并实现定时抓取机制。
2. **数据格式转换与映射**：由于汤臣倍健营销云与金蝶云星辰V2之间存在数据格式差异，我们自定义了一套适用于业务需求的数据转换逻辑。通过可视化设计工具，将从汤臣倍健营销云获取到的原始JSON格式数据，按照预设规则转换为符合金蝶API /jdy/v2/scm/pur_inbound 接口要求的结构，提高了对接效率。
3. **批量写入与异常处理**：针对大规模数据写入场景，我们使用轻易云平台支持的大吞吐量能力实现快速写入，同时配备集中监控和告警系统，以实时跟踪任务状态。一旦发生异常，重试机制会自动触发，从而保证全程无缝衔接，不遗漏任何关键信息。
4. **实时监控与日志记录**：在整个流程中，对各个环节进行了详细的日志记录和实时监控。这不仅提升了透明度，还使得问题定位更加迅速准确，为后续维护提供了有力保障。
上述几点是本次项目成功实施的重要因素。下一部分我们将具体探讨每一个环节所采用的方法和实践细节，以便为其他类似项目提供借鉴经验。
### 调用源系统汤臣倍健营销云接口/erp/api/order/query/purInWarehsOrder获取并加工数据
在轻易云数据集成平台中，调用源系统接口是数据处理生命周期的第一步。本文将详细探讨如何通过调用汤臣倍健营销云的API接口`/erp/api/order/query/purInWarehsOrder`来获取并加工采购入库数据。
#### 接口概述
该接口用于查询采购入库订单信息，支持POST请求方式。其主要参数配置如下：
- **tenantId**: 经销商ID（必填），如：08e2fd9d074f4ef7b5e6416b74d006d6
- **yxyNumber**: 营销云销售订单号，如：lzwhy0121012002
- **number**: 系统订单号，如：CGDD00000003744
- **status**: 订单状态，0表示未审核，1表示已审核（已出库）
- **beginTime**: 开始时间，格式为YYYY-MM-DD或YYYY-MM-DD HH:MM:SS
- **endTime**: 结束时间，格式同上
- **pageNo**: 页码，默认值为1
- **pageSize**: 每页条数，默认值为30
- **timeType**: 查询时间段标识，0表示基于创建时间查询（默认），1表示基于更新时间查询
#### 元数据配置解析
根据提供的元数据配置，我们可以看到以下关键点：
1. **请求参数配置**
- `tenantId`、`beginTime`、`endTime`等字段是必填项。
- `number`和`yxyNumber`字段在传递时会使其他时间状态条件无效。
- `status`字段用于过滤订单状态。
- `pageNo`和`pageSize`用于分页控制。
2. **自动填充响应**
- 配置中设置了`autoFillResponse:true`，意味着平台会自动处理并填充响应数据。
3. **条件过滤**
- 配置中有一个条件过滤：当物料编号（materialNumber）包含"F.A"时，不进行匹配（notlike）。
#### 实际调用与数据处理
在实际操作中，我们需要按照以下步骤进行：
1. **构建请求参数**
根据元数据配置构建请求参数，例如：
```json
{
"tenantId": "08e2fd9d074f4ef7b5e6416b74d006d6",
"beginTime": "{{LAST_SYNC_TIME|datetime}}",
"endTime": "{{CURRENT_TIME|datetime}}",
"status": "1",
"pageNo": "1",
"pageSize": "30",
"timeType": "1"
}
```
2. **发送请求**
使用POST方法将构建好的请求参数发送到API接口：
```http
POST /erp/api/order/query/purInWarehsOrder HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"tenantId": "08e2fd9d074f4ef7b5e6416b74d006d6",
"beginTime": "{{LAST_SYNC_TIME|datetime}}",
"endTime": "{{CURRENT_TIME|datetime}}",
"status": "1",
"pageNo": "1",
"pageSize": "30",
"timeType": "1"
}
```
3. **处理响应数据**
响应的数据会自动填充到平台中，并根据条件进行过滤。例如，如果物料编号包含"F.A"，则该条记录不会被匹配。
4. **错误处理与重试机制**
在实际操作中，还需要考虑网络异常、接口超时等情况。可以设置重试机制，例如每隔几分钟重试一次，共重试三次，以确保数据能够成功获取。
#### 数据清洗与转换
在获取到原始数据后，需要对其进行清洗和转换，以便写入目标系统。这包括但不限于：
- 数据格式转换：将日期格式统一为目标系统所需的格式。
- 字段映射：将源系统字段映射到目标系统对应字段。
- 数据校验：确保所有必填字段都有值且符合业务规则。
例如，将原始响应中的日期字段从"YYYY-MM-DD HH:MM:SS"转换为"YYYYMMDDHHMMSS"格式：
```python
import datetime
def convert_date_format(date_str):
date_obj = datetime.datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
return date_obj.strftime("%Y%m%d%H%M%S")
```
通过上述步骤，我们可以高效地从汤臣倍健营销云获取采购入库订单信息，并对其进行必要的清洗和转换，为后续的数据写入做好准备。
### 使用轻易云数据集成平台实现采购入库数据同步至金蝶云星辰V2
在数据集成的生命周期中，ETL（提取、转换、加载）是关键步骤之一。本文将重点探讨如何使用轻易云数据集成平台，将源平台的数据进行ETL转换，并最终写入目标平台金蝶云星辰V2 API接口。
#### 配置元数据
在配置元数据时，我们需要根据目标平台的API接口要求，定义请求参数和字段映射。以下是针对金蝶云星辰V2 API `/jdy/v2/scm/pur_inbound` 接口的元数据配置：
```json
{
"api": "/jdy/v2/scm/pur_inbound",
"effect": "EXECUTE",
"method": "POST",
"number": "1",
"id": "1",
"name": "1",
"idCheck": true,
"request": [
{"field": "bill_date", "label": "单据日期", "type": "string", "describe": "单据日期", "value": "{{auditTime|date}}"},
{"field": "bill_no", "label": "单据编码", "type": "string", "describe": "单据编码"},
{"field": "transtype", "label": "业务类型", "type": "string", "value": "2"},
{"field": "supplier_id", "label": "供应商编码", "type": "string", "describe": "供应商编码",
"value":"1325910470984514560"},
{"field":"remark","label":"备注","type":"string","describe":"商品编码","value":"{remark}-来自营销云-{yxyNumber}"},
{
...
}
]
}
```
#### 数据提取与清洗
首先，从源系统提取采购入库数据。在提取过程中，需要对数据进行初步清洗，以确保数据格式和内容的正确性。例如，将日期格式化为目标系统所需的格式，去除无效字符等。
```python
# 示例代码：提取并清洗数据
source_data = extract_data_from_source()
cleaned_data = clean_data(source_data)
```
#### 数据转换
在数据转换阶段，根据元数据配置，将源系统的数据字段映射到目标系统所需的字段。例如，将源系统的`auditTime`字段转换为`bill_date`，并将其格式化为日期字符串。
```python
# 示例代码：数据转换
transformed_data = {
'bill_date': format_date(cleaned_data['auditTime']),
'bill_no': cleaned_data['billNo'],
'transtype': '2',
'supplier_id': '1325910470984514560',
'remark': f"{cleaned_data['remark']}-来自营销云-{cleaned_data['yxyNumber']}",
...
}
```
对于数组类型的字段，如商品分录（`material_entity`），需要逐一处理每个子项，并进行相应的字段映射和转换。
```python
# 示例代码：处理数组类型字段
material_entity = []
for item in cleaned_data['itemList']:
material_entity.append({
'material_number': item['extMaterialNo'],
'stock_id': '1320321849665543168',
'is_free': False,
'qty': item['opernumber'],
...
})
transformed_data['material_entity'] = material_entity
```
#### 数据写入
最后，将转换后的数据通过API接口写入目标系统金蝶云星辰V2。使用HTTP POST方法发送请求，并处理响应结果。
```python
# 示例代码：发送HTTP POST请求
import requests
url = 'https://api.kingdee.com/jdy/v2/scm/pur_inbound'
headers = {'Content-Type': 'application/json'}
response = requests.post(url, json=transformed_data, headers=headers)
if response.status_code == 200:
print('Data successfully written to Kingdee Cloud')
else:
print(f'Failed to write data: {response.text}')
```
通过上述步骤，我们实现了从源系统到金蝶云星辰V2的采购入库数据同步。轻易云数据集成平台提供了全生命周期管理和可视化操作界面，使得整个过程更加透明和高效。
