### 旺店通·旗舰版数据集成到金蝶云星空案例分享：入库瞬时成本-销售退货入库-1
在企业日常运作中，如何高效、准确地将不同系统的数据进行无缝对接是一个关键问题。本文聚焦于一次具体的系统对接案例，即将旺店通·旗舰版的数据集成到金蝶云星空中的详细过程及其技术细节。本次案例方案名为“入库瞬时成本-销售退货入库-1”，旨在演示如何通过轻易云数据集成平台实现从获取数据、处理格式转换，到最终成功写入目标系统的全过程。
本次实施的核心是调用旺店通·旗舰版提供的接口`statistic.StockinCollect.queryCostWithDetail`来获取详细的库存与成本信息，并通过金蝶云星空API `batchSave` 将处理后的数据批量快速写入。整个过程需要解决如下几个技术挑战：
1. **确保数据不漏单**：为了保证从旺店通·旗舰版抓取的数据完整性，我们使用定时任务可靠地触发API抓取动作，每个任务周期结束后都会检查是否存在遗漏。
2. **实时监控与日志记录**：整个集成过程中，我们启用了实时监控机制和详尽日志记录功能，确保每一步骤都可被追溯，大大降低了调试难度。
3. **分页和限流处理**：由于源系统接口存在一定的分页限制和调用频率限制，我们设计了一套智能分页策略，以确保大量数据能够被顺利、高效地拉取。
4. **异常处理与错误重试机制**：在向目标系统写入过程中，可能会出现网络波动或者其他意外情况导致部分请求失败。我们构建了一套完善的错误捕捉和重试机制来应对这种情况。
以下章节将具体讲解各步骤操作方法，包括API调用配置、分页策略设置以及自定义映射规则等内容。这些细节不仅能提高用户对于相关技术环节的理解，还可以帮助他们更好地应对类似项目中的各种挑战与问题。
### 调用旺店通·旗舰版接口statistic.StockinCollect.queryCostWithDetail获取并加工数据
在数据集成的生命周期中，调用源系统接口是至关重要的一步。本文将深入探讨如何通过轻易云数据集成平台调用旺店通·旗舰版的`statistic.StockinCollect.queryCostWithDetail`接口，并对获取的数据进行初步加工。
#### 接口概述
接口`statistic.StockinCollect.queryCostWithDetail`主要用于查询入库瞬时成本，特别适用于销售退货入库场景。该接口采用POST请求方式，能够根据指定的查询参数返回详细的入库成本信息。
#### 元数据配置解析
元数据配置如下：
```json
{
"api": "statistic.StockinCollect.queryCostWithDetail",
"effect": "QUERY",
"method": "POST",
"number": "stockin_no",
"id": "stockin_id",
"name": "stockout_no",
"idCheck": true,
"request": [
{
"field": "params",
"label": "查询参数",
"type": "object",
"children": [
{
"field": "start_time",
"label": "开始时间",
"type": "string",
"describe": "起始时间（发货时间），若无出库单号则为必填。",
"value": "{{LAST_SYNC_TIME|datetime}}"
},
{
"field": "end_time",
"label": "结束时间",
"type": "string",
"describe": "结束时间（发货时间）",
"value": "{{CURRENT_TIME|datetime}}"
},
{
...
}
]
},
...
],
...
}
```
#### 请求参数详解
1. **params**: 查询参数对象，包括以下字段：
- **start_time**: 起始时间，格式为字符串，通常使用上次同步时间。
- **end_time**: 结束时间，格式为字符串，通常使用当前时间。
- **warehouse_no**: 仓库编号，用于指定查询的仓库。
- **stockin_no**: 入库单号，可多个单号用英文逗号分隔。
- **time_type**: 时间查询类型，默认值为2（审核时间）。
2. **pager**: 分页对象，包括以下字段：
- **page_size**: 每页记录数，默认值为100。
- **page_no**: 页码，从1开始。
#### 数据请求与清洗
在调用接口之前，需要构建请求体。以下是一个示例请求体：
```json
{
"params": {
"start_time": "{{LAST_SYNC_TIME|datetime}}",
"end_time": "{{CURRENT_TIME|datetime}}",
...
},
...
}
```
通过轻易云平台，我们可以自动填充这些动态参数，如`{{LAST_SYNC_TIME|datetime}}`和`{{CURRENT_TIME|datetime}}`。这确保了每次请求都能获取到最新的数据。
#### 数据转换与写入
获取到数据后，需要对其进行初步清洗和转换。例如，将返回的数据结构化存储到目标数据库中。在轻易云平台上，可以利用其内置的ETL工具，对数据进行如下处理：
1. **过滤无效数据**：根据业务逻辑过滤掉不需要的数据，例如状态异常或缺失关键字段的数据。
2. **字段映射与转换**：将源数据字段映射到目标系统的字段，并进行必要的格式转换。例如，将日期字符串转换为标准日期格式。
3. **增量更新**：通过检查`stockin_id`等唯一标识符，实现增量更新，避免重复写入。
#### 实际应用案例
假设我们需要从2023年10月1日到2023年10月31日之间的所有销售退货入库记录，并将其存储到我们的内部数据库中。具体步骤如下：
1. 配置请求参数：
```json
{
...
{"field":"start_time","value":"2023-10-01T00:00:00"},
{"field":"end_time","value":"2023-10-31T23:59:59"},
...
}
```
2. 调用接口并获取响应数据：
```json
{
...
// 响应示例
{"data":[{"stockin_id":"12345",...},{"stockin_id":"67890",...}]}
...
}
```
3. 数据清洗与转换：
```sql
INSERT INTO internal_db.stockin_records (stockin_id, ...)
VALUES ('12345', ...), ('67890', ...)
ON DUPLICATE KEY UPDATE ...;
```
通过上述步骤，我们成功实现了从旺店通·旗舰版获取销售退货入库成本数据，并将其高效地集成到我们的内部系统中。这不仅提升了数据处理效率，也确保了业务流程的透明和可追溯性。
### 使用轻易云数据集成平台进行ETL转换并写入金蝶云星空API接口
在数据集成的生命周期中，ETL（Extract, Transform, Load）转换是至关重要的一步。本文将详细探讨如何使用轻易云数据集成平台将源平台的数据转换为金蝶云星空API接口所能接收的格式，并最终写入目标平台。
#### API接口配置与元数据解析
为了实现数据的无缝对接，我们需要配置金蝶云星空API接口的相关元数据。以下是我们需要配置的主要字段及其解析方式：
1. **单据类型 (FBillTypeID)**
- 类型：字符串
- 描述：标准销售退货单、寄售退货单等。
- 解析器：`ConvertObjectParser`，参数为`FNumber`
- 示例值：`XSTHD01_SYS`
2. **单据编号 (FBillNo)**
- 类型：字符串
- 描述：单据编号
- 示例值：`{stockin_no}`
3. **销售组织 (FSaleOrgId)**
- 类型：字符串
- 描述：销售组织
- 解析器：`ConvertObjectParser`，参数为`FNumber`
- 示例值：`100`
4. **日期 (FDate)**
- 类型：字符串
- 描述：日期
- 示例值：`{{check_time|datetime}}`
5. **库存组织 (FStockOrgId)**
- 类型：字符串
- 描述：库存组织
- 解析器：`ConvertObjectParser`，参数为`FNumber`
- 示例值：`100`
6. **退货客户 (FRetcustId)**
- 类型：字符串
- 描述：退货客户
- 解析器：`ConvertObjectParser`，参数为`FNumber`
- 示例值：`THYRK`
7. **结算币别 (FSettleCurrId)**
- 类型：字符串
- 描述：人民币、香港元等。
- 解析器：`ConvertObjectParser`，参数为`FNumber`
- 示例值：`PRE001`
8. **明细信息 (FEntity)**
明细信息包含多个子字段，如物料编码、实退数量、含税单价等：
```json
"children": [
{"field":"FMaterialId","label":"物料编码","type":"string","describe":"物料编码","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{{detail_list.spec_no}}"},
{"field":"FRealQty","label":"实退数量","type":"string","describe":"实退数量","value":"{{detail_list.num}}"},
{"field":"FTaxPrice","label":"含税单价","type":"string","describe":"含税单价","value":"{{detail_list.checked_cost_price}}"},
{"field":"FAmount","label":"金额","type":"string","describe":"含税单价"},
{"field":"FStockId","label":"仓库 ","type":"string","describe":"仓库 ","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{warehouse_no}"},
{"field":"FNote","label":"备注 ","type":"string","describe":"备注 ","value":"{{detail_list.remark}}"},
{"field":"F_UBGN_Decimal1","label":"总成本（旺店通）","type":"string","value":"_function {{detail_list.checked_cost_price}}*{{detail_list.num}}"},
{"field":"F_UBGN_Decimal","label":"成本价（旺店通）","type":"string","value":"{{detail_list.checked_cost_price}}"},
{"field": "FEntryTaxRate", "label": "税率%", "type": "string"}
]
```
9. **财务信息 (SubHeadEntity)**
财务信息包含结算组织等字段：
```json
"children": [
{"field": "FSettleOrgId", "label": "结算组织", "type": "string", "describe": "结算组织", "parser": {"name": "ConvertObjectParser", "params": "FNumber"}, "value": "100"}
]
```
10. **其他字段**
包括制单人、对应旺店通单据等：
```json
[
{"field": "FormId", "label": "业务对象表单Id", "type": "string", "describe": "必须填写金蝶的表单ID如:PUR_PurchaseOrder", "value": "SAL_RETURNSTOCK"},
{"field": "Operation", "label": "执行的操作", "type": "string", "describe": "执行的操作", "value": "BatchSave"},
{"field": "IsAutoSubmitAndAudit", "label": "",提交并审核"type" :bool," describe ":" 提交并审核 "," value ":" true "}，
{“ field”：“ IsVerifyBaseDataField”，“ label”：“验证基础资料”，“ type”：“ bool”，“ describe”：“是否验证所有基础资料有效性，布尔类，默认false（非必录）”，“ value”：“ true "}
]
```
#### 数据转换与写入过程
在ETL过程中，我们首先需要从源平台提取数据，然后根据上述元数据配置进行转换。以下是具体步骤：
1. **提取数据**：
从源平台提取原始数据，例如销售退货入库的数据列表。
2. **数据清洗**：
清洗原始数据以确保其符合目标平台要求。例如，将日期格式统一为目标平台所需格式。
3. **数据转换**：
使用轻易云提供的元数据配置，将清洗后的数据字段映射到金蝶云星空API接口所需的字段。例如，将源平台的物料编码转换为目标平台所需格式。
4. **写入目标平台**：
使用POST请求将转换后的数据批量保存到金蝶云星空系统中。具体请求如下：
```json
{
“api”: “batchSave”，
“effect”： “EXECUTE”，
“method”： “POST”，
“idCheck”： true，
“request”： [ ... ] // 上述元数据信息填充后的请求体内容。
...
“operation”： {
“rowsKey”： “array”，
“rows”： 1，
“method”： “batchArraySave”
}
}
```
通过以上步骤，我们可以实现从源平台到金蝶云星空系统的数据无缝对接，大大提升了业务处理效率和透明度。在实际操作中，可以根据业务需求进一步定制和优化ETL流程，以满足不同场景下的数据集成需求。
