### 案例分享：金蝶云星空数据集成到管易云的技术实现
在本案例中，我们将详细探讨如何通过轻易云数据集成平台，将金蝶云星空的数据无缝对接至管易云系统。该项目运行的具体方案名称为“其他入库对接-已测试”。通过这一实例，我们不仅能够展示高效、稳定的系统对接流程，还能解决实际操作中的许多技术难题。
首先，针对数据获取环节，使用金蝶云星空的API接口`executeBillQuery`进行定时可靠的数据抓取。这一步骤需要特别注意分页和限流，否则可能导致请求失败或部分数据丢失。通过设定合理的调用频率和处理逻辑，我们可以确保每次请求都精准有效。
其次，在大量数据写入方面，通过调用管易云提供的API接口 `gy.erp.stock.other.in.add` 实现批量数据导入。为了保证写入速度和成功率，设计了分段提交及错误重试机制，以避免网络波动或异常情况造成的数据遗漏。
在两大系统之间进行数据转换时，不同格式之间的不兼容性是一个常见问题。例如，金蝶云星空返回的数据结构与管易云所需格式不一致。因此，定制化的数据映射成为必要。在此过程中，可以利用轻易云平台提供的一些过滤器与转换工具，无缝完成多种复杂场景下的数据适配。
最后，对整个集成过程实时监控及日志记录也是不可忽视的重要一环。通过轻易云的平台特性，所有事务操作均可追溯，并且具备自动告警功能，有助于及时发现并解决潜在问题，提高系统整体可靠性。
以上就是本次‘其他入库对接-已测试’方案实施过程中涉及到的一些关键技术点，为后续全面揭示具体实现细节打下基础。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的第一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口，获取并加工所需的数据。
#### 接口配置与请求参数
根据提供的元数据配置，我们需要通过POST方法调用`executeBillQuery`接口。以下是具体的请求参数配置：
- **FormId**: 业务对象表单Id，必须填写金蝶的表单ID，例如：`STK_MISCELLANEOUS`。
- **FieldKeys**: 需查询的字段key集合，格式为数组，例如：`["FEntity_FEntryID", "FID", "FBillNo", ...]`。
- **FilterString**: 过滤条件，用于筛选符合条件的数据，例如：`FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FBillTypeID.FNUMBER = 'QTRKD02_SYS'`。
- **Limit**: 最大行数，用于分页查询。
- **StartRow**: 开始行索引，用于分页查询。
#### 请求示例
以下是一个完整的请求示例：
```json
{
"FormId": "STK_MISCELLANEOUS",
"FieldKeys": [
"FEntity_FEntryID",
"FID",
"FBillNo",
"FDocumentStatus",
"FStockOrgId.FNumber",
"FDate",
"FBillTypeID",
"FSUPPLIERID.FNumber",
"FNOTE",
"FMATERIALID.FNumber",
"FSTOCKID.FNumber",
"FQty",
"FPrice",
"FAmount"
],
"FilterString": "FApproveDate>='2023-01-01' and FBillTypeID.FNUMBER = 'QTRKD02_SYS'",
"Limit": 100,
"StartRow": 0
}
```
#### 数据清洗与转换
在获取到原始数据后，需要对其进行清洗和转换，以便后续的数据处理和写入。以下是一些常见的数据清洗和转换操作：
1. **字段重命名**：将原始字段名转换为目标系统所需的字段名。例如，将`FBillNo`重命名为`OrderNumber`。
2. **数据类型转换**：确保每个字段的数据类型符合目标系统的要求。例如，将日期字符串转换为标准日期格式。
3. **缺失值处理**：对于缺失值，可以选择填充默认值或删除该记录。
以下是一个简单的数据清洗示例：
```python
def clean_data(raw_data):
cleaned_data = []
for record in raw_data:
cleaned_record = {
'OrderNumber': record['FBillNo'],
'Status': record['FDocumentStatus'],
'StockOrg': record['FStockOrgId.FNumber'],
'Date': convert_to_date(record['FDate']),
'Supplier': record['FSUPPLIERID.FNumber'],
'MaterialCode': record['FMATERIALID.FNumber'],
'Quantity': float(record['FQty']),
'Price': float(record['FPrice']),
'TotalCost': float(record['FAmount'])
}
cleaned_data.append(cleaned_record)
return cleaned_data
def convert_to_date(date_str):
# 实现日期字符串到标准日期格式的转换
return datetime.strptime(date_str, '%Y-%m-%d')
```
#### 自动填充响应
根据元数据配置中的`autoFillResponse: true`，我们可以自动填充响应数据。这意味着在调用接口后，平台会自动将返回的数据映射到预定义的字段中，无需手动处理。
#### 实时监控与日志记录
为了确保数据集成过程的透明度和可追溯性，我们需要对每次接口调用进行实时监控，并记录详细日志。这些日志应包括请求参数、响应结果、处理时间等信息，以便在出现问题时能够快速定位和解决。
```python
import logging
def log_request(request_params, response):
logging.info(f"Request Params: {request_params}")
logging.info(f"Response: {response}")
# 示例调用
request_params = {
# 请求参数...
}
response = call_execute_bill_query(request_params)
log_request(request_params, response)
```
通过以上步骤，我们可以高效地调用金蝶云星空接口获取并加工所需的数据，为后续的数据处理和写入奠定坚实基础。
### 使用轻易云数据集成平台进行ETL转换并写入管易云API接口
在数据集成的生命周期中，将源平台的数据进行ETL（Extract, Transform, Load）转换，并最终写入目标平台是一个关键步骤。本文将详细探讨如何使用轻易云数据集成平台将源数据转换为管易云API接口所能接收的格式，并写入目标平台。
#### 元数据配置解析
元数据配置是实现数据转换和写入的核心。以下是我们针对管易云API接口`gy.erp.stock.other.in.add`的元数据配置：
```json
{
"api": "gy.erp.stock.other.in.add",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"operation": {
"method": "merge",
"field": "FBillNo,F_Shipping_address",
"bodyName": "items",
"bodySum": ["FQty"],
"header": ["FBillNo", "FSTOCKID", "F_recipient", "F_Receiving_phone_number", "F_Shipping_address",
"F_economize", "F_market", "F_distinguish"],
"body": ["FMATERIALID_FNumber", "FQty", "FDate"]
},
"request": [
{"field": "warehouse_code", "label": "仓库代码",
"type": "string",
"describe": "仓库代码",
"value": "{FSTOCKID}"},
{"field": "note",
...
```
#### 数据请求与清洗
在进入ETL过程之前，首先需要从源平台请求数据并进行初步清洗。这一步骤确保了原始数据的准确性和完整性，为后续的转换打下基础。
#### 数据转换
1. **字段映射**：根据元数据配置，将源平台的数据字段映射到管易云API接口所需的字段。例如，`{FSTOCKID}`映射到`warehouse_code`，`{FBillNo}`映射到`wms_bizcode`等。
2. **合并操作**：通过配置中的`operation.method: merge`，我们可以将多个字段合并为一个。例如，`FBillNo,F_Shipping_address`两个字段合并为一个，用于唯一标识记录。
3. **数组处理**：对于商品列表这种嵌套结构，通过定义`children`字段，我们可以将每个商品的信息逐一映射到目标平台。例如，商品代码映射到`item_code`, 数量映射到`qty`, 入库日期映射到`stockDate`.
```json
{
...
{"field":"details","label":"商品列表","type":"array","describe":"商品列表","value":"items","children":[
{"field":"item_code","label":"商品代码","type":"string","describe":"商品代码与商品条码二者必选其一，当两者都提供时，以商品条码为准","value":"{{items.FMATERIALID_FNumber}}"},
{"field":"sku_code","label":"规格代码","type":"string","describe":"有规格的商品此字段必填","value":"{{items.FMATERIALID_FNumber}}"},
{"field":"barcode","label":"商品条码","type":"string","describe":"商品代码与商品条码二者必选其一，当两者都提供时，以商品条码为准"},
{"field":"qty","label":"数量","type":"string","describe":"若当前商品为唯一码商品，忽略这个参数的传入值，程序固定取1。开启小数库存参数的情况下，支持以小数形式录入数量","value":"{{items.FQty}}"},
{"field":"stockDate","label":"入库日期","type":"string","describe":"批次商品专用属性，参数选填。不填写时，程序默认当天","value":"{{items.FDate}}"}
]}
}
```
#### 数据写入
完成数据转换后，通过HTTP POST方法将处理后的数据写入管易云API接口。以下是一个示例请求：
```json
{
...
{
"warehouse_code": "{FSTOCKID}",
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
