轻易云平台：详细探讨ETL至金蝶云星辰V1API接口

2021-07-29 02:03:29
轻易云集成顾问-胡秀丛

系统对接集成案例分享：旺店通·企业奇门数据集成到金蝶云星辰V1

在实施复杂业务系统的数据对接过程中，确保数据流的完整性和高效处理是至关重要的一环。本案例将重点介绍如何通过轻易云数据集成平台，实现wk_销售出库单方案中旺店通·企业奇门与金蝶云星辰V1的数据无缝集成。

确保数据不漏单

在本次项目中，我们首先要解决的核心问题是如何确保从旺店通·企业奇门接口（wdt.stockout.order.query.trade）抓取的数据不会出现遗漏。为了实现这一目标，我们实现了定时可靠的任务调度机制，每隔一定时间间隔自动调用该API，并维护一个日志记录系统用于实时监控每个请求的状态。

批量快速写入

针对大量销售出库单据，需要高效地写入到金蝶云星辰V1。在这里，我们采用了批量处理技术，将从旺店通获取的大批量数据按一定规则进行整合，再通过调用金蝶云提供的对应API接口（jdy/sal/sal_outbound_save），一次性完成多条记录的导入。同时，为了防止因网络或服务异常导致的数据丢失，每个操作都会有详细的错误重试机制。

数据格式转换及映射

由于两个系统之间的数据结构存在差异，为保证正确性，在抓取原始订单数据后，我们引入了一套自定义映射逻辑。这不仅包括基础字段匹配，还涉及到复合逻辑转换，如订单状态、库存信息等。配置好的参数化模板能够灵活应对不同场景下的数据对接需求，有效降低手工干预成本。

异常处理与限流管理

在实际运行过程中，API接口可能会受到分页和限流政策影响。为此我们开发了一系列辅助工具，包括但不限于分页查询策略和限流控制器，以便动态调整请求频率并确保顺利完成大规模数据拉取。此外，通过设定合理超时时间以及捕获各种可能发生的异常情况构建全面可靠性的事务管理，使得整个流程更加稳定、可靠。

以上便是本次“wk_销售出库单”项目中的关键步骤概述。在随后的文章部分，将详解如何具体配置这些技术细节，保障整个过程有效落地。打通企业微信数据接口

调用源系统旺店通·企业奇门接口wdt.stockout.order.query.trade获取并加工数据

在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用旺店通·企业奇门接口wdt.stockout.order.query.trade，并对获取的数据进行初步加工。

接口调用配置

首先，我们需要配置元数据以便正确调用接口。以下是关键的元数据配置项：

API: wdt.stockout.order.query.trade
请求方法: POST
分页大小: 100
增量获取时间段: 使用start_time和end_time字段

{
  "api": "wdt.stockout.order.query.trade",
  "method": "POST",
  "number": "order_no",
  "id": "stockout_id",
  "pagination": {
    "pageSize": 100
  },
  "omissionRemedy": {
    "crontab": "55 * * * *",
    "adapter": "\\Adapter\\Wdt\\WdtQMQueryAdapter",
    "takeOverRequest": [
      {
        "field": "start_time",
        "label": "修改时间开始段",
        "type": "string",
        "is_required": true,
        "value": "{{HOURE_AGO_1|datetime}}"
      }
    ]
  },
  "idCheck": true,
  "request": [
    {
      "field": "start_time",
      "label": "开始时间",
      "type": "datetime",
      "describe": "增量获取数据，start_time作为开始时间，格式：yyyy-MM-dd HH:mm:ss",
      "value": "{{LAST_SYNC_TIME|datetime}}"
    },
    {
      "field": "end_time",
      "label": "结束时间",
      "type": "datetime",
      "describe":"增量获取数据，end_time作为结束时间，格式：yyyy-MM-dd HH:mm:ss",
      'value': '{{CURRENT_TIME|datetime}}'
    },
    {
      'field': 'status',
      'label': '状态',
      'type': 'string',
      'describe': '5已取消，55已审核，95已发货，105 部分打款，110已完成，113：异常发货'
    },
    {
      'field': 'src_order_no',
      'label': '系统订单编号',
      'type': 'string'
    },
    {
      'field': 'src_tid',
      'label': '原始单号',
      'type': 'string'
    },
    {
      'field': 'stockout_no',
      'label': '出库单号',
      'type': 'string'
    },
    {
      'field': 'shop_no',
      'label': '店铺编号',
      'type':'string',
      'describe':'代表店铺所有属性的唯一编码，用于店铺区分，ERP内支持自定义（ERP店铺界面设置），用于获取指定店铺单据数据信息'
    },
    {
       'field':'warehouse_no',
       'label':'仓库编号',
       'type':'string',
       'describe':'代表仓库所有属性的唯一编码，用于仓库区分，ERP内支持自定义（ERP仓库界面设置），用于获取指定仓库单据数据信息(不支持一次推送多个仓库编号)'
     },
     {
       'label':'is_by_modified',
       'field':'is_by_modified',
       'type':'string'
     }
   ],
   'otherRequest':[{
     'field':'page_size',
     'label':'分页大小',
     'type':'string',
     'describe':'每页返回的数据条数，输入值范围1~100，不传本参数，输入值默认为40。',
     'value':'{PAGINATION_PAGE_SIZE}'
   },{
     'field':'page_no',
     'label':'页号',
     'type':'string',
     'describe':'不传值默认从0页开始。',
     'value':'{PAGINATION_START_PAGE}'
   }]
}

数据请求与清洗

在调用接口时，我们需要特别注意以下几点：

