如何通过ETL实现汤臣倍健营销云到金蝶云的流畅数据集成

API数据转换与写入：实现汤臣倍健与金蝶云的系统对接

2023-03-01 17:28:58
轻易云集成顾问-谢楷斌

汤臣倍健营销云数据集成至金蝶云星辰V2案例分享

在企业信息化过程中，统一的数据管理和流畅的系统对接是实现高效运营的关键。本文将详细介绍一个具体技术案例——如何通过轻易云数据集成平台，将汤臣倍健营销云中的退货入库业务数据无缝对接到金蝶云星辰V2，实现业务流程的自动化与数据透明。

案例背景及核心挑战

此次集成任务主要涉及从汤臣倍健营销云获取退货入库订单数据，并批量写入至金蝶云星辰V2系统。这一过程面临以下几个核心挑战：

如何确保集成汤臣倍健营销云数据不漏单：我们需要精准地抓取所有相关订单，避免任何遗漏，以保证销售退货处理的完整性。
大量数据快速写入到金蝶云星辰V2：为了提高系统效率，大量订单需快速、稳定地写入目标系统中。
定时可靠地抓取汤臣倍健营销云接口数据：使用API /erp/api/order/query/saleReturnOrder 定期、安全地获取最新销售退货单据是此方案的重要环节。
处理分页和限流问题：因接口调用存在限制，我们必须合理设计分页策略，并且做好应对限流情况的准备。
解决跨平台的数据格式差异问题：不同平台之间的数据结构会有所不同，需要进行必要的数据转换，以保证顺利对接。
异常处理与错误重试机制的实现：在面对网络波动或其他不可预见的问题时，设置完善的错误重试机制尤为重要，以增加整个流程的鲁棒性。

接口配置及操作详解

调用接口获取源端数据
- 使用轻易云配置任务，通过GET请求访问 https://api.example.com/erp/api/order/query/saleReturnOrder 获取待处理销售退货单。据了解，该API支持按时间段查询，并返回JSON格式结果，其中包含了详细的订单信息（如客户ID、产品SKU、数量等）。
实时监控与日志记录
- 在抓取过程中，为确保每一步操作都能被追踪和复盘，我们引入了实时监控和日志记录功能，对每次接口调用以及响应状态进行详细记录；这不仅便于排查故障，也能够优化后续批量运行策略。
批量插入目的端数据库
- 调用POST方法向 https://cloud.kingdee.com/jdy/v2/scm/sal_in_bound 写入已转换格式后的销售退货单。在这一环
  调用源系统汤臣倍健营销云接口获取并加工数据

在数据集成的生命周期中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用汤臣倍健营销云的/erp/api/order/query/saleReturnOrder接口来获取并加工退货入库数据。

接口配置与请求参数

首先，我们需要了解该接口的元数据配置。以下是该接口的主要配置项：

API路径: /erp/api/order/query/saleReturnOrder
请求方法: POST
操作类型: QUERY
主要字段:
- tenantId: 经销商ID（必填）
- yxyNumber: 营销云销售订单号
- number: 系统订单号
- status: 订单状态（0: 未审核, 1: 已审核）
- beginTime: 开始时间
- endTime: 结束时间
- pageNo: 页码（默认1）
- pageSize: 每页条数（默认30）
- timeType: 时间段标志（0: 创建时间, 1: 最后更新时间）

请求参数详解

在实际调用过程中，参数配置至关重要。以下是一些关键参数及其作用：

tenantId: 经销商ID，这是一个必填项，用于标识具体的经销商。例如：34cc4109705e4c058b7b3b0352e57d31。
yxyNumber和number: 分别对应营销云销售订单号和系统订单号。当传递这些参数时，其他时间状态等条件将无效。
status: 用于过滤订单状态，例如传递值为1表示已审核的订单。
beginTime和endTime: 用于定义查询的时间范围，这两个字段在不传递单号时必填。格式为YYYY-MM-DD或YYYY-MM-DD HH:mm:ss。
pageNo和pageSize: 用于分页查询，默认值分别为1和30。
timeType: 时间段标志，0表示基于创建时间查询，1表示基于最后更新时间查询。

请求示例

以下是一个实际请求示例：

{
    "tenantId": "34cc4109705e4c058b7b3b0352e57d31",
    "status": "1",
    "beginTime": "{{LAST_SYNC_TIME|datetime}}",
    "endTime": "{{CURRENT_TIME|datetime}}",
    "pageNo": "1",
    "pageSize": "30",
    "timeType": "1"
}

在这个示例中，我们请求了特定经销商ID下已审核的订单，并指定了查询的时间范围和分页信息。

数据清洗与转换

