### 案例分享：物料同步金蝶=>聚水潭
在本次技术案例中，我们将探讨如何高效地实现金蝶云星空数据集成到聚水潭系统，通过轻易云数据集成平台，确保数据的准确无误、高效传输和实时监控。具体而言，我们的目标是通过调用金蝶云星空API `executeBillQuery` 定时抓取物料数据，并批量写入到聚水潭接口 `/open/jushuitan/itemsku/upload`。
整个过程开始于对来自金蝶云星空系统中的物料信息进行定时可靠的抓取。为此，我们设计了一套处理流程来解决分页和限流问题，以应对大量数据在短时间内导出的需求。例如，当接口请求超过一定次数限制时，将采用短暂休眠策略进行重试，从而避免因频繁请求导致的数据丢失或遗漏。
针对不同系统之间的数据格式差异，在将金蝶云星空的数据映射至聚水潭之前，需要进行必要的数据转换与校验。为了实现这一点，利用轻易云平台预置的规则引擎，对每个字段按照业务需求进行转换，同时保留原始数据信息以便追溯和审查。
此外，为了保证系统间联通性与稳定性，在提交最终结果到聚水潭前，还需要建立一套完备的异常处理机制。当遇到网络波动或接口响应超时时，通过自动化脚本记录错误日志并触发重试流程，使得整个传输链条具备高度容错能力。
通过这样的设置，不仅能大幅提高业务透明度，也能实时监控每一个操作环节，从而极大提升整体效率。在接下来的内容中，我们将详细讲述以上这些关键步骤，并逐步解析各部分技巧及注意事项。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的第一步。本文将深入探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口来获取物料数据，并对其进行初步加工。
#### 接口配置与调用
首先，我们需要了解`executeBillQuery`接口的基本配置。根据提供的元数据配置，接口采用POST方法进行调用，主要用于查询操作（QUERY）。以下是关键参数的配置：
- **api**: `executeBillQuery`
- **method**: `POST`
- **effect**: `QUERY`
- **number**: `FNumber`
- **id**: `FNumber`
- **idCheck**: `true`
请求字段包括物料ID、物料编码、物料名称等多个字段。这些字段在请求时需要按照特定格式传递，以确保能够正确获取到所需的数据。
#### 请求参数构建
根据元数据配置，我们需要构建一个包含所有必要字段的请求体。以下是一个示例请求体：
```json
{
"FormId": "BD_MATERIAL",
"FieldKeys": [
"FMATERIALID", "FNumber", "FName", "FSpecification", "FOldNumber",
"FBARCODE", "FDescription", "FMaterialGroup.FNumber", "FErpClsID",
"FDocumentStatus", "FForbidStatus", "FBaseUnitId.FName",
...
],
"FilterString": "FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FUseOrgId.FNumber='100'",
"Limit": "{PAGINATION_PAGE_SIZE}",
"StartRow": "{PAGINATION_START_ROW}"
}
```
上述请求体中，`FormId`指定了表单ID为`BD_MATERIAL`，即物料表单。`FieldKeys`包含了所有需要查询的字段，而`FilterString`则用于过滤满足条件的数据，例如最近同步时间后的数据。
#### 数据处理与清洗
在成功获取到原始数据后，需要对其进行初步清洗和加工。这一步骤通常包括以下几个方面：
1. **字段映射与转换**：将金蝶云星空返回的数据字段映射到目标系统所需的字段。例如，将金蝶中的`FMATERIALID`映射为目标系统中的物料ID。
2. **数据格式化**：根据目标系统要求，对日期、数值等特殊格式的数据进行转换。例如，将日期格式从YYYY-MM-DD转换为目标系统所需的格式。
3. **异常处理**：对于缺失或异常的数据进行处理，例如填充默认值或记录日志以便后续排查。
#### 示例代码
以下是一个示例代码片段，用于展示如何通过轻易云平台调用金蝶云星空接口并处理返回的数据：
```python
import requests
import json
# 配置API请求参数
url = 'https://api.kingdee.com/executeBillQuery'
headers = {'Content-Type': 'application/json'}
payload = {
'FormId': 'BD_MATERIAL',
'FieldKeys': [
'FMATERIALID', 'FNumber', 'FName', 'FSpecification', 'FOldNumber',
'FBARCODE', 'FDescription', 'FMaterialGroup.FNumber', 'FErpClsID',
...
],
'FilterString': "FApproveDate>='2023-01-01' and FUseOrgId.FNumber='100'",
'Limit': 100,
'StartRow': 0
}
# 发起API请求
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
# 数据处理与清洗
processed_data = []
for item in data:
processed_item = {
'material_id': item['FMATERIALID'],
'material_number': item['FNumber'],
...
}
processed_data.append(processed_item)
# 输出处理后的数据
print(json.dumps(processed_data, indent=4))
```
#### 总结
通过以上步骤，我们可以高效地调用金蝶云星空的`executeBillQuery`接口获取物料数据，并对其进行初步加工和清洗。这不仅确保了数据的一致性和准确性，还为后续的数据转换与写入奠定了坚实基础。在实际应用中，可以根据具体需求进一步优化和扩展这些操作，以满足不同业务场景的需求。
### 物料同步金蝶至聚水潭的ETL转换技术案例
在轻易云数据集成平台上，完成从金蝶到聚水潭的物料数据同步，需要经过数据请求与清洗、数据转换与写入两个主要阶段。本文将重点探讨生命周期的第二步，即如何将已经集成的源平台数据进行ETL转换，转为目标平台聚水潭API接口所能够接收的格式，并最终写入目标平台。
#### 元数据配置解析
在本案例中，我们需要将金蝶系统中的物料信息通过ETL流程转换并上传至聚水潭。以下是我们使用的元数据配置：
```json
{
"api": "/open/jushuitan/itemsku/upload",
"method": "POST",
"idCheck": true,
"request": [
{
"field": "items",
"label": "商品列表",
"type": "array",
"children": [
{
"field": "sku_id",
"label": "商品编码",
"type": "string",
"value": "{FNumber}",
"mapping": {
"target": "6477f6f6a517ed6f062fd49f",
"direction": "reverse"
}
},
{
"field": "i_id",
"label": "款式编码",
"type": "string",
"value": "{FNumber}",
"mapping": {
"target": "646333df81ab904e106b743c",
"direction": "reverse"
}
},
{
"field": "unit",
"label": "单位",
"type": "string",
"value": "{FBaseUnitId_FName}"
},
{
"field": "name",
"label": "名称",
"type": "string",
"value": "{FName}"
},
{
"field": "properties_value",
"label": "颜色规格",
"type":"string",
" value":"{FSpecification}"
}
]
}
]
}
```
#### 数据转换过程详解
1. **字段映射与转换**
在ETL过程中，首先要确保源平台（金蝶）的字段能够正确映射到目标平台（聚水潭）的字段。根据元数据配置，我们需要处理以下字段：
- `sku_id` 映射自 `{FNumber}`：商品编码
- `i_id` 映射自 `{FNumber}`：款式编码
- `unit` 映射自 `{FBaseUnitId_FName}`：单位
- `name` 映射自 `{FName}`：名称
- `properties_value` 映射自 `{FSpecification}`：颜色规格
2. **数组处理**
聚水潭API接口要求以数组形式提交商品列表，因此我们需要将金蝶系统中提取的数据组装成符合要求的JSON数组结构。每个商品信息应包含上述字段，并按指定格式排列。
3. **API请求构建**
在完成字段映射和数组处理后，构建API请求体。根据元数据配置，最终的请求体应如下所示：
```json
{
“items”: [
{
“sku_id”: “12345”,
“i_id”: “12345”,
“unit”: “件”,
“name”: “商品名称”,
“properties_value”: “红色”
},
...
]
}
```
4. **发送POST请求**
使用HTTP POST方法，将构建好的JSON请求体发送至聚水潭的`/open/jushuitan/itemsku/upload`接口。确保设置正确的HTTP头部信息，如Content-Type为application/json。
#### 实际操作步骤
1. **提取源数据**
从金蝶系统中提取所需的物料信息，确保获取到所有必要字段的数据。
2. **数据清洗与预处理**
对提取的数据进行清洗，包括去除无效记录、标准化字段值等，以确保后续转换过程顺利进行。
3. **构建JSON结构**
根据元数据配置，将清洗后的数据组装成符合目标API要求的JSON结构。
4. **发送HTTP请求**
使用编程语言（如Python、Java等）或集成工具（如Postman），发送POST请求至聚水潭API接口，并监控响应结果以确保成功写入。
#### 示例代码
以下是一个使用Python实现上述步骤的示例代码：
```python
import requests
import json
# 假设从金蝶系统提取的数据如下
data_from_kingdee = [
{"FNumber":"12345",
{"FBaseUnitId_FName":"件",
{"FName":"商品名称",
{"FSpecification":"红色"}
]
# 构建请求体
items = []
for item in data_from_kingdee:
items.append({
'sku_id': item['FNumber'],
'i_id': item['FNumber'],
'unit': item['FBaseUnitId_FName'],
'name': item['FName'],
'properties_value': item['FSpecification']
})
request_body = {'items': items}
# 发送POST请求
url = 'https://api.jushuitan.com/open/jushuitan/itemsku/upload'
headers = {'Content-Type': 'application/json'}
response = requests.post(url, headers=headers, data=json.dumps(request_body))
# 检查响应状态
if response.status_code == 200:
print('Data uploaded successfully')
else:
print(f'Failed to upload data: {response.text}')
```
通过以上步骤和代码示例，我们可以实现从金蝶到聚水潭的数据同步。在实际应用中，根据具体需求和环境可能需要进行适当调整和优化。
