### 金蝶云星空数据集成案例：收款单-新20231120_copy
在本次技术案例中，我们将分享如何使用轻易云数据集成平台对接金蝶云星空，实现从一个金蝶云星空系统向另一个同类系统的数据迁移。具体的集成方案名称为“收款单-新20231120_copy”。此次项目重点在于确保大量数据高效、可靠地写入到目标系统，同时实时监控和处理接口间潜在的问题。
#### 系统对接概述
首先，利用金蝶云星空的executeBillQuery API接口，从源系统中获取需要迁移的收款单数据。这些获取的数据经过清洗和转换后，通过batchSave API接口批量写入到目标金蝶云星空系统中。在这一过程中，我们遇到了多个技术挑战，包括分页限流、异常处理以及实时监控等问题，以下是详细解决方案及其应用场景。
#### 关键技术要点
1. **高吞吐量的数据写入能力**：通过优化API调用策略，使得每次调用都能最大化数据传输效率，从而提升整体任务时效性。
2. **自定义数据转换逻辑**：为了适应源与目标系统之间的数据结构差异，自定义了一套灵活的数据映射规则，确保各个字段能够对应匹配。
3. **集中监控与告警**：配置了全面的监控和告警机制，实时跟踪整个集成过程中的状态变化。一旦检测到异常情况，例如接口响应超时或网络故障，即可迅速采取相应措施进行恢复。
4. **异常处理与重试机制**：针对可能出现的网络波动或API调用失败，设计了一套完善的重试机制，以保证即使在不稳定环境下也能顺利完成任务。
5. **定制化日志记录**: 在每个重要步骤设置了详细日志记录，不仅方便日常运维查错，也为未来类似项目提供参考依据。
这些关键技术点帮助我们有效解决了多项复杂问题，使得整个集成过程既安全又高效。下一步内容将深入探讨上述特性的实现细节，并展示如何通过实际代码和配置进一步优化我们的解决方案。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成过程中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口来获取和加工数据。
#### 接口配置与请求参数
首先，我们需要配置接口的元数据，以确保能够正确地调用金蝶云星空的API。以下是关键的元数据配置：
```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":...}
],
"otherRequest": [
{"field": "Limit", "label": "最大行数", "type": "string", "describe": "金蝶的查询分页参数", "value": "2000"},
{"field": "StartRow", "label": "开始行索引", "type": "string", "describe": "金蝶的查询分页参数",
"value": "{PAGINATION_START_ROW}"},
{"field":...}
]
}
```
#### 请求构建
在构建请求时，需要特别注意以下几个关键字段：
- `FormId`: 表单ID，必须填写金蝶的表单ID，例如`AR_RECEIVEBILL`。
- `FieldKeys`: 查询字段集合，通过解析器将数组转换为字符串格式。
- `FilterString`: 用于过滤条件，例如根据时间范围和特定单位编号进行过滤。
示例请求体如下：
```json
{
"FormId": "AR_RECEIVEBILL",
"FieldKeys": ["FID", ..., ...].join(","),
...
}
```
#### 数据获取与处理
通过发送POST请求到金蝶云星空的`executeBillQuery`接口，可以获取到所需的数据。以下是一个示例代码片段，用于发送请求并处理响应：
```python
import requests
url = 'https://api.kingdee.com/executeBillQuery'
headers = {'Content-Type': 'application/json'}
payload = {
'FormId': 'AR_RECEIVEBILL',
'FieldKeys': 'FID,FBillNo,FDOCUMENTSTATUS,...',
'FilterString': 'FDATE >=\'2023-01-01\' and (FCONTACTUNIT.FNumber = \'JD008\' or FCONTACTUNIT.FNumber = \'DY017\')',
'Limit': '2000',
'StartRow': '0'
}
response = requests.post(url, headers=headers, json=payload)
data = response.json()
# 数据处理逻辑
for record in data:
process_record(record)
```
#### 分页处理
由于每次请求返回的数据量有限，需要进行分页处理。可以通过调整`StartRow`参数来实现分页：
```python
start_row = 0
page_size = 500
while True:
payload['StartRow'] = str(start_row)
response = requests.post(url, headers=headers, json=payload)
data = response.json()
if not data:
break
for record in data:
process_record(record)
start_row += page_size
```
#### 数据清洗与转换
在获取到原始数据后，通常需要进行清洗和转换，以便后续的数据写入操作。例如，可以根据业务需求对字段进行格式化或过滤无效数据。
```python
def process_record(record):
# 清洗和转换逻辑
cleaned_record = {
'单据编号': record['FBillNo'],
'创建日期': format_date(record['FCreateDate']),
...
}
# 将清洗后的数据存储或进一步处理
```
通过以上步骤，我们可以高效地调用金蝶云星空的API接口，获取并加工所需的数据，为后续的数据集成奠定基础。
### 使用轻易云数据集成平台进行ETL转换并写入金蝶云星空API接口
在数据集成生命周期的第二阶段，我们将已经集成的源平台数据进行ETL转换，转为目标平台金蝶云星空API接口所能够接收的格式，最终写入目标平台。本文将详细介绍如何通过轻易云数据集成平台配置元数据，实现这一过程。
#### API接口配置
在元数据配置中，我们使用了`batchSave` API接口，并通过POST方法进行数据传输。以下是关键字段及其配置：
- **FBillNo**（单据编号）：直接映射源数据中的`FBillNo`。
- **FSETTLEORGID**（结算组织）：使用`ConvertObjectParser`解析器，将源数据中的值转换为金蝶云星空系统可识别的编号。
- **FEXCHANGETYPE**（汇率类型）：固定值`HLTX01_SYS`，同样使用`ConvertObjectParser`解析器。
- **FCURRENCYID**（币别）：固定值`PRE001`，使用解析器进行转换。
- **FDATE**（业务日期）：直接映射源数据中的`FDATE`。
- **FBillTypeID**（单据类型）：固定值`SKDLX01_SYS`，使用解析器转换。
#### 数据请求与清洗
在请求阶段，我们需要确保所有字段都已正确映射和转换。以下是部分字段的详细配置：
```json
{
"field": "FBillNo",
"label": "单据编号",
"type": "string",
"describe": "单据编号",
"value": "{FBillNo}"
},
{
"field": "FSETTLEORGID",
"label": "结算组织",
"type": "string",
"describe": "结算组织",
"parser": {
"name": "ConvertObjectParser",
"params": "FNumber"
},
"value": "114",
"mappingDirection": "positive"
}
```
上述配置中，通过设置字段的类型、描述和解析器参数，我们能够确保数据在传输过程中保持一致性和正确性。
#### 数据转换与写入
在完成数据请求与清洗后，我们进入数据转换与写入阶段。此阶段主要涉及将清洗后的数据按照金蝶云星空API接口要求的格式进行转换，并通过POST方法提交。
##### 请求头部配置
请求头部包含了多个必填字段，例如：
```json
{
"header": ["FBillNo", "FSETTLEORGID", ...],
...
}
```
这些字段确保了每个请求都包含必要的信息，以便目标系统能够正确处理。
##### 请求体配置
请求体主要包含收款单明细信息，如下所示：
```json
{
"bodyName": "details",
...
}
```
其中，明细信息包括结算方式、应收金额、银行账号等。这些字段同样需要经过解析和映射，以确保符合目标系统的要求。
##### 具体明细字段配置
例如，对于结算方式字段，我们可以这样配置：
```json
{
"field": "FSETTLETYPEID",
"label": "结算方式",
...
}
```
通过这种方式，我们能够确保每个明细字段都被正确处理和传输。
#### 提交与审核
最后，在提交请求时，我们可以选择是否自动提交并审核，以及是否验证基础资料有效性。例如：
```json
{
"field": "IsAutoSubmitAndAudit",
...
},
{
"field": "IsVerifyBaseDataField",
...
}
```
这些选项允许我们根据具体业务需求灵活调整操作流程。
### 总结
通过以上步骤，我们成功实现了从源平台到金蝶云星空API接口的数据ETL转换和写入过程。利用轻易云数据集成平台的强大功能和灵活配置，我们能够高效、准确地完成复杂的数据集成任务。