获取到数据后，需要进行清洗与转换，以确保数据的一致性和完整性。这包括但不限于：

字段映射与重命名：根据目标系统的要求，将源系统的数据字段映射到目标字段。例如，将源系统中的number字段映射为目标系统中的order_number。
数据格式转换：将日期、金额等字段转换为目标系统所需的格式。例如，将日期格式从YYYY-MM-DD HH:mm:ss转换为目标系统所需的格式。
异常数据处理：过滤掉不符合业务规则的数据，如缺失关键字段的数据记录。

自动填充响应

轻易云平台提供了自动填充响应功能，即在成功调用API并获取数据后，可以自动将响应结果填充到预定义的数据结构中。这极大地简化了后续的数据处理步骤。

实时监控与日志记录

为了确保数据集成过程的透明性和可追溯性，实时监控与日志记录是必不可少的。通过轻易云平台，可以实时监控API调用情况，并记录每次调用的详细日志，包括请求参数、响应结果、错误信息等。这有助于快速定位和解决问题，提高数据集成效率。

综上所述，通过合理配置请求参数、进行有效的数据清洗与转换，以及利用自动填充响应功能，可以高效地实现对汤臣倍健营销云接口的数据集成，为后续的数据处理奠定坚实基础。金蝶云星空API接口配置

利用轻易云数据集成平台实现金蝶云星辰V2API接口的数据转换与写入

在数据集成过程中，ETL（Extract, Transform, Load）转换是关键步骤之一。本文将详细探讨如何通过轻易云数据集成平台，将源平台的数据转换为金蝶云星辰V2API接口所能接收的格式，并最终写入目标平台。

元数据配置解析

在进行ETL转换之前，首先需要理解元数据配置。以下是一个具体的元数据配置示例：

{
  "api": "/jdy/v2/scm/sal_in_bound",
  "effect": "EXECUTE",
  "method": "POST",
  "number": "id",
  "id": "id",
  "name": "id",
  "idCheck": true,
  "request": [
    {"field":"bill_source","label":"来源","type":"string","value":"ISV"},
    {"field":"bill_date","label":"出库日期","type":"string","describe":"出库日期,格式：2019-01-01","value":"{{auditTime|date}}"},
    {"field":"customer_id","label":"客户","type":"string","describe":"客户","value":"_findCollection find id from 2571be32-59cc-3353-9ba0-2fb855f844d0 where number={extCusCode}"},
    {"field":"remark","label":"单据备注","type":"string","describe":"上传的附件url","value":"{remark}-来自营销云-{number}"},
    {"field":"contact_address","label":"联系信息-详细地址","type":"string","describe":"联系信息-详细地址","value":"{shippingAddress}"},
    {"field":"contact_linkman","label":"联系信息-联系人","type":"string","describe":"联系信息-联系人","value":"{contacts}"},
    {"field":"contact_phone","label":"联系信息-联系方式","type":"string","describe":"联系信息-联系方式","value":"{phone}"},
    {"field":"dept_number","label":"部门编码","type":"string","describe":"业务员","value":"100000"},
    {
      "field": "material_entity",
      "label": "商品分录",
      "type": "array",
      "describe": "商品分录",
      "value": "itemList",
      "children": [
        {"field": "material_id", "label": "商品id", "type": "string", "describe": "商品id", 
            "value": "_findCollection find id from b5d1f599-d90a-3a38-bc95-1ea455bced41 where number={extMaterialNo}"},
        {"field": "stock_id", "label": "仓库id", 
            "type": "string", 
            "describe": 
            "仓库id", 
            "value":
                "1545736562556290048"},
        {"field":
                "qty", 
            "label":
                "数量", 
            "type":
                "int", 
            "describe":
                "数量", 
            "value":
                "{{itemList.opernumber}}"},
        {"field":
                "tax_price", 
            "label":
                "含税单价", 
            "type":
                "int", 
            "describe":
                "含税单价", 
            "value":
                "{{itemList.taxunitprice}}"},
        {"field":
                "is_free", 
            "label":
                "是否赠品", 
            "type":
                "bool", 
            "describe":
                "是否赠品", 
            "value":
                false},
        {"field":
                "unit_id", 
            "label":
                "单位id", 
            "type":
                string, describe:
                 单位id, value:
                 _findCollection find base_unit_id from b5d1f599-d90a-3a38-bc95-1ea455bced41 where number={extMaterialNo}},
        { field:
                 batch_no, label:
                 批次号, type:
                 string, describe:
                 批次号, value:
                 {{itemList.lot}}},
        { field:
                 comment, label:
                 行备注, type:
                 string, describe:
                 行备注, value:
                 {{itemList.remark}}},
        { field:
                 kf_date, label:
                 生产日期, type:
                 string, describe:
                 生产日期, value:
                 {{itemList.mfg}}},
        { field:
                 valid_date, label:
                 有效日期, type:
                 string, describe:
                 有效日期, value:
                 {{itemList.exp}}},
        { field: kf_period,
          label: 保质期天数,
          type: string,
          describe: 保质期天数,
          value: 2},
        { field: kf_type,
          label: 保质期类型,
          type: string,
          describe: 保质期类型，1：天，2：月，3：年,
          value: 3}
      ]
    },
    {
      field: custom_field,
      label: 自定义字段,
      type: object,
      children: [
        { field: custom_field__1__2uvgd1jiapcazg,
          label: 营销云单号,
          type: string,
          value: {number}},
        { field: custom_field__1__2xf8ohpvbytn,
          label: 下单人,
          type: string,
          value: {number}}
      ]
    }
  ]
}

