### 案例分享：金蝶物料同步简道云的技术实践
在此次案例中，我们将聚焦于如何通过高效的数据集成方案，将金蝶云星空系统中的物料数据准确无误地同步至简道云。为了实现这一目标，主要使用了金蝶云星空的executeBillQuery接口和简道云的数据写入API。
#### 数据获取与处理
首先，我们需要从金蝶云星空系统中批量抓取物料数据。这一步关键在于调用其提供的executeBillQuery API，该接口不仅支持灵活的查询条件设置，还能够高效处理分页和限流问题，以确保大规模数据获取过程中的稳定性。在此过程中，轻易云平台自带的定时可靠抓取功能，可以帮助我们定期自动拉取最新数据，避免漏单情况发生。
示例代码如下：
```python
# 调用executeBillQuery接口获取金蝶物料数据
import requests
def fetch_kingdee_data():
url = "https://example.com/api/kingdee/executeBillQuery"
params = {
"billType": "material",
"pageNumber": 1,
"pageSize": 100
}
response = requests.get(url, params=params)
if response.status_code == 200:
return response.json()
else:
# 错误处理机制
handle_error(response)
data = fetch_kingdee_data()
```
#### 数据转换与兼容性调整
由于金蝶云星空与简道云之间存在一定的数据格式差异，需要对获取到的数据进行适当转换。我们利用轻易云提供的大量自定义转换逻辑支持，对字段进行映射和结构调整，使得最终生成的数据符合简道云API接受要求。
如需将`MaterialID`字段映射为`ItemID`：
```python
def transform_data(kingdee_data):
transformed_data = []
for item in kingdee_data['items']:
new_item = {
'ItemID': item['MaterialID'],
'Name': item['MaterialName'],
'Quantity': item['StockQty']
}
transformed_data.append(new_item)
return transformed_data
transformed_data = transform_data(data)
```
#### 批量写入操作及监控机制
完成数据转换后，即可通过调用简道云提供的数据创建接口(/api/v2/app/{app_id}/entry/{entry_id}/data_create)来批量写入这些信息。在整个写入过程中，为保证任务执行效率以及错误排查，我们依托平台自带的集中监控和告警系统，对每一个步骤进行了性能跟踪和状态监控。一旦出现异常，即刻触发重试或报警机制，以及时修复问题。
示例代码
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在轻易云数据集成平台中，调用源系统接口是数据集成生命周期的第一步。本文将详细探讨如何通过调用金蝶云星空的`executeBillQuery`接口来获取和加工物料数据。
#### 接口配置与请求参数
首先，我们需要配置接口的元数据。根据提供的元数据配置，`executeBillQuery`接口采用POST方法进行调用，主要参数包括：
- `api`: "executeBillQuery"
- `method`: "POST"
- `number`: "FNumber"
- `id`: "FNumber"
- `pagination`: {"pageSize": 100}
- `idCheck`: true
- `condition_bk`: [[{"field":"field1","logic":"eqv2","value":null}]]
请求参数部分主要包含以下字段：
```json
[
{"field":"FMATERIALID","label":"实体主键","type":"string","value":"FMATERIALID"},
{"field":"FNumber","label":"编码","type":"string","value":"FNumber"},
{"field":"FName","label":"名称","type":"string","value":"FName"},
{"field":"FSpecification","label":"规格型号","type":"string","value":"FSpecification"},
{"field":"FOldNumber","label":"旧物料编码","type":"string","value":"FOldNumber"},
{"field":"FBARCODE","label":"条码","type":"string","value":"FBARCODE"},
{"field":"FDescription","label":"描述","type":"string","value":"FDescription"},
{"field":"FMaterialGroup_FNumber","label":"物料分组","type":"string","value":"FMaterialGroup.FNumber"},
{"field":"FErpClsID","label":"物料属性","type":"string","value":"FErpClsID"},
{"field":...}
]
```
其他请求参数包括分页参数和过滤条件：
```json
[
{"field": "Limit", "label": "最大行数", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_PAGE_SIZE}"},
{"field": "StartRow", "label": "开始行索引", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_START_ROW}"},
{"field": "TopRowCount", "label": "返回总行数", "type": "int", "describe": "金蝶的查询分页参数"},
{"field":...}
]
```
#### 数据请求与清洗
在实际操作中，我们首先构建请求体，将上述字段和分页参数填充到请求体中。示例如下：
```json
{
"FormId": "BD_MATERIAL",
"FieldKeys": ["FMATERIALID", ...],
"FilterString": "FApproveDate>='{{LAST_SYNC_TIME|datetime}}'",
...
}
```
通过POST方法发送请求后，系统会返回包含物料信息的数据集。此时，需要对返回的数据进行清洗和处理，以确保数据质量和一致性。例如，可以对空值进行填充，对字段类型进行转换等。
#### 数据转换与写入
清洗后的数据需要进一步转换为目标系统所需的格式。在轻易云平台上，可以利用内置的数据转换工具，将原始数据映射到目标字段。例如，将金蝶云星空中的`FMATERIALID`映射到目标系统中的`MaterialID`。
```json
{
...
{
"sourceField": "FMATERIALID",
"targetField": "MaterialID",
...
}
}
```
完成数据转换后，即可将处理好的数据写入目标系统，实现不同系统间的数据同步。
#### 实践案例
假设我们需要同步金蝶云星空中的物料信息到简道云。首先，通过调用`executeBillQuery`接口获取物料信息，并对返回的数据进行清洗和转换。然后，将处理好的数据通过API写入简道云，实现两者间的数据集成。
具体步骤如下：
1. **配置元数据**：根据提供的元数据配置，设置API调用参数。
2. **发送请求**：构建请求体并发送POST请求。
3. **清洗数据**：对返回的数据进行必要的清洗和处理。
4. **转换数据**：将清洗后的数据映射到目标系统字段。
5. **写入目标系统**：通过API将处理好的数据写入简道云。
通过以上步骤，可以实现金蝶云星空与简道云之间的无缝数据集成，提高业务流程的自动化程度和效率。
### 使用轻易云数据集成平台实现金蝶物料同步至简道云
在数据集成的生命周期中，ETL（提取、转换、加载）是关键步骤之一。本文将重点探讨如何使用轻易云数据集成平台，将从金蝶系统提取的物料数据转换为简道云API接口所能接收的格式，并最终写入简道云。
#### 数据请求与清洗
首先，我们需要从金蝶系统中提取原始物料数据。这一步骤通常涉及调用金蝶的API接口，获取所需的物料信息。假设我们已经成功获取了如下格式的数据：
```json
{
"FNumber": "MAT001",
"FName": "物料A",
"FSpecification": "规格A",
"FBaseUnitId_FNumber": "UNIT001"
}
```
#### 数据转换与写入
接下来，我们需要将上述数据转换为简道云API接口能够接收的格式。根据元数据配置，简道云API接口要求的数据格式如下：
```json
{
"_widget_1669962898406": "MAT001",
"_widget_1669962898407": "物料A",
"_widget_1669962898408": "规格A",
"_widget_1669969813205": "UNIT001",
"_widget_1677637774814": "规格A",
"is_start_workflow": "true",
"is_start_trigger": "false",
"transaction_id": "",
"appId": "63899c8e6705fb000870437d",
"entryId": "63899c9264b9a9000ad4d3ce"
}
```
为了实现这一转换，我们需要配置轻易云平台中的ETL规则。以下是详细步骤：
1. **字段映射**：
- `FNumber` 映射到 `_widget_1669962898406`
- `FName` 映射到 `_widget_1669962898407`
- `FSpecification` 映射到 `_widget_1669962898408` 和 `_widget_1677637774814`
- `FBaseUnitId_FNumber` 映射到 `_widget_1669969813205`
2. **配置解析器**：
每个字段都使用 `ConvertObjectParser`，其参数为 `value`，表示直接取值。
3. **其他请求参数**：
- `is_start_workflow`: 固定值 `"true"`
- `is_start_trigger`: 固定值 `"false"`
- `transaction_id`: 动态生成或传递
- `appId`: 固定值 `"63899c8e6705fb000870437d"`
- `entryId`: 固定值 `"63899c9264b9a9000ad4d3ce"`
#### 实际操作
在轻易云平台中进行配置时，需要按照以下步骤操作：
1. **创建ETL任务**：
在轻易云平台中创建一个新的ETL任务，选择数据源为金蝶系统。
2. **配置字段映射**：
在ETL任务中配置字段映射规则，根据上述映射关系，将金蝶系统中的字段对应到简道云API接口所需的字段。
3. **设置解析器**：
为每个字段设置解析器为 `ConvertObjectParser`，并指定参数为 `value`。
4. **添加其他请求参数**：
在请求体中添加固定值和动态生成的其他请求参数，如 `is_start_workflow`, `is_start_trigger`, `transaction_id`, `appId`, 和 `entryId`。
5. **测试与验证**：
配置完成后，可以通过测试功能验证数据是否正确地被转换并写入简道云。如果一切正常，则可以将该任务投入生产环境。
#### API调用示例
最终生成的HTTP请求示例如下：
```http
POST /api/v2/app/63899c8e6705fb000870437d/entry/63899c9264b9a9000ad4d3ce/data_create HTTP/1.1
Host: www.jiandaoyun.com
Content-Type: application/json
{
"_widget_1669962898406": "MAT001",
"_widget_1669962898407": "物料A",
"_widget_1669962898408": "规格A",
"_widget_1669969813205": "UNIT001",
"_widget_1677637774814": "规格A",
"is_start_workflow": true,
"is_start_trigger": false,
"transaction_id": "<dynamic_transaction_id>",
"appId": "63899c8e6705fb000870437d",
"entryId": "63899c9264b9a9000ad4d3ce"
}
```
通过以上步骤，我们成功地将金蝶系统中的物料数据转换并写入到简道云，实现了不同系统间的数据无缝对接。这不仅提升了业务流程的自动化程度，也极大地提高了数据处理的效率和准确性。
