### 金蝶云星空数据集成案例分享：收款单-新20231120_copy
在本次技术案例中，我们将详细探讨如何通过轻易云数据集成平台，实现金蝶云星空与金蝶云星空之间的高效、可靠的数据对接。具体方案名称为"收款单-新20231120_copy"，该方案主要涉及从源系统获取收款单数据，并批量写入目标系统中的过程。
为了确保大规模数据传输的效率和可靠性，本方案主要利用了以下几个关键特性：
1. **高吞吐量的数据写入能力**：我们采用了金蝶云星空提供的`batchSave` API，使得大量收款单能够快速、高效地写入到目标系统中，极大提升了数据处理时效性。
2. **定时抓取接口数据**：通过调用`executeBillQuery` API，从源系统定时可靠地抓取最新的收款单信息，确保每一笔交易都不会遗漏。
3. **异常处理与错误重试机制**：针对可能出现的数据传输异常或接口调用失败情况，我们设计并实现了一套完整的异常捕获和自动重试机制，保障整个集成过程的不间断运行。
4. **实时监控与日志记录**：为了全程跟踪各项操作状态及性能，我们利用集中监控和告警功能，对每个环节进行精准监测，并记录详细日志，以便后续审计和问题排查。
5. **自定义数据转换逻辑**：由于不同业务场景下的数据格式存在差异，通过自定义转换规则，我们实现了灵活适配各种业务需求，让复杂多变的数据结构也能顺利完成映射对接。
下一步，将具体介绍上述技术要点在实际项目中的应用细节，以及如何通过轻易云平台可视化工具优化配置, 以达到最佳实践效果。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成过程中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口来获取和加工数据。
#### 接口配置与调用
首先，我们需要配置接口的元数据，以确保能够正确地请求和处理数据。以下是针对`executeBillQuery`接口的元数据配置：
```json
{
"api": "executeBillQuery",
"method": "POST",
"number": "FBillNo",
"id": "FRECEIVEBILLENTRY_FEntryID",
"pagination": {
"pageSize": 500
},
"idCheck": true,
"condition_bk": [
[
{
"field": "field1",
"logic": "eqv2",
"value": null
}
]
],
"request": [
{"field":"FID","label":"实体主键","type":"string","value":"FID"},
{"field":"FBillNo","label":"单据编号","type":"string","value":"FBillNo"},
{"field":"FDOCUMENTSTATUS","label":"单据状态","type":"string","value":"FDOCUMENTSTATUS"},
{"field":"FCreatorId","label":"创建人","type":"string","value":"FCreatorId"},
{"field":"FAPPROVERID","label":"审核人","type":"string","value":"FAPPROVERID"},
{"field":"FCreateDate","label":"创建日期","type":"string","value":"FCreateDate"},
{"field":"FSETTLEORGID","label":"结算组织","type":"string","value":"FSETTLEORGID.FNumber"},
{"field":"FApproveDate","label":"审核日期","type":"string","value":"FApproveDate"},
{"field":"FSALEORGID","label":"销售组织","type":"string","value":"FSALEORGID.FNumber"},
{"field":"FEXCHANGETYPE","label":"汇率类型","type":"string","value":"FEXCHANGETYPE"},
{"field":"FRECEIVEAMOUNTFOR_H","label":"表头-应收金额","type":"string","value":"FRECEIVEAMOUNTFOR_H"},
{"field":...},
...
],
"otherRequest": [
{"field": "Limit", "label": "最大行数", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_PAGE_SIZE}"},
{"field": "StartRow", "label": "开始行索引", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_START_ROW}"},
{"field":...},
...
]
}
```
#### 请求参数解析
在上述配置中，关键字段包括：
- `api`: 指定要调用的API名称，这里是`executeBillQuery`。
- `method`: 请求方法，使用POST。
- `number`: 用于标识单据编号的字段。
- `id`: 用于标识唯一记录的字段。
- `pagination`: 分页设置，每页500条记录。
- `idCheck`: 是否进行ID检查，确保唯一性。
请求参数部分(`request`)定义了需要从金蝶云星空获取的数据字段，例如单据编号、创建人、审核人等。这些字段将用于后续的数据处理和分析。
其他请求参数(`otherRequest`)包括分页相关设置，如最大行数(`Limit`)和开始行索引(`StartRow`)，以及过滤条件(`FilterString`)等。这些参数可以根据实际需求进行调整，以优化查询性能和结果准确性。
#### 数据请求与清洗
在配置好元数据后，通过轻易云平台发起对金蝶云星空的API请求。以下是一个示例请求体：
```json
{
"FormId": "AR_RECEIVEBILL",
"FieldKeys": ["FID", ...],
...
}
```
该请求体包含了业务对象表单ID（如收款单`AR_RECEIVEBILL`）和需查询的字段集合（`FieldKeys`），这些字段会被转换为逗号分隔的字符串格式发送给金蝶云星空。
#### 数据清洗与转换
获取到原始数据后，需要进行清洗和转换，以便后续处理。例如，可以根据业务需求过滤掉无效或重复的数据，并对特定字段进行格式化处理。以下是一个简单的数据清洗示例：
```python
def clean_data(raw_data):
cleaned_data = []
for record in raw_data:
if record['FDOCUMENTSTATUS'] == 'C':
cleaned_data.append(record)
# 添加更多清洗逻辑
return cleaned_data
```
此函数过滤掉所有状态不是“已审核”（状态码为'C'）的记录，仅保留有效数据。
#### 数据写入与存储
最后，将清洗后的数据写入目标系统或存储介质。可以使用轻易云平台提供的数据写入功能，将处理后的数据无缝对接到目标数据库或其他系统中。
通过以上步骤，我们实现了从金蝶云星空获取、清洗并加工数据，为后续的数据分析和业务决策提供了可靠的数据基础。这一过程不仅提升了数据处理效率，也确保了数据质量和一致性。
### 使用轻易云数据集成平台将源数据转换并写入金蝶云星空API接口的技术案例
在数据集成生命周期的第二步，我们需要将已经集成的源平台数据进行ETL（提取、转换、加载）转换，最终写入目标平台——金蝶云星空API接口。以下是详细的技术步骤和配置说明。
#### 1. 配置API接口信息
首先，我们需要配置目标平台的API接口信息。在本案例中，使用的是金蝶云星空的`batchSave`接口，方法为`POST`。具体配置如下：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"method": "merge",
"field": "FBillTypeID,FBillNo,FDATE,FPAYORGI",
"bodyName": "details",
"header": ["FBillNo", "FSETTLEORGID", "FDATE", "FCURRENCYID", "FBillTypeID", "FCONTACTUNITTYPE", "FCONTACTUNIT", "FPAYUNITTYPE", "FPAYUNIT", "FBUSINESSTYPE", "FPAYORGID", "FSETTLECUR"],
"body": ["FSETTLETYPEID", "FRECTOTALAMOUNTFOR", "FACCOUNTID", "FPURPOSEID", "FRECEIVEITEMTYPE", "FSALEORDERNO"]
}
}
```
#### 2. 请求字段配置
接下来，我们需要根据元数据配置请求字段。这些字段将从源平台的数据中提取，并映射到金蝶云星空所需的格式。
```json
[
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","value":"{FBillNo}"},
{"field":"FSETTLEORGID","label":"结算组织","type":"string","describe":"结算组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{FCONTACTUNIT}","mapping":"6355fe20c4a6d536d27cd8dc","mappingDirection":"positive"},
{"field":"FCURRENCYID","label":"币别","type":"string","describe":"币别","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"PRE001"},
{"field":"FDATE","label":"业务日期","type":"string","describe":"业务日期","value":"{FDATE}"},
{"field":"FBillTypeID","label":"单据类型","type":"string","describe":"单据类型","value":"SKDLX01_SYS","parser":{"name":"ConvertObjectParser","params":"FNumber"}},
{"field":"FCONTACTUNITTYPE","label":"往来单位类型","type":"string","describe":"往来单位类型","value":"{FCONTACTUNITTYPE}"},
{"field":"FCONTACTUNIT","label":"往来单位","type":"string","describe":"往来单位","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{FCONTACTUNIT}"},
{"field":"FPAYUNITTYPE","label":"付款单位类型","type":"","value":"","describe":"","parser":{"name":"","params":""}},
{"field":"","label":"","type":"","value":"","describe":"","parser":{"name":"","params":""}}
]
```
#### 3. 数据转换与映射
在数据转换过程中，需要特别注意字段的解析和映射。例如，对于结算组织（`FSETTLEORGID`）字段，需要使用`ConvertObjectParser`进行解析，并将其值映射为金蝶云星空所需的格式。
```json
{
"field": "FSETTLEORGID",
"label": "结算组织",
"type": "string",
"describe": "",
// 使用 ConvertObjectParser 将 FCONTACTUNIT 的值转换为 FNumber 格式
// 并通过 mapping 映射到目标系统
// mappingDirection 表示正向映射，即从源系统到目标系统
}
```
#### 4. 明细数据处理
对于收款单明细（`details`），需要逐条处理并转换为目标格式。例如，表体-应收金额（`FRECTOTALAMOUNTFOR`）等字段：
```json
{
// 收款单明细数组，每个元素代表一条明细记录
// 每条记录包含多个字段，如结算方式、应收金额等
}
```
#### 示例代码片段
以下是一个简化后的代码示例，用于展示如何将上述配置应用于实际的数据处理流程：
```python
import requests
# 定义 API 接口 URL 和请求头信息
url = 'https://api.kingdee.com/batchSave'
headers = {'Content-Type': 'application/json'}
# 构建请求体，根据元数据配置填充相应字段值
payload = {
'FormId': 'AR_RECEIVEBILL',
'Operation': 'BatchSave',
'Model': {
'FID': '',
'FBillNo': source_data['FBillNo'],
'FSETTLEORGID': convert_to_fnumber(source_data['FCONTACTUNIT']),
'FCURRENCYID': 'PRE001',
# ...其他字段...
'details': [
{
'FSETTLETYPEID': convert_to_fnumber(detail['settle_type']),
'FACCOUNTID': convert_to_fnumber(detail['account_id']),
# ...其他明细字段...
}
for detail in source_data['details']
]
}
}
# 发起 POST 请求，将数据写入金蝶云星空系统
response = requests.post(url, json=payload, headers=headers)
# 检查响应状态码和返回结果，处理错误或成功情况
if response.status_code == 200:
print('Data successfully written to Kingdee Cloud.')
else:
print(f'Error: {response.status_code}, {response.text}')
```
通过以上步骤和代码示例，我们实现了从源平台数据到金蝶云星空API接口的数据转换和写入。此过程确保了数据在不同系统间的无缝对接，并满足业务需求。