数据请求与清洗

在ETL流程中，首先需要从源平台请求数据并进行清洗。假设我们已经完成了这一阶段，现在我们需要将清洗后的数据转换为金蝶云星辰V2API接口所能接收的格式。

数据转换与写入

根据元数据配置，我们可以逐步将源平台的数据映射到目标平台所需的字段。

映射主要字段

来源（bill_source）：
```
{
 "bill_source": "ISV"
}
```

出库日期（bill_date）：

{
 // 假设 auditTime 是一个时间戳
 // 使用模板引擎将其格式化为 YYYY-MM-DD 格式
 // 格式化后的结果如："2023-10-10"
 bill_date = format(auditTime)
}

客户ID（customer_id）：

{
 // 从指定集合中查找客户ID
 customer_id = findCustomerId(extCusCode)
}

单据备注（remark）：

{
 remark = remark + "-来自营销云-" + number
}

商品分录映射

对于数组类型的字段，如商品分录（material_entity），需要对每个子项进行映射：

{
  material_entity = itemList.map(item => ({
    material_id = findMaterialId(item.extMaterialNo),
    stock_id = '1545736562556290048',
    qty = item.opernumber,
    tax_price = item.taxunitprice,
    is_free = false,
    unit_id = findUnitId(item.extMaterialNo),
    batch_no = item.lot,
    comment = item.remark,
    kf_date = item.mfg,
    valid_date = item.exp,
    kf_period = '2',
    kf_type = '3'
  }))
}

自定义字段映射

{
  custom_field__1__2uvgd1jiapcazg = number,
  custom_field__1__2xf8ohpvbytn = number
}

最终JSON结构

整合上述所有字段后，我们得到最终的JSON结构：

{
  bill_source : 'ISV',
  bill_date : format(auditTime),
  customer_id : findCustomerId(extCusCode),
  remark : remark + "-来自营销云-" + number,
  contact_address : shippingAddress ,
  contact_linkman : contacts ,
  contact_phone : phone ,
 dept_number : '100000',
 material_entity : itemList.map(item => ({
 material_id : findMaterialId(item.extMaterialNo),
 stock_id : '1545736562556290048',
 qty : item.opernumber ,
 tax_price : item.taxunitprice ,
 is_free : false ,
 unit_id : findUnitId(item.extMaterialNo),
 batch_no : item.lot ,
 comment : item.remark ,
 kf_date : item.mfg ,
 valid_date : item.exp ,
 kf_period : '2' ,
 kf_type :'3'
 })),
 custom_field__1__2uvgd1jiapcazg:number ,custom_field__1__2xf8ohpvbytn:number}

数据写入目标平台

最后一步是通过HTTP POST请求将转换后的JSON数据发送到金蝶云星辰V2API接口：

const axios = require('axios');

axios.post('/jdy/v2/scm/sal_in_bound', finalData)
.then(response => {
 console.log('Data successfully written to 金蝶云星辰:', response.data);
})
.catch(error => {
 console.error('Error writing data to 金蝶云星辰:', error);
});

通过以上步骤，我们成功地将源平台的数据转换为金蝶云星辰V2API接口所能接收的格式，并完成了数据写入。这一过程展示了如何利用轻易云数据集成平台高效地进行ETL转换和系统间的数据无缝对接。电商OMS与ERP系统接口开发配置

版权声明

该文章《如何通过ETL实现汤臣倍健营销云到金蝶云的流畅数据集成》为原创内容，版权归 广东轻亿云软件科技有限公司 所有。未经本公司书面授权，严禁转载、引用、复制或建立镜像等行为。若需转载或引用本文内容，请联系本公司获取授权，并在显著位置注明作者姓名、文章出处（包括原文链接）等信息。