### 旺店通·跨境版数据集成到金蝶云星空的技术实践
在本案例中，我们详细探讨了如何通过轻易云数据集成平台，将旺店通·跨境版的数据高效地对接到金蝶云星空系统。该项目方案被命名为"二期-旺店通跨境销售出库单&星空销售出库单---(订单接口)11"，其核心目标是实现两套系统间的数据无缝对接，确保每个销售出库单都能准确、及时地反映在企业的综合管理平台中。
首先，让我们简要阐述一下核心API接口及其功能。我们从旺店通·跨境版获取数据的API为`/api/openservices/trade/v1/getSalesTradeList`，需要定时可靠地抓取这些交易信息，并处理分页和限流问题，以防止数据丢失或请求失败。而写入金蝶云星空的数据则使用的是批量保存接口`batchSave`，这要求我们在执行过程中考虑如何快速而大批量地进行操作，以提升整体效率。
为了确保不漏单，每次执行任务时会调用旺店通·跨境版的API，通过设定合理有效的时间区间和分页参数来抓取所有新的订单信息。这些抓取到的数据经过必要转换后，再通过金蝶云星空提供的批量保存接口写入目标数据库。在这个过程中，我们还实现了全面且细致的监控与日志记录功能，一旦出现异常情况，可以及时捕捉并重试相应任务，从而保证系统稳定运行。
对于两个不同系统之间可能存在的数据格式差异，我们设计了定制化的数据映射规则，使得源端（旺店通）的字段能够精确匹配至目的端（金蝶云星空），同时避免因格式不一致导致的信息错漏。此外，为了进一步保障数据传输过程中的可靠性，还设置了一系列错误处理机制，包括自动回滚、告警通知以及多次重试策略等。
本文下面将逐步详细解析各个模块具体实施步骤及背后采用的重要技术手段。
### 调用旺店通·跨境版接口获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用旺店通·跨境版的`/api/openservices/trade/v1/getSalesTradeList`接口，并对数据进行初步加工。
#### 接口配置与请求参数
首先，我们需要配置元数据以便正确调用API。以下是元数据配置的关键部分：
```json
{
"api": "/api/openservices/trade/v1/getSalesTradeList",
"effect": "QUERY",
"method": "POST",
"number": "tradeNo",
"id": "tradeId",
"name": "{stockoutNo}",
"idCheck": true,
"request": [
{"field":"modifyTimeBegin","label":"创建开始时间","type":"datetime","value":"{{LAST_SYNC_TIME|datetime}}"},
{"field":"modifyTimeEnd","label":"创建结束时间","type":"datetime","value":"{{CURRENT_TIME|datetime}}"},
{"field":"tradeStatusCode","label":"订单状态编码","type":"string","value":"4"}
],
"otherRequest": [
{"field":"pageNo","label":"当前页码","type":"string","describe":"当前页码","value":"_function {PAGINATION_START_PAGE}+1"},
{"field":"pageSize","label":"分页大小","type":"string","describe":"分页大小","value":"{PAGINATION_PAGE_SIZE}"},
{"field":"responseKey","label":"响应详情参","type":"string","value":"tradeId"},
{"field":"invokeKey","label":"请求详情参","type":"string","value":"tradeIds"},
{"field":"detailApi","label":"详情接口","type":"string","value":"/api/openservices/trade/v1/getSalesTradeOrderList"}
],
"autoFillResponse": true,
"condition": [
[{"field": "shopText", "logic": "notin", "value": "JW-分销-Jingdong E-COMMERCE(TRADE) HONGKONG CORPORATION LIMITED（京东马来西亚）,JW-分销-日本C＆C Co.,Ltd（IROOM）,JW-分销-韩国OUYA TRADING COMPANY LIMITED,JW-分销-欧美HONG KONG GEEKBUYING INFORMATION TECHNOLOGY（际客）,JW-分销-Jingdong E-COMMERCE(TRADE) HONGKONG CORPORATION LIMITED（京东荷兰）"}]
]
}
```
#### 请求参数详解
1. **基本请求参数**：
- `modifyTimeBegin` 和 `modifyTimeEnd`：用于指定查询时间范围，分别代表创建开始时间和结束时间。这两个参数使用动态变量`{{LAST_SYNC_TIME|datetime}}`和`{{CURRENT_TIME|datetime}}`来自动填充。
- `tradeStatusCode`：订单状态编码，固定值为`4`，表示特定状态的订单。
2. **分页参数**：
- `pageNo`：当前页码，通过函数 `_function {PAGINATION_START_PAGE}+1` 动态计算。
- `pageSize`：分页大小，使用变量 `{PAGINATION_PAGE_SIZE}` 来设置。
3. **其他参数**：
- `responseKey` 和 `invokeKey`：分别用于响应详情和请求详情的标识符。
- `detailApi`：详情接口，用于获取更详细的订单信息。
#### 数据过滤条件
为了确保获取的数据符合业务需求，我们设置了过滤条件：
```json
"condition": [
[{"field": "shopText", "logic": "notin", "value": "..."}]
]
```
此条件排除了特定店铺的订单数据，确保我们只处理需要的数据。
#### 数据请求与清洗
在实际操作中，首先通过上述配置调用API获取原始订单数据。由于平台支持全异步操作，可以高效地处理大批量数据。获取的数据会自动填充到响应结构中，这一步骤称为“自动填充响应”。
接下来，我们需要对原始数据进行清洗和初步加工。例如，可以根据业务需求筛选出特定字段或转换字段格式，以便后续的数据转换与写入阶段更为顺畅。
#### 示例代码
以下是一个简化的示例代码片段，用于展示如何通过轻易云平台发起API请求并处理响应：
```python
import requests
import json
from datetime import datetime, timedelta
# 设置请求头
headers = {
'Content-Type': 'application/json',
}
# 设置请求体
payload = {
'modifyTimeBegin': (datetime.now() - timedelta(days=1)).strftime('%Y-%m-%d %H:%M:%S'),
'modifyTimeEnd': datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
'tradeStatusCode': '4',
'pageNo': '1',
'pageSize': '100'
}
# 发起POST请求
response = requests.post('https://api.wangdian.cn/api/openservices/trade/v1/getSalesTradeList', headers=headers, data=json.dumps(payload))
# 检查响应状态并处理数据
if response.status_code == 200:
data = response.json()
# 数据清洗与初步加工逻辑
else:
print(f"Error: {response.status_code}")
```
通过上述步骤，我们成功实现了从旺店通·跨境版获取销售出库单数据，并进行了初步加工，为后续的数据转换与写入打下了坚实基础。
### 利用轻易云数据集成平台实现金蝶云星空API接口的数据转换与写入
在数据集成过程中，ETL（Extract, Transform, Load）是一个关键步骤。本文将深入探讨如何利用轻易云数据集成平台，将已经集成的源平台数据进行ETL转换，转为金蝶云星空API接口所能够接收的格式，并最终写入目标平台。
#### 1. 数据转换与映射
在进行数据转换时，我们需要根据金蝶云星空API接口的要求，对源数据进行相应的字段映射和格式转换。以下是元数据配置中的关键字段及其映射关系：
- **单据类型（FBillTypeID）**：此字段表示销售出库单的类型。在元数据配置中，使用了固定值`XSCKD07_SYS`，表示B2C销售出库单。
- **单据编号（FBillNo）**：此字段对应于源平台的订单编号，通过占位符`{tradeNo}`来获取。
- **日期（FDate）**：对应于订单的交货时间，通过占位符`{deliveryTime}`来获取。
- **发货组织（FStockOrgId）和销售组织（FSaleOrgId）**：这两个字段都使用了占位符`{shopText}`，并通过`ConvertObjectParser`解析为金蝶云星空所需的格式。
- **客户（FCustomerID）**：此字段通过占位符`{shopNo}`获取客户信息，并使用`ConvertObjectParser`进行解析。
- **备注（FNote）**：多行文本备注信息。
#### 2. 明细信息处理
明细信息是订单的重要组成部分，需要特别注意其结构和字段映射：
```json
{
"field": "FEntity",
"label": "明细信息",
"type": "array",
"describe": "明细信息",
"value": "details_list",
"children": [
{
"field": "FMaterialID",
"label": "物料编码",
"type": "string",
"describe": "基础资料",
"parser": {
"name": "ConvertObjectParser",
"params": "FNumber"
},
"value": "{{details_list.skuNo}}"
},
{
"field": "FRealQty",
"label": "实发数量",
"type": "string",
"describe": "数量",
"value": "{{details_list.num}}"
},
{
...
}
]
}
```
在这个配置中，每个明细项都包含多个子字段，例如物料编码、实发数量、含税单价等。这些子字段通过占位符从源数据中提取，并使用相应的解析器进行格式转换。
#### 3. API 请求配置
为了将转换后的数据写入金蝶云星空，我们需要构建一个符合其API要求的请求体。以下是完整的请求配置示例：
```json
{
...
{
"field":"FormId",
...
"value":"SAL_OUTSTOCK"
},
{
...
...
...
},
{
...
...
...
}
}
```
在这个请求配置中，我们指定了业务对象表单ID为`SAL_OUTSTOCK`，表示销售出库单。同时，我们设置了操作类型为`Save`，并启用了自动提交和审核功能。
#### 4. 提交与监控
一旦请求体构建完成，我们可以通过轻易云数据集成平台的全异步机制，将请求发送到金蝶云星空API接口。通过平台提供的实时监控功能，可以跟踪每个请求的状态，确保数据成功写入目标系统。
#### 总结
通过上述步骤，我们实现了从源平台到金蝶云星空的数据ETL转换与写入。在这个过程中，利用轻易云数据集成平台提供的丰富功能，不仅简化了复杂的数据处理任务，还确保了高效、准确的数据传输。
