### 案例分享：金蝶云星空数据集成——收款单-新20231120-临时使用
在本次技术案例中，我们聚焦于如何高效实现“收款单-新20231120-临时使用”方案的系统对接和数据集成。该方案基于轻易云数据集成平台，目标是将业务系统中的收款单数据准确、及时地写入到金蝶云星空。
为满足快速大规模的数据处理需求，我们充分利用了平台支持的大量数据快速写入能力及统一API资产管理功能，通过executeBillQuery接口来获取需要集成的数据，并通过batchSave接口进行批量写入操作，从而确保了每个环节都能顺畅工作，高度契合企业实际应用场景。
**关键技术要点**
1. **高吞吐量的数据写入**
通过优化网络连接和并行处理机制，实现大量收款单数据快速、高效地导入至金蝶云星空。这一特性能显著提升整个业务流程的响应速度，确保关键财务信息能够实时更新。
2. **集中监控与告警系统**
在整个集成过程中，引入完善的监控和告警机制，不仅可以实时跟踪任务状态，还可在出现异常时即时报警，有助于维护人员迅速定位问题并采取措施，保障系统稳定运行。
3. **自定义转换逻辑适配**
集成过程涉及多种复杂业务规则，为此我们设计了一系列自定义转换逻辑，使得不同结构的数据能够灵活适配。同时，这些逻辑经过严密测试，以确保其对各类边缘情况均有良好兼容性。
4. **分页与限流策略**
针对executeBillQuery和batchSave接口调用频率较高的问题，我们应用分页查询及限流策略。这样不仅减轻了服务器压力，也有效避免了因过载引起的服务宕机或请求失败，提高整体可靠性。
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":"FEXCHANGETYPE","label":"汇率类型","type":"string","value":"FEXCHANGETYPE"}
],
"otherRequest": [
{"field": "Limit", "label": "最大行数", "type": "string", "describe": "金蝶的查询分页参数", "value": "2000"},
{"field": "StartRow", "label": "开始行索引", "type": "string", "describe": "金蝶的查询分页参数",
"value": "{PAGINATION_START_ROW}"},
{"field": "TopRowCount", "label": "返回总行数",
"type": int,
"describe": 金蝶的查询分页参数},
{"field": FilterString,
"label" :过滤条件,
"type" : string,
"describe" : 示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>=,"value" : FBillNo='SKD03149266'or\nFBillNo='SKD03149267'or\nFBillNo='SKD03149268'or\nFBillNo='SKD03149269'or\nFBillNo='SKD03149270'or\nFBillNo='SKD03149271'or\nFBillNo='SKD03149272'or\nFBillNo='SKD03190935'or\nFBillNo='SKD03190936'or\nFBillNo='SKD03190937'or\nFBillNo='SKD03190938'or\nFBillNo='SKD03190939'or\nFBillNo='SKD03190940'or\nFBillNo='SKD03190941'or\nFBillNo='SKD03190942'or\nFBillNo='SKD03190943'or\nFBillNo='SKD03190944'or\nFBillNo='SKD03190945'or\nFBillNo='SKD03190946'or\nFBillNo='SKD03190947'or\nFBillNo='SKD03190948'or\nFBillNo='SKD03190949'or\nFBillNo='SKD03190950'or\nFBillNo='SKD03190951'or\nFBillNo='SKD03190952'or\nFBillNo='SKD03190953'or\n'...
]
}
```
#### 调用API获取数据
在配置好元数据后，我们可以通过轻易云平台调用金蝶云星空的`executeBillQuery`接口。以下是一个示例请求：
```json
{
"_metadata_":{
"_api_":{
"_name_":"",
"_version_":"",
"_method_":"",
"_url_":"",
"_headers_":[]
},
"_pagination_":{
"_pageSize_":"",
"_currentPage_":"",
"_totalPages_":"",
"_totalRecords_":"",
"_hasNextPage_":"",
"_hasPreviousPage_" :""
}
},
}
```
#### 数据清洗与转换
获取到原始数据后，需要对其进行清洗和转换。以下是一些常见的数据清洗与转换操作：
1. **字段映射**：将源系统字段映射到目标系统字段。例如，将`FID`映射到目标系统中的`EntityID`。
2. **数据格式转换**：将日期格式从`YYYY-MM-DD`转换为目标系统所需的格式。
3. **数据过滤**：根据业务需求过滤掉不需要的数据。例如，只保留状态为“已审核”的单据。
#### 示例代码
以下是一个示例代码片段，展示如何使用Python进行上述操作：
```python
import requests
import json
# 配置请求头和URL
headers = {'Content-Type': 'application/json'}
url = 'https://api.kingdee.com/executeBillQuery'
# 构建请求体
payload = {
'FormId': 'AR_RECEIVEBILL',
'FieldKeys': ','.join([f['value'] for f in metadata['request']]),
'FilterString': metadata['otherRequest'][3]['value'],
'Limit': metadata['otherRequest'][0]['value'],
'StartRow': metadata['otherRequest'][1]['value']
}
# 发起POST请求
response = requests.post(url, headers=headers, data=json.dumps(payload))
# 检查响应状态码
if response.status_code == 200:
data = response.json()
# 数据清洗与转换
cleaned_data = []
for record in data:
cleaned_record = {
'EntityID': record[0],
'BillNumber': record[1],
'DocumentStatus': record[2],
'CreatorID': record[3],
'ApproverID': record[4],
# 更多字段映射...
}
cleaned_data.append(cleaned_record)
else:
print(f'Error: {response.status_code}')
```
以上代码展示了如何通过HTTP POST请求调用金蝶云星空API，并对返回的数据进行初步清洗和转换。
#### 总结
通过轻易云数据集成平台，我们可以高效地调用金蝶云星空的API，获取所需的业务数据，并进行必要的数据清洗和转换。这一步骤为后续的数据处理和分析奠定了坚实基础。在实际应用中，根据具体业务需求，可能还需要进一步优化和调整元数据配置及清洗逻辑。
### 数据转换与写入金蝶云星空API接口的技术案例
在数据集成生命周期的第二阶段，我们需要将已经集成的源平台数据进行ETL转换，转为目标平台金蝶云星空API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨如何利用轻易云数据集成平台实现这一过程。
#### 元数据配置解析
元数据配置是实现数据转换与写入的核心。以下是关键字段和操作的详细解析：
- **API接口信息**：
```json
{"api":"batchSave","method":"POST","idCheck":true}
```
我们使用的是`batchSave` API，采用POST方法进行数据提交，并启用了ID检查功能。
- **操作配置**：
```json
"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"]}
```
操作方法为`merge`，合并字段包括`FBillTypeID`, `FBillNo`, `FDATE`, `FPAYORGI`。请求体名称为`details`，头部字段和体部字段分别定义了具体的数据映射关系。
- **请求字段**：
```json
"request":[{"field":"FBillNo",...},{"field":"FSETTLEORGID",...},...]
```
请求字段定义了每个字段在请求中的具体配置，包括字段名、标签、类型、描述、值以及解析器等。例如：
```json
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","value":"{FBillNo}"}
```
单据编号字段直接从源数据中获取对应值。
#### 数据转换细节
1. **单据编号（FBillNo）**：
- 类型：字符串
- 描述：单据编号
- 值：直接从源数据中获取 `{FBillNo}`
2. **结算组织（FSETTLEORGID）**：
- 类型：字符串
- 描述：结算组织
- 值：固定值 `114`
- 映射方向：正向映射
- 映射配置：`6355fe20c4a6d536d27cd8dc`
- 转换器：使用 `ConvertObjectParser` 将值转换为金蝶云星空所需格式
3. **币别（FCURRENCYID）**：
- 类型：字符串
- 描述：币别
- 值：固定值 `PRE001`
- 转换器：使用 `ConvertObjectParser`
4. **业务日期（FDATE）**：
- 类型：字符串
- 描述：业务日期
- 值：直接从源数据中获取 `{FDATE}`
5. **单据类型（FBillTypeID）**：
- 类型：字符串
- 描述：单据类型
- 值：固定值 `SKDLX01_SYS`
- 转换器：使用 `ConvertObjectParser`
6. **往来单位类型（FCONTACTUNITTYPE）**和**往来单位（FCONTACTUNIT）**：
- 往来单位类型直接从源数据中获取 `{FCONTACTUNITTYPE}`
- 往来单位使用固定值 `PDD15` 并通过 `ConvertObjectParser` 转换
7. **付款单位类型（FPAYUNITTYPE）**和**付款单位（FPAYUNIT）**：
- 类似于往来单位，分别从源数据中获取 `{FPAYUNITTYPE}` 和 `{FPAYUNIT}`，并通过相应的转换器处理
8. **收款单明细（FRECEIVEBILLENTRY）**：
明细部分包含多个子字段，如结算方式、应收金额、我方银行账号等，每个子字段都有对应的配置。例如：
```json
{"field":"FACCOUNTID", "label":"我方银行账号", "type":"string", "describe":"我方银行账号", "parser":{"name":"ConvertObjectParser", "params":"FNumber"}, "value":"{FACCOUNTID}", "parent":"FRECEIVEBILLENTRY"}
```
我方银行账号通过 `ConvertObjectParser` 转换，并从源数据中获取 `{FACCOUNTID}`。
#### 请求其他参数
- 表单Id (`FormId`) 必须填写金蝶的表单 ID，例如 `AR_RECEIVEBILL`
- 执行操作 (`Operation`) 固定为 `BatchSave`
- 提交并审核 (`IsAutoSubmitAndAudit`) 默认设置为 false，不自动提交审核
- 验证基础资料 (`IsVerifyBaseDataField`) 默认设置为 false，不验证基础资料有效性
#### 实际应用案例
假设我们有一条源平台的数据如下：
```json
{
"FBillNo": "20231120",
"FDATE": "2023-11-20",
"FCONTACTUNITTYPE": "Customer",
"FPAYUNITTYPE": "Company",
"FPAYUNIT": "XYZ Ltd.",
...
}
```
通过上述元数据配置和ETL过程，我们可以将其成功转换并写入到金蝶云星空系统中。请求体示例如下：
```json
{
"FormId": "AR_RECEIVEBILL",
"Operation": "BatchSave",
"Model": {
...
// 根据元数据配置生成的具体请求内容
...
},
...
}
```
以上就是利用轻易云数据集成平台实现ETL转换并写入金蝶云星空API接口的技术案例，通过详细解析每个步骤和字段配置，实现了高效的数据集成与处理。
