### 金蝶云星空与旺店通·企业奇门的调拨单数据集成实践案例
在本技术案例中，我们将探讨如何通过轻易云数据集成平台，将金蝶云星空中的调拨单数据无缝对接到旺店通·企业奇门系统中。本方案使用了“调拨单对接到其他入库旺店通”的具体实施策略，包含从金蝶云星空接口获取数据、处理分页和限流问题，到最终批量写入旺店通·企业奇门的一系列关键技术步骤。
首先，通过调用金蝶云星空的`executeBillQuery` API，我们可以定时可靠地抓取所需的调拨单数据信息。为了应对可能出现的数据量大、请求频繁等情况，集成方案针对API接口进行了高效的分页处理和限流控制，以确保系统稳定运行及其吞吐能力不受影响。这种设计不仅提高了请求的数据精确度，同时也避免了因大量并发导致的服务异常。
在实现过程中，自定义的数据转换逻辑被广泛运用，以适应两套系统之间不同的数据结构需求。例如，从金蝶云星空取得的数据需要根据业务规则进行格式化，然后再通过`wdt.stockin.order.push` API 传输至旺店通。为此，我们采用可视化的数据流设计工具，不仅使得该过程更加直观易懂，也便于项目团队成员进行管理和调整。
此外，为确保整个数据集成流程能够实时监控和及时响应可能出现的问题，本方案引入了一套集中监控与告警机制。当任何环节出现异常，例如网络抖动或API返回错误信息时，该机制能迅速捕捉并记录日志，并触发相应的重试策略，有效保证任务失败情况下能快速恢复。
让我们详细分析每个技术细节，从如何调用各个关键API开始，到如何解决常见挑战，实现高效准确的数据同步。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的第一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口，获取调拨单数据并进行初步加工。
#### 接口配置与请求参数
首先，我们需要配置`executeBillQuery`接口的元数据。以下是该接口的元数据配置：
```json
{
"api": "executeBillQuery",
"effect": "QUERY",
"method": "POST",
"number": "FBillNo",
"id": "FBillEntry_FEntryID",
"idCheck": true,
"request": [
{"field":"FBillEntry_FEntryID","label":"FBillEntry_FEntryID","type":"string","describe":"111","value":"FBillEntry_FEntryID"},
{"field":"FID","label":"FID","type":"string","describe":"111","value":"FID"},
{"field":"FBillNo","label":"FBillNo","type":"string","describe":"111","value":"FBillNo"},
{"field":"FDocumentStatus","label":"FDocumentStatus","type":"string","describe":"111","value":"FDocumentStatus"},
{"field":"FStockOrgId_FNumber","label":"FStockOrgId_FNumber","type":"string","describe":"111","value":"FStockOrgId.FNumber"},
{"field":"FDate","label":"FDate","type":"string","describe":"111","value":"FDate"},
{"field":"FBillTypeID_FNumber","label":"FBillTypeID_FNumber","type":"string","describe":"111","value":"FBillTypeID.FNumber"},
{"field":"FTransferBizType","label":"FTransferBizType","type":"string","describe":"111","value":"FTransferBizType"},
{"field": "Limit", "label": "Limit", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_PAGE_SIZE}"},
{"field": "FieldKeys", "label": "FieldKeys", "type": "array", "describe": "金蝶分录主键ID格式：FPOOrderEntry_FEntryId,其它格式 FPurchaseOrgId.FNumber",
"value": "{MAIN_REQUEST}"},
{"field": "TopRowCount", "label": "TopRowCount", "type": "int",
"describe": "金蝶的查询分页参数"},
{"field": "FilterString",
"label":
"FilterString",
"type":
"string",
"describe":
"示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>=",
"value":
"FApproveDate>='{{LAST_SYNC_TIME|datetime}}' and FDestStockId.FNumber='007' and FStockOrgId.FNumber='102'"},
{"field":
"FormId",
"label":
"FormId",
"type":
"string",
"describe":
"必须填写金蝶的表单ID如:PUR_PurchaseOrder",
"value":
"STK_TransferDirect"
},
{"field":
"StartRow",
"label":
"StartRow",
"type":
"string",
"describe":
"金蝶的查询分页参数",
"value":
"{PAGINATION_START_ROW}"
},
{"field":
"FBillNo",
"label":
"单号",
"type":
"string"}
],
...
}
```
#### 请求参数解析
1. **API和方法**：该接口使用`POST`方法，通过调用`executeBillQuery` API来执行查询操作。
2. **主键字段**：`number`字段表示单据编号，`id`字段表示分录主键。
3. **请求字段**：包含了调拨单相关的所有必要字段，如`FBillNo`, `FID`, `FDocumentStatus`, `FStockOrgId_FNumber`, `FDate`, 等等。
4. **分页参数**：为了处理大批量数据，接口支持分页查询，相关参数包括`Limit`, `TopRowCount`, `StartRow`。
5. **过滤条件**：通过`FilterString`字段可以设置复杂的过滤条件，例如按时间范围和库存组织编号进行过滤。
#### 实际调用示例
假设我们需要查询最近同步时间之后，目标库存组织编号为'007'且库存组织编号为'102'的调拨单，我们可以构造如下请求：
```json
{
"FormId": "STK_TransferDirect",
"FieldKeys": ["FID", ...],
...
// 分页参数
{
...
// 分页大小
Limit: 100,
// 起始行
StartRow: 0,
// 查询条件
FilterString:
"'{{LAST_SYNC_TIME|datetime}}' and FDestStockId.FNumber='007' and FStockOrgId.FNumber='102'"
...
}
}
```
#### 数据清洗与转换
在获取到原始数据后，需要对其进行清洗和转换，以便后续处理。常见的数据清洗操作包括：
1. **去除冗余字段**：只保留业务需要的关键字段。
2. **格式转换**：将日期、数值等字段转换为统一格式。
3. **数据校验**：检查关键字段是否为空或格式是否正确。
例如，对于获取到的一条记录，可以执行如下清洗操作：
```python
def clean_data(record):
cleaned_record = {
'BillNo': record['FBillNo'],
'Date': format_date(record['FDate']),
'Qty': float(record['FQty']),
'Amount': float(record['FAmount']),
...
}
return cleaned_record
def format_date(date_str):
# 假设日期格式为 YYYY-MM-DD
return datetime.strptime(date_str, '%Y-%m-%d').strftime('%Y%m%d')
```
#### 数据写入目标系统
清洗后的数据可以通过轻易云平台进一步转换并写入目标系统（如旺店通）。这一步通常涉及映射字段、处理业务逻辑等。
```python
def transform_and_write(data):
transformed_data = {
'order_no': data['BillNo'],
'order_date': data['Date'],
'quantity': data['Qty'],
'total_amount': data['Amount'],
...
}
# 调用目标系统API写入数据
target_system_api.write(transformed_data)
```
通过上述步骤，我们实现了从金蝶云星空获取调拨单数据，并对其进行清洗和初步加工，为后续的数据处理奠定了基础。
### 使用轻易云数据集成平台实现调拨单对接到旺店通·企业奇门API接口
在数据集成生命周期的第二步中，我们需要将已经集成的源平台数据进行ETL转换，转为目标平台——旺店通·企业奇门API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨如何利用轻易云数据集成平台配置元数据，实现这一过程。
#### 元数据配置解析
首先，我们需要理解元数据配置中的各个字段及其含义。以下是我们需要配置的元数据：
```json
{
"api": "wdt.stockin.order.push",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{
"field": "outer_no",
"label": "外部单号",
"type": "string",
"value": "{FBillNo}"
},
{
"field": "warehouse_no",
"label": "仓库编号",
"type": "string",
"value": "{FDestStockId_FNumber}"
},
{
"field": "remark",
"label": "备注",
"type": "string",
"value": "金蝶调拨单"
},
{
"field": "is_check",
"label": "是否审核",
"type": "string",
"value": "1"
},
{
"field": "goods_list",
"label": "货品明细节点{FBillEntry_FEntryID}",
"type": "array",
...
```
#### 配置解析与ETL转换
1. **API接口与请求方法**：
- `api`: 表示调用的API接口，这里是`wdt.stockin.order.push`。
- `method`: 请求方法为`POST`，表示我们将以POST方式提交数据。
2. **字段映射**：
- `outer_no`: 对应外部单号，映射源字段`{FBillNo}`。
- `warehouse_no`: 对应仓库编号，映射源字段`{FDestStockId_FNumber}`。
- `remark`: 固定值“金蝶调拨单”。
- `is_check`: 固定值“1”，表示是否审核。
3. **货品明细节点**：
- `goods_list`: 是一个数组类型，包含多个子字段。
- `spec_no`: 商家编码，对应源字段`{{details_listss.FMaterialId_FNumber}}`。
- `stockin_num`: 入库数量，对应源字段`{{details_listss.FQty}}`。
- `src_price`, `stockin_price`: 固定值“1”。
4. **其他请求参数**：
- `stockin_info`: 固定描述“111”。
#### 数据转换与写入
在实际操作中，我们需要进行以下步骤：
1. **提取与清洗数据**：
首先从源系统提取原始调拨单数据，并进行必要的数据清洗和预处理。这一步可以通过轻易云的数据处理工具实现。
2. **构建请求体**：
根据元数据配置，将清洗后的数据映射到目标API所需的格式。例如：
```json
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
{
...
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
```
3. **发送请求**：
使用HTTP客户端（如Postman或编程语言中的HTTP库）发送POST请求，将构建好的JSON请求体发送到旺店通·企业奇门API接口。
4. **处理响应**：
接收并处理API响应，根据响应结果进行后续操作，如记录日志、更新状态等。
#### 实例代码示例
以下是一个简单的Python示例代码，用于发送POST请求：
```python
import requests
import json
url = 'https://api.wangdian.cn/openapi2/stockin_order_push.php'
headers = {'Content-Type': 'application/json'}
data = {
'outer_no': '20231001',
'warehouse_no': 'WH001',
'remark': '金蝶调拨单',
'is_check': '1',
'goods_list': [
{'spec_no': 'SP001', 'stockin_num': '10', 'src_price': '1', 'stockin_price': '1'},
{'spec_no': 'SP002', 'stockin_num': '20', 'src_price': '1', 'stockin_price': '1'}
],
'stockin_info': '111'
}
response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
```
通过以上步骤和示例代码，我们可以实现将调拨单数据从源系统转换并写入到旺店通·企业奇门API接口中。
