### 2C吉客云-销售单--->YS-销售退货单成功配置实践
在本案例中，我们将详细探讨如何实现将吉客云·奇门的数据集成到用友BIP的过程，具体方案名称为“2C吉客云-销售单--->YS-销售退货单-成功”。通过利用轻易云数据集成平台，结合API接口技术及若干关键特性，实现了高效、稳定的数据对接。
#### 系统对接概述
首先，我们需要从吉客云·奇门系统获取相关的交易数据。这个过程中使用的是`jackyun.tradenotsensitiveinfos.list.get` API接口，这个接口支持高吞吐量的数据读取能力，同时提供分页机制以确保大数据量场景下的处理效率。
```javascript
// 示例API调用请查看官方文档
GET /api/jackyun/tradenotsensitiveinfos.list.get?...
```
在获取并初步处理完这些数据之后，需要将其写入用友BIP对应模块内。这一环节中使用了用友BIP提供的`sale return save` API：`/yonbip/sd/vouchersalereturn/singleSave`。为了适应这两个系统间的数据格式差异，整个流程还包括了定制化的数据映射和转换逻辑。
```text
POST /yonbip/sd/vouchersalereturn/singleSave HTTP/1.1
Host: yonbip.example.com
Content-Type: application/json
{
// 请求体内容示例，请参考官方文档进行字段映射和填充
}
```
#### 数据流监控与异常处理
应用轻易云平台的一大优势是能够实时监控整个数据流动过程。从采集、清洗、转换到最终写入，用一个透明可视化界面进行展示，不仅提高业务透明度，还能及时发现并解决潜在问题。例如，在实际运行过程中，通过设置专门的告警规则来监测接口返回状态码，当出现异常时可以迅速介入处理或触发自动重试机制，以确保任务顺利完成而不丢单。
此外，为应对可能发生的大规模数据写入需求，该方案充分利用轻易云平台所支持的批量操作能力，将大量交易记录一次性导入目标系统，大幅提升了整体效率和可靠性。
综上所述，通过合理利用各项技术特点，本案例实现了跨系统、高效、安全且可靠的数据集成。接下来我们将更深入地剖析每一步实施细节及遇到的问题解决方法。
### 调用吉客云·奇门接口jackyun.tradenotsensitiveinfos.list.get获取并加工数据
在数据集成的生命周期中，调用源系统接口是关键的第一步。本文将详细探讨如何使用轻易云数据集成平台，通过调用吉客云·奇门接口`jackyun.tradenotsensitiveinfos.list.get`来获取并加工数据。
#### 接口配置与请求参数
首先，我们需要了解该接口的基本配置和请求参数。根据元数据配置，接口采用POST方法，主要参数如下：
- **modified_begin** 和 **modified_end**：用于指定修改时间的起始和结束时间，必须同时存在且间隔不能超过七天。
- **tradeNo**：销售单号，可多个用半角逗号分隔。
- **pageSize** 和 **pageIndex**：分页参数，每页记录数默认为50，最大1000；页码从0开始。
- **startConsignTime** 和 **endConsignTime**：发货时间的起始和截止时间。
- **fields**：需要返回的字段列表，以逗号分隔。
示例请求体如下：
```json
{
"modified_begin": "2023-10-01T00:00:00",
"modified_end": "2023-10-07T23:59:59",
"tradeNo": "123456,789012",
"pageSize": "100",
"pageIndex": "0",
"startConsignTime": "{{HOURE_AGO_1|datetime}}",
"endConsignTime": "{{CURRENT_TIME|datetime}}",
"fields": "checkTotal,tradeNo,postFee,otherFee,..."
}
```
#### 数据清洗与转换
获取到原始数据后，需要进行数据清洗与转换。以下是几个关键步骤：
1. **字段映射与重命名**：根据业务需求，将原始字段映射到目标系统所需的字段。例如，将`tradeNo`映射为`orderNumber`。
2. **数据类型转换**：确保所有字段的数据类型符合目标系统要求。例如，将字符串类型的日期字段转换为日期类型。
3. **过滤无效数据**：根据条件过滤掉不需要的数据。例如，根据元数据配置中的条件，过滤掉`goodsDetail.sellCount`为0或`goodsDetail.goodsNo`为空的数据。
4. **分页处理**：由于接口返回的数据可能会分页，需要处理多页数据的合并。在每次请求时，通过调整`pageIndex`参数获取下一页的数据，直到没有更多数据为止。
示例代码片段：
```python
import requests
import json
def fetch_data():
url = 'https://api.jackyun.com/tradenotsensitiveinfos/list/get'
headers = {'Content-Type': 'application/json'}
payload = {
"modified_begin": "2023-10-01T00:00:00",
"modified_end": "2023-10-07T23:59:59",
"tradeNo": "123456,789012",
"pageSize": 100,
"pageIndex": 0,
"startConsignTime": "{{HOURE_AGO_1|datetime}}",
"endConsignTime": "{{CURRENT_TIME|datetime}}",
"fields": "checkTotal,tradeNo,postFee,otherFee,..."
}
all_data = []
while True:
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
# 数据清洗与转换
cleaned_data = clean_data(data)
all_data.extend(cleaned_data)
if len(data) < payload['pageSize']:
break
payload['pageIndex'] += 1
return all_data
def clean_data(data):
cleaned = []
for item in data:
if item['goodsDetail']['sellCount'] == 0 or not item['goodsDetail']['goodsNo']:
continue
cleaned_item = {
'orderNumber': item['tradeNo'],
'totalFee': item['totalFee'],
# 更多字段映射...
}
cleaned.append(cleaned_item)
return cleaned
```
#### 异常处理与日志记录
在实际操作中，还需要考虑异常处理和日志记录，以确保数据集成过程的可靠性和可追溯性。例如：
```python
try:
all_data = fetch_data()
except Exception as e:
log_error(e)
```
通过上述步骤，我们可以有效地调用吉客云·奇门接口获取销售单数据，并进行必要的数据清洗与转换，为后续的数据写入阶段做好准备。
### 轻易云数据集成平台中的ETL转换：将销售单数据写入用友BIP
在轻易云数据集成平台中，数据处理的生命周期包括多个步骤，其中关键的一步是将已经集成的源平台数据进行ETL（提取、转换、加载）转换，并转为目标平台用友BIP API接口所能够接收的格式，最终写入目标平台。本文将重点探讨如何使用元数据配置，将2C吉客云的销售单数据转换为用友BIP销售退货单的数据格式，并通过API接口写入用友BIP系统。
#### 数据转换与API接口调用
在进行ETL转换时，我们需要特别关注以下几个关键步骤：
1. **数据提取与清洗**：从源系统提取原始销售单数据，并进行必要的清洗和预处理。
2. **数据映射与转换**：根据目标系统API接口的要求，将源系统的数据字段映射到目标系统的数据字段，并进行必要的格式转换。
3. **数据写入**：通过调用目标系统的API接口，将转换后的数据写入目标系统。
#### 元数据配置解析
以下是用于将销售单数据写入用友BIP API接口的元数据配置：
```json
{
"api": "/yonbip/sd/vouchersalereturn/singleSave",
"method": "POST",
"idCheck": true,
"request": [
{
"field": "resubmitCheckKey",
"label": "保证请求的幂等性",
"type": "string",
"describe": "保证请求的幂等性,该值由客户端生成,并且必须是全局唯一的，长度不能超过32位。更多信息,请参见«MDD幂等性»",
"value": "{tradeNo}-20240318"
},
{
"field": "code",
"label": "单据编码",
"type": "string",
"describe": "单据编码，以系统编码规则配置为准：系统设置为手工编号时必输，系统设置为自动编号时非必输；修改时必传 示例：\"S0T5-0000000000-20210831-000000\"",
"value": "{tradeNo}"
},
{
"field": "salesOrgId",
"label": "销售组织",
...
}
]
}
```
上述配置定义了一个POST请求，用于调用用友BIP的`/yonbip/sd/vouchersalereturn/singleSave` API接口。以下是几个关键字段及其映射和转换逻辑：
1. **resubmitCheckKey**：
- 用于保证请求的幂等性，确保每个请求都有一个唯一标识符。
- 配置中使用了占位符 `{tradeNo}`，表示该值将从源系统中提取并拼接日期后生成。
2. **code**：
- 单据编码，根据系统编码规则配置。
- 配置中直接使用 `{tradeNo}` 占位符，从源系统获取交易编号。
3. **salesOrgId**：
- 销售组织ID或代码。
- 使用 `{shopCode}` 占位符，从源系统获取商店代码，并通过映射关系转换为目标系统所需格式。
4. **saleReturnDetails**：
- 退货单详情，是一个数组类型字段，每个元素代表一个退货商品明细。
- 内部包含多个子字段，如 `productId`（商品ID）、`qty`（退货数量）等，这些子字段同样需要进行映射和格式转换。
#### 数据映射与格式转换
在实际操作中，需要根据元数据配置中的描述和示例，对每个字段进行相应的数据映射和格式转换。例如：
- **productId** 映射：
```json
{
...
{
"field": "productId",
...
"value": "{{goodsDetail.goodsNo}}"
}
...
}
```
表示从源系统中的 `goodsDetail.goodsNo` 字段获取商品ID，并直接赋值给目标系统中的 `productId` 字段。
- **qty** 转换：
```json
{
...
{
"field": "qty",
...
"value":"_function '{{goodsDetail.sellCount}}'*(-1)"
}
...
}
```
表示从源系统中的 `goodsDetail.sellCount` 字段获取销售数量，并通过 `_function` 函数将其乘以-1，得到退货数量。
#### 调用API接口
完成所有字段的映射和格式转换后，通过HTTP POST请求调用用友BIP API接口，将组装好的JSON对象发送到目标URL：
```python
import requests
import json
url = 'https://api.yonyou.com/yonbip/sd/vouchersalereturn/singleSave'
headers = {'Content-Type': 'application/json'}
data = {
# 根据元数据配置组装好的JSON对象
}
response = requests.post(url, headers=headers, data=json.dumps(data))
if response.status_code == 200:
print('Data successfully written to Yonyou BIP')
else:
print(f'Failed to write data: {response.text}')
```
以上代码片段展示了如何使用Python脚本调用API接口，将组装好的JSON对象发送到用友BIP，实现销售退货单的数据写入。
通过上述步骤，我们可以高效地完成从2C吉客云到用友BIP的数据集成，实现不同异构系统间的数据无缝对接。
