### 从简道云到金蝶云星空：流量成交表（二合一）到销售退货单的系统对接集成案例
在本篇技术案例中，我们将重点探讨如何通过轻易云数据集成平台，实现从简道云的数据无缝对接到金蝶云星空。在具体方案“流量成交表（二合一）=> 销售退货单”的实际运行过程中，有效解决了数据抓取、批量写入和格式转换等诸多难题。
首先，通过使用简道云提供的标准API接口`/api/v2/app/{app_id}/entry/{entry_id}/data`，我们能够定时可靠地抓取所需的数据。为了确保不漏单及提高处理效率，我们特别设计了分页处理机制以及错误重试策略，以应对可能出现的限流问题。
然后，在将大量数据进行快速写入到金蝶云星空前，需要充分考虑两者之间的数据格式差异。这里，采用了一套定制化的数据映射规则，同时借助于金蝶云星空提供的API `batchSave` 实现批量数据对接。这不仅提升了整体处理速度，还能最大程度地保证数据的一致性和完整性。
此外，为保障整个集成过程中的透明度与可追溯性，对每个环节进行了实时监控，并设置详细日志记录功能，使得任何异常情况都能迅速定位并加以修正，从而提升业务运作的可靠性及客户满意度。
通过上述方案，不仅有效实现了简道云与金蝶云星空间的数据高效传输和无缝整合，也为后续类似项目提供了一套通用且可复制的方法论。
### 使用简道云接口获取并加工数据的技术案例
在轻易云数据集成平台中，调用源系统接口是数据处理生命周期的第一步。本文将详细探讨如何通过调用简道云接口`/api/v2/app/{app_id}/entry/{entry_id}/data`来获取并加工数据。
#### 接口配置与请求参数
首先，我们需要配置接口的元数据。以下是关键的元数据配置：
```json
{
"api": "/api/v2/app/{app_id}/entry/{entry_id}/data",
"effect": "QUERY",
"method": "POST",
"number": "_widget_1683509935530",
"id": "_id",
"idCheck": true,
"request": [
{"field":"appId","label":"应用ID","type":"string","describe":"应用ID","value":"642307c010703500087839ac"},
{"field":"entryId","label":"表单ID","type":"string","describe":"表单ID","value":"6438b3adacef5e0009b2e467"},
{"field":"fields","label":"需要查询的字段","type":"string","describe":"多个字段以逗号隔开，默认不传入则输出所有字段","parser":{"name":"StringToArray","params":","}},
{"field":"limit","label":"每页返回数量","type":"string","describe":"查询的数据条数，1~100，默认10","value":"100"},
{"field":"filter","label":"过滤参数","type":"object","describe":"过滤参数",...}
],
...
}
```
#### 请求示例
根据上述元数据配置，我们可以构建一个请求体来获取所需的数据。以下是一个具体的请求示例：
```json
{
"appId": "642307c010703500087839ac",
"entryId": "6438b3adacef5e0009b2e467",
"fields": ["_widget_1683509935530", "_id"],
"limit": 100,
"filter": {
"rel": "and",
"cond_1": {
"field": "updateTime",
"type": "datetime",
"method": "range",
"value": ["2023-01-01T00:00:00Z", "{{LAST_SYNC_TIME|datetime}}"]
},
...
}
}
```
#### 数据清洗与转换
在获取到原始数据后，需要对其进行清洗和转换，以便后续处理和写入目标系统。以下是一些常见的数据清洗与转换操作：
1. **字段映射**：将源系统中的字段映射到目标系统中的对应字段。例如，将简道云中的`_widget_1683509935530`映射到目标系统中的`transaction_amount`。
```python
def map_fields(data):
return {
'transaction_amount': data['_widget_1683509935530'],
'id': data['_id']
}
```
2. **数据格式转换**：将日期字符串转换为目标系统所需的日期格式。
```python
from datetime import datetime
def convert_date_format(date_str):
return datetime.strptime(date_str, '%Y-%m-%dT%H:%M:%SZ').strftime('%Y-%m-%d %H:%M:%S')
```
3. **过滤无效数据**：去除不符合业务规则的数据。例如，过滤掉交易金额为负数的记录。
```python
def filter_invalid_data(data):
return [record for record in data if record['transaction_amount'] > 0]
```
#### 实践案例
假设我们需要从简道云中获取销售退货单的数据，并将其写入到目标系统中。具体步骤如下：
1. **调用简道云接口**：使用上述请求示例，通过HTTP POST方法调用简道云接口，获取原始数据。
2. **清洗与转换**：对获取到的数据进行字段映射、日期格式转换和无效数据过滤。
3. **写入目标系统**：将清洗和转换后的数据通过轻易云平台写入到目标系统中。
以下是一个完整的Python代码示例：
```python
import requests
from datetime import datetime
# 调用简道云接口获取原始数据
response = requests.post(
url='https://api.jiandaoyun.com/api/v2/app/642307c010703500087839ac/entry/6438b3adacef5e0009b2e467/data',
json={
'fields': ['_widget_1683509935530', '_id'],
'limit': 100,
'filter': {
'rel': 'and',
'cond_1': {
'field': 'updateTime',
'type': 'datetime',
'method': 'range',
'value': ['2023-01-01T00:00:00Z', '{{LAST_SYNC_TIME|datetime}}']
},
...
}
}
)
data = response.json()['data']
# 数据清洗与转换
def map_fields(data):
return {
'transaction_amount': data['_widget_1683509935530'],
'id': data['_id']
}
def convert_date_format(date_str):
return datetime.strptime(date_str, '%Y-%m-%dT%H:%M:%SZ').strftime('%Y-%m-%d %H:%M:%S')
def filter_invalid_data(data):
return [record for record in data if record['transaction_amount'] > 0]
cleaned_data = filter_invalid_data([map_fields(record) for record in data])
# 将清洗后的数据写入目标系统（此处省略具体实现）
write_to_target_system(cleaned_data)
```
通过以上步骤，我们实现了从简道云接口获取并加工销售退货单数据，并准备好将其写入目标系统。这一过程展示了如何利用轻易云平台高效地进行异构系统间的数据集成。
### 使用轻易云数据集成平台将源数据转换并写入金蝶云星空API接口
在数据集成过程中，ETL（Extract, Transform, Load）是至关重要的一步。本文将深入探讨如何使用轻易云数据集成平台，将已经集成的源平台数据进行ETL转换，转为金蝶云星空API接口所能够接收的格式，并最终写入目标平台。
#### 元数据配置解析
元数据配置是实现数据转换和写入的关键。以下是针对金蝶云星空API接口的具体元数据配置：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 1,
"method": "batchArraySave"
},
"request": [
{
"field": "FBillTypeID",
"label": "单据类型",
"type": "string",
"describe": "单据类型",
"parser": {
"name": "ConvertObjectParser",
"params": "FNumber"
},
"value": "XSTHD01_SYS"
},
{
...
}
],
...
}
```
#### 数据请求与清洗
在生命周期的第一阶段，我们已经完成了从源系统的数据请求与清洗。接下来，我们需要将这些清洗后的数据进行转换，以符合金蝶云星空API的要求。
#### 数据转换与写入
1. **定义API和方法**：
配置中指定了API为`batchSave`，方法为`POST`，这意味着我们将使用批量保存的方式提交数据。
2. **操作参数**：
- `rowsKey`：指定数组键名。
- `rows`：每次操作的数据行数。
- `method`：具体操作方法，这里使用`batchArraySave`。
3. **请求字段映射**：
每个字段都需要映射到目标平台对应的字段。例如：
- `FBillTypeID`：单据类型，通过`ConvertObjectParser`解析，参数为`FNumber`。
- `FSaleOrgId`、`FStockOrgId`等字段通过相同方式解析，并从源系统中提取相应值。
4. **明细信息处理**：
明细信息（如物料编码、实退数量等）被定义为一个数组，通过子字段进行详细描述。例如：
```json
{
...
"field": "FEntity",
...
"children": [
{
...
"field": "FMaterialId",
...
},
{
...
"field": "FRealQty",
...
}
]
}
```
5. **其他请求参数**：
包括业务对象表单ID（如：SAL_RETURNSTOCK）、执行操作（如：Save）、是否自动提交并审核等。
#### 实际应用案例
假设我们有一组来自源系统的数据，需要转换并写入金蝶云星空。以下是具体步骤：
1. **提取源数据**：
从源系统中提取相关字段，如销售组织、库存组织、单据编号、退货客户等。
2. **转换字段格式**：
使用配置中的解析器（如ConvertObjectParser）将源系统中的值转换为目标系统可接受的格式。例如，将销售组织编码转换为金蝶云星空所需格式。
3. **构建请求体**：
根据元数据配置构建HTTP请求体，包括头部信息和明细信息。确保所有必填字段都已正确映射和填充。
4. **发送请求**：
使用POST方法将构建好的请求体发送到金蝶云星空API接口，并处理返回结果。如果有错误，需要根据返回的信息进行调试和修正。
```json
{
...
// 示例请求体
{
"FormId":"SAL_RETURNSTOCK",
...
// 主表信息
{
...
// 明细表信息
{
...
// 子项
[
{
...
}
]
}
}
}
}
```
通过上述步骤，我们可以高效地将源系统的数据转换并写入到金蝶云星空，实现不同系统间的数据无缝对接。这不仅提高了业务流程的透明度和效率，还确保了数据的一致性和准确性。
