### 金蝶云星空数据到MySQL的集成方案分享：kd-金蝶查询付款退款单-->mysql（鸿巢）其他退款
在系统对接和数据集成领域，如何有效地将金蝶云星空中复杂的数据及时准确地迁移到MySQL数据库是我们面临的一项挑战。在此案例中，我们通过executeBillQuery接口获取金蝶云星空中的付款退款单数据，并运用高效的数据写入策略，将其导入到MySQL数据库中。本案例旨在详细阐述这一数据集成过程中的关键技术要点。
首先，在金蝶云星空与MySQL之间的连接和通信方面，选择合适的API至关重要。我们使用了executeBillQuery API来主动抓取付款退款单信息，并结合一系列自定义的数据转换逻辑，以确保这些信息能够符合MySQL数据库的存储结构及业务需求。此外，为了保证大规模数据转移功能稳定流畅，我们特别关注以下几个方面：
**1. 高吞吐量的数据写入能力**
借助轻易云平台特有的高吞吐量支持，可以实现大量数据快速写入到MySQL。这不仅提升了系统性能，也缩短了全流程所需时间，有效应对企业日常生产经营过程中产生的大量交易记录。
**2. 集中的监控和告警机制**
为实时跟踪这一任务运行状态，我们依托于平台内置的监控系统，实现全过程透明化管理。当发生异常时，告警机制会第一时间通知相关人员进行处理。这种全方位、多层次保障体系，大幅度降低因网络波动或接口变动而导致的数据丢失风险，从而确保每笔交易都得到完整、准确记录。
**3. 数据质量监控与异常检测**
在执行过程中，由于涉及多接口调用操作，很容易出现超时、限流等问题。对此，通过设置合理分页策略和重试机制，不仅能有效缓解接口负载，还能保证每次请求都被成功响应。同时，对返回结果进行质量校验与异常检测，进一步提高整体集成工作的可靠性。
接下来，让我们具体探讨如何利用上述功能点，实现从金蝶云星空向MySQL无缝迁移“kd-金蝶查询付款退款单-->mysql（鸿巢）其他退款”这一路径上的技术细节，包括分页处理、错误重试、自定义映射等内容。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在轻易云数据集成平台中，调用源系统的API接口是数据集成生命周期的第一步。本文将深入探讨如何通过调用金蝶云星空的`executeBillQuery`接口获取付款退款单的数据，并对其进行初步加工。
#### 接口配置与请求参数
首先，我们需要配置元数据以便正确调用金蝶云星空的API接口。以下是元数据配置的关键部分：
```json
{
"api": "executeBillQuery",
"effect": "QUERY",
"method": "POST",
"number": "FBillNo",
"id": "FREFUNDBILLENTRY_FEntryID",
"idCheck": true,
"formatResponse": [
{
"old": "FDATE",
"new": "FDate_new",
"format": "date"
}
],
"request": [
{"field":"FBillNo","label":"FBillNo","type":"string","describe":"单据编号","value":"FBillNo"},
{"field":"FDOCUMENTSTATUS","label":"FDOCUMENTSTATUS","type":"string","describe":"单据状态","value":"FDOCUMENTSTATUS"},
{"field":"FDATE","label":"FDATE","type":"string","describe":"业务日期","value":"FDATE"},
{"field":"FREFUNDAMOUNTFOR","label":"FREFUNDAMOUNTFOR","type":"string","describe":"表体-应退金额","value":"FREFUNDBILLENTRY_FEntryID"}
],
"otherRequest": [
{"field":"Limit","label":"Limit","type":"string","describe":"金蝶的查询分页参数","value":"{PAGINATION_PAGE_SIZE}"},
{"field":"StartRow","label":"StartRow","type":"string","describe":"金蝶的查询分页参数","value":"{PAGINATION_START_ROW}"},
{"field":"TopRowCount","label":"TopRowCount","type":"int"},
{"field":"FilterString","label":"FilterString","type":"string",
"describe": "示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>=",
"value": "FApproveDate>='{{LAST_SYNC_TIME|date}}' and FCreaterId= '100796' and FBillTypeID.FNUMBER='FKTKDLX02_SYS' and FBillNo NOT LIKE 'LHHYBXD%'"
},
{"field": "FieldKeys",
"label": "FieldKeys",
"type": "array",
"describe": "金蝶分录主键ID格式：FPOOrderEntry_FEntryId,其它格式 FPurchaseOrgId.FNumber",
"value": "{MAIN_REQUEST}"
},
{"field": "FormId",
"label": "FormId",
"type": "string",
"describe": "'必须填写金蝶的表单ID如:PUR_PurchaseOrder'",
"value": "'AP_REFUNDBILL'"
}
],
autoFillResponse: true
}
```
#### 请求参数解析
1. **基本请求字段**：
- `FBillNo`: 单据编号
- `FDOCUMENTSTATUS`: 单据状态
- `FDATE`: 业务日期
- `FREFUNDAMOUNTFOR`: 表体-应退金额
- `FREFUNDBILLENTRY_FEntryID`: 分录主键ID
2. **其他请求字段**：
- `Limit` 和 `StartRow`: 用于分页查询。
- `FilterString`: 用于过滤条件，例如：`FSupplierId.FNumber = 'VEN00010' and FApproveDate>=`。
- `FieldKeys`: 查询返回字段。
- `FormId`: 表单ID，这里为`AP_REFUNDBILL`。
#### 数据请求与清洗
在发送请求时，我们使用POST方法向金蝶云星空发送上述配置的请求参数。以下是一个示例请求体：
```json
{
"_apiName_": "/k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.ExecuteBillQuery.common.kdsvc",
"_method_": "/k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.ExecuteBillQuery.common.kdsvc",
"_params_":{
"_formid_ ": "'AP_REFUNDBILL'",
"_filterString_ ": "'FApproveDate>='2023-01-01' and FCreaterId= '100796' and FBillTypeID.FNUMBER='FKTKDLX02_SYS' and FBillNo NOT LIKE 'LHHYBXD%'",
"_fieldKeys_ ": ["FBillNo", ...],
"_limit_ ": "{PAGINATION_PAGE_SIZE}",
"_startRow_ ": "{PAGINATION_START_ROW}"
}
}
```
#### 响应处理与格式化
响应返回后，我们需要对数据进行初步清洗和格式化。例如，将日期字段`FDATE`转换为新的格式`FDate_new`：
```json
{
...
{
old: 'FDATE',
new: 'FDate_new',
format: 'date'
}
}
```
通过这种方式，我们可以确保数据在进入下一阶段（如数据转换与写入）之前已经过初步处理，符合目标系统的要求。
#### 小结
通过以上步骤，我们成功调用了金蝶云星空的`executeBillQuery`接口，获取并初步加工了付款退款单的数据。这一过程展示了如何利用轻易云数据集成平台进行高效的数据请求与清洗，为后续的数据转换与写入奠定了坚实基础。
### 数据集成中的ETL转换与写入：从金蝶查询付款退款单到MySQLAPI接口
在数据集成生命周期的第二步，我们需要将已经集成的源平台数据进行ETL（Extract, Transform, Load）转换，并最终写入目标平台。在本案例中，源平台为金蝶系统，目标平台为MySQL数据库。以下是具体的技术实现过程。
#### 元数据配置解析
元数据配置是ETL过程中的关键部分，定义了数据从源平台到目标平台的转换规则和结构。在本案例中，元数据配置如下：
```json
{
"api": "execute",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{
"field": "main_params",
"label": "main_params",
"type": "object",
"describe": "111",
"children": [
{"field": "FEntity_FEntryID", "label": "明细id", "type": "string", "value": "{FREFUNDBILLENTRY_FEntryID}"},
{"field": "order_no_new", "label": "单号", "type": "string", "value": "{FBillNo}"},
{"field": "FDocumentStatus", "label": "状态", "type": "string", "value": "{FDOCUMENTSTATUS}"},
{"field": "qty_count", "label": "数量", "type": "string", "value":"1"},
{"field":"sales_count","label":"金额","type":"string","value":"{FREFUNDAMOUNTFOR}"},
{"field":"datetime_new","label":"时间","type":"date","value":"{FDate_new}"},
{"field":"Document_Type","label":"单据类型","type":"string","value":"其他退款"}
]
}
],
“otherRequest”: [
{
“field”: “main_sql”,
“label”: “main_sql”,
“type”: “string”,
“describe”: “111”,
“value”: “INSERT INTO `hc_kd_qttk`(`FEntity_FEntryID`,`order_no_new`,`FDocumentStatus`,`qty_count`,`sales_count`,`datetime_new`,`Document_Type`) VALUES (:FEntity_FEntryID,:order_no_new,:FDocumentStatus,:qty_count,:sales_count,:datetime_new,:Document_Type)”
}
]
}
```
#### 数据请求与清洗
在ETL过程中，首先要从金蝶系统中请求付款退款单的数据。这一步通常通过API调用实现，确保获取的数据准确无误。
#### 数据转换
接下来是数据转换阶段，根据元数据配置，将源平台的数据字段映射到目标平台所需的格式。具体字段映射如下：
- `FEntity_FEntryID` 映射到 `明细id`
- `FBillNo` 映射到 `单号`
- `FDOCUMENTSTATUS` 映射到 `状态`
- 固定值 `1` 映射到 `数量`
- `FREFUNDAMOUNTFOR` 映射到 `金额`
- `FDate_new` 映射到 `时间`
- 固定值 `其他退款` 映射到 `单据类型`
这些字段通过元数据配置中的 `"children"` 节点定义，每个字段都有明确的来源和目标定义。
#### 数据写入
最后一步是将转换后的数据写入目标平台，即MySQL数据库。根据元数据配置中的 `"otherRequest"` 节点，我们可以看到具体的SQL插入语句：
```sql
INSERT INTO `hc_kd_qttk`(`FEntity_FEntryID`, `order_no_new`, `FDocumentStatus`, `qty_count`, `sales_count`, `datetime_new`, `Document_Type`)
VALUES (:FEntity_FEntryID, :order_no_new, :FDocumentStatus, :qty_count, :sales_count, :datetime_new, :Document_Type)
```
这条SQL语句将把映射后的字段值插入到名为 `hc_kd_qttk` 的表中。每个占位符（如`:FEntity_FEntryID`）将在实际执行时被对应的字段值替换。
#### API接口调用
为了完成上述操作，需要通过API接口进行POST请求。以下是一个示例请求：
```http
POST /execute HTTP/1.1
Host: target-platform-api.com
Content-Type: application/json
{
“main_params”: {
“FEntity_FEntryID”: “12345”,
“order_no_new”: “ORD001”,
“FDocumentStatus”: “Approved”,
“qty_count”: “1”,
“sales_count”: “1000.00”,
“datetime_new”: “2023-10-01T12:00:00Z”,
“Document_Type”:“其他退款”
},
”main_sql”:“INSERT INTO hc_kd_qttk(FEntity_FEntryID, order_no_new, FDocumentStatus, qty_count, sales_count, datetime_new, Document_Type) VALUES (:FEntity_FEntryID,:order_no_new,:FDocumentStatus,:qty_count,:sales_count,:datetime_new,:Document_Type)”
}
```
通过上述步骤，我们实现了从金蝶系统查询付款退款单并将其转换为MySQL数据库可接受格式的数据写入过程。这一过程充分利用了轻易云数据集成平台的强大功能，实现了高效、透明的数据处理和管理。