增量同步：通过start_time和end_time字段实现增量同步。start_time通常设置为上次同步时间，而end_time则设置为当前时间。
分页处理：由于接口返回的数据可能非常庞大，因此需要使用分页机制。我们可以通过配置分页大小和页号来控制每次请求的数据量。
状态过滤：根据业务需求，可以通过status字段过滤不同状态的订单，例如已取消、已审核、已发货等。

以下是一个示例请求体：

{
  “start_time”: “2023-10-01 00:00:00”,
  “end_time”: “2023-10-01 23:59:59”,
  “status”: “95”,
  “page_size”: “100”,
  “page_no”: “0”
}

数据转换与写入

在成功获取数据后，需要对其进行初步加工和清洗，以确保数据质量。例如：

字段映射：将源系统中的字段映射到目标系统中的相应字段。
数据格式转换：将日期、金额等字段转换为目标系统所需的格式。
异常处理：对于缺失或异常的数据进行处理，如填充默认值或记录日志。

以下是一个简单的数据转换示例：

def transform_data(raw_data):
    transformed_data = []
    for record in raw_data:
        transformed_record = {}
        transformed_record['order_id'] = record['stockout_id']
        transformed_record['order_number'] = record['order_no']
        transformed_record['status'] = map_status(record['status'])
        transformed_record['timestamp'] = convert_datetime(record['modified'])
        transformed_data.append(transformed_record)
    return transformed_data

通过上述步骤，我们可以高效地调用旺店通·企业奇门接口并对数据进行初步加工，为后续的数据写入和进一步处理打下坚实基础。打通钉钉数据接口

轻易云数据集成平台：ETL转换至金蝶云星辰V1API接口

在使用轻易云数据集成平台进行数据处理时，生命周期的第二步是将已经集成的源平台数据进行ETL（提取、转换、加载）转换，并将其转为目标平台金蝶云星辰V1API接口所能够接收的格式，最终写入目标平台。本文将详细探讨这一过程中的技术细节和实现方法。

元数据配置解析

根据提供的元数据配置，我们需要将源数据转换为符合金蝶云星辰V1API接口规范的格式。以下是主要字段及其配置解析：

单据来源 (billsource)：固定传入值 "APP"。
出库日期 (billdate)：通过模板变量 {{consign_time|date}} 转换为指定格式 "2019-01-01"。
单据编号 (billno)：直接映射到 {order_no}。
客户信息 (customerid_id)：通过 _findCollection 函数查找客户ID，基于 shop_name 进行匹配。
业务员信息 (empid_id)：此字段未指定具体值，需根据实际业务逻辑填充。
单据备注 (remark)：映射到 {cs_remark}。
联系信息：
- 联系方式 (contact_phone)
- 国家ID (contact_country_id)
- 省ID (contact_province_id)
- 市ID (contact_city_id)
- 区ID (contact_district_id)

这些字段均需从源数据中提取相应的信息。

商品分录配置解析

商品分录是一个复杂的嵌套数组结构，需要逐项处理：

商品 (materialid_id)：通过 _findCollection 函数查找商品ID，基于 details_list.spec_no 进行匹配。
仓库 (stockid_id)：通过 _findCollection 函数查找仓库ID，基于 warehouse_name 进行匹配。
数量 (qty)：直接映射到 {{details_list.goods_count}}。
单位 (unit_id)：固定值 "2"，需确保与商品关联单位一致。
单价 (price)：使用 _function 函数计算单价，公式为 ({{details_list.total_amount}} + {{details_list.share_post}}) / {{details_list.goods_count}}。
税率 (cess)：直接映射到 {{details_list.tax_rate}}。
是否赠品 (is_free)：使用 _function CASE WHEN {{details_list.sell_price}}>0 THEN 'false' ELSE 'true' END 判断是否为赠品。
批次 (batchno)：映射到 {batch_no}。

数据转换与写入

在完成上述字段解析后，我们需要构建请求体并通过POST方法调用金蝶云星辰V1API接口。以下是具体实现步骤：

提取源数据 从源系统中提取原始数据，包括订单信息、客户信息、商品明细等。
字段映射与转换 根据元数据配置，将源数据字段映射并转换为目标格式。例如，将订单编号 {order_no} 映射到 billno 字段，将出库日期 {{consign_time|date}} 转换为符合要求的日期格式等。

构建请求体 按照API接口规范构建请求体，包括所有必填字段和嵌套数组结构。示例如下：

{
   "billsource": "APP",
   "billdate": "2023-10-01",
   "billno": "ORD123456",
   "customerid_id": "CUST001",
   "empid_id": "EMP001",
   "remark": "备注信息",
   ...
   "material_entity": [
       {
           "materialid_id": "MAT001",
           "stockid_id": "STOCK001",
           ...
       }
       ...
   ]
}

调用API接口 使用HTTP POST方法将构建好的请求体发送至金蝶云星辰V1API接口：

POST /jdy/sal/sal_outbound_save HTTP/1.1
Host: api.kingdee.com
Content-Type: application/json
Authorization: Bearer <access_token>

{
   // 请求体内容
}

处理响应 接收并处理API响应，根据返回结果判断操作是否成功，并进行相应的错误处理或日志记录。

技术要点总结

在整个ETL过程中，关键技术点包括：

使用模板变量和函数进行动态字段转换和计算；
利用 _findCollection 函数实现跨系统的数据查找和匹配；
构建符合目标系统API规范的复杂嵌套结构请求体；
实现高效的数据传输和错误处理机制。

通过以上步骤，可以确保源平台的数据顺利转化并写入目标平台金蝶云星辰V1，实现系统间的数据无缝对接和业务流程自动化。如何开发用友BIP接口