轻易云集成案例：数据转换与上传到聚水潭API

2022-11-29 00:54:41
轻易云集成顾问-曹润

金蝶云星空到聚水潭系统集成案例：组装单（子项）对接其他出库单

在企业信息化管理中，数据的高效流转和准确对接是保证业务顺畅运作的关键。本文将分享一个具体的技术案例，即如何通过轻易云数据集成平台，实现金蝶云星空与聚水潭之间的数据无缝集成。本次配置场景为：金蝶--组装单（子项）=>聚水潭--其他出库单。

技术要点解析

API接口调用与数据获取 利用金蝶云星空提供的executeBillQuery API，我们能够实时、可靠地抓取其系统内的组装单（子项）数据。同时，为了避免漏单现象，我们设计了一套定时任务机制，确保每隔一段时间自动拉取最新数据。
分页处理与限流策略 由于金蝶云星空API对于返回结果有分页限制，我们需要合理设置分页参数并处理批量请求，以便顺利获取全部所需的数据。此外，在高频请求情况下，还需注意API接口的限流问题，通过排队机制来平衡接口调用频率，防止触发限制规则而影响整体流程。
自定义转换逻辑与格式适配 在实现跨系统的数据写入前，需要先完成格式转换。由于金蝶和聚水潭在不同业务模块下的数据结构存在差异，因此必须利用轻易云提供的数据转换工具，自定义编写映射脚本，将源端结构精准匹配至目标端要求的格式，并进行必要的字段校验与补全操作。
数据写入及性能优化 聚水潭支持通过开放API /open/jushuitan/otherinout/upload 接口导入外部数据。在大批量、高频率插入操作中，应当充分发挥平台高吞吐量特点，将预处理后的数据信息快速传输至目标数据库。这不仅提高了工作效率，也减少了因网络波动导致延迟或误差的情况发生。
监控告警及异常重试机制 针对此次集成项目，我们配置了全面且细致的数据监控和告警措施。当出现任何异常状况，如网络故障或接口响应超时等，都能第一时间获得预警信号并采取相应方案，同时启动错误重试机制以保障最终任务执行成功。一整套完善且灵活的问题追踪体系，为整个集成过程保驾护航。

调用金蝶云星空接口executeBillQuery获取并加工数据

在轻易云数据集成平台中，调用源系统接口是数据处理生命周期的第一步。本文将深入探讨如何通过金蝶云星空接口executeBillQuery获取并加工数据。

接口概述

金蝶云星空的executeBillQuery接口支持POST请求，用于查询特定业务对象的数据。该接口支持分页查询，并允许通过过滤条件精确筛选所需数据。以下是元数据配置中的关键参数：

api: "executeBillQuery"
method: "POST"
number: "FBillNo"
id: "FSubEntity_FDetailID"
pagination: {"pageSize":500}
idCheck: true

请求参数配置

在实际调用中，我们需要根据业务需求配置请求参数。以下是主要的请求字段及其含义：

实体主键 (FID): 用于唯一标识每条记录。
单据编号 (FBillNo): 用于标识具体的单据。
单据状态 (FDocumentStatus): 仅查询状态为已审核的单据。
库存组织 (FStockOrgId.FNumber): 指定库存组织编号。
日期 (FDate): 单据日期。
单据类型 (FBillTypeID): 指定单据类型。
成品货主类型 (FOwnerTypeIdHead): 成品货主类型。
成品货主 (FOwnerIdHead.FNumber): 成品货主编号。
事务类型 (FAffairType): 事务类型，示例中为"Assembly"。

其他字段如费用、部门、备注等也可以根据需要进行配置。

分页与过滤条件

为了提高查询效率，接口支持分页查询。分页参数包括：

Limit: 每页返回的最大行数，配置为500。
StartRow: 查询起始行索引，根据实际情况动态调整。

过滤条件通过FilterString字段进行配置，例如：

"FilterString": "FApproveDate>='{{LAST_SYNC_TIME|datetime}}' and FAFFAIRTYPE = 'Assembly' and FDocumentStatus='C'"

该条件表示仅查询审核日期在上次同步时间之后且事务类型为"Assembly"、单据状态为已审核的记录。

字段集合与表单ID

字段集合通过FieldKeys字段指定，包含所有需要查询的字段。例如：

"FieldKeys": ["FID", "FBillNo", "FDocumentStatus", "FStockOrgId.FNumber", ...]

表单ID通过FormId字段指定，例如：

"FormId": "STK_AssembledApp"

实际调用示例

以下是一个实际调用示例，通过POST请求获取组装单（子项）数据：

{
  "api": "executeBillQuery",
  "method": "POST",
  "number": "FBillNo",
  "id": "FSubEntity_FDetailID",
  "pagination": {"pageSize": 500},
  "idCheck": true,
  "request": [
    {"field":"FID","label":"实体主键","type":"string","value":"FID"},
    {"field":"FBillNo","label":"单据编号","type":"string","value":"FBillNo"},
    {"field":"FDocumentStatus","label":"单据状态","type":"string","value":"FDocumentStatus"},
    {"field":"FStockOrgId_FNumber","label":"库存组织","type":"string","value":"FStockOrgId.FNumber"},
    {"field":"FDate","label":"日期","type":"string","value":"FDate"},
    {"field":"FBillTypeID","label":"单据类型","type":"string","value":"FBillTypeID"},
    {"field":"FOwnerTypeIdHead","label":"成品货主类型","type":"string","value":"FOwnerTypeIdHead"},
    {"field":"FOwnerIdHead_FNumber","label":"成品货主","type":"string","value":"FOwnerIdHead.FNumber"},
    {"field":"FAffairType","label":"事务类型","type":"string","value":"FAffairType"},
    ...
  ],
  "otherRequest": [
    {"field": "Limit", "label": "最大行数", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_PAGE_SIZE}"},
    {"field": "StartRow", "label": "开始行索引", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_START_ROW}"},
    {"field": "TopRowCount", "label": "返回总行数", "type": int, describe: 金蝶的查询分页参数},
    {"field": FilterString, label: 过滤条件, type: string, describe: 示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>=, value: FApproveDate>='{{LAST_SYNC_TIME|datetime}}' and FAFFAIRTYPE = 'Assembly' and FDocumentStatus='C'},
    ...
  ]
}

通过上述配置，可以高效地从金蝶云星空系统中获取所需的数据，并在后续步骤中进行进一步的数据清洗和转换处理。企业微信与OA系统接口开发配置

使用轻易云数据集成平台进行ETL转换并写入聚水潭API接口的技术案例

在数据集成生命周期的第二步中，我们需要将已经集成的源平台数据进行ETL（Extract, Transform, Load）转换，最终写入目标平台。在本案例中，我们将金蝶系统中的组装单（子项）数据转换为聚水潭系统能够接收的其他出库单格式，并通过API接口上传。

元数据配置解析

以下是我们在轻易云数据集成平台上配置的元数据：

{
  "api": "/open/jushuitan/otherinout/upload",
  "effect": "EXECUTE",
  "method": "POST",
  "idCheck": true,
  "request": [
    {
      "field": "is_confirm",
      "label": "是否确认单据",
      "type": "string",
      "value": "_function IF({F_POKM_JSTSTOCKNUMBER} = 10816570 , 1 , 0 )"
    },
    {
      "field": "excute_confirming",
      "label": "是否审核单据",
      "type": "string",
      "value": "false"
    },
    {
      "field": "wms_co_id",
      "label": "仓库编号",
      "type": "int",
      "value": "{F_POKM_JSTSTOCKNUMBER}"
    },
    {
      "field": "type",
      "label": "出入库类型",
      "type": "string",
      "value": "out"
    },
    {
      "field": "external_id",
      "label": "外部单号",
      "type": "string",
      "value":"Z{FBillNo}{F_POKM_JSTSTOCKNUMBER}{F_POKM_JSTSTOCKNUMBER2}"
    },
    {
      ...
    }
  ],
  ...
}

配置细节与实现

API 接口路径与请求方法：
- api字段指定了目标平台聚水潭的API路径为/open/jushuitan/otherinout/upload。
- method字段指定了HTTP请求方法为POST。
字段映射与转换：
- is_confirm字段通过自定义函数判断仓库编号是否为特定值，来决定是否确认单据。
- excute_confirming字段直接设置为"false"，表示不自动审核单据。
- wms_co_id字段直接映射金蝶系统中的仓库编号 {F_POKM_JSTSTOCKNUMBER}。
- type字段固定为"out"，表示出库类型。
- external_id字段组合了多个源字段生成唯一外部单号：Z{FBillNo}{F_POKM_JSTSTOCKNUMBER}{F_POKM_JSTSTOCKNUMBER2}。
备注与物流信息：
- remark字段包含了推送来源和单号信息，便于追踪。
- 物流相关字段如lc_id, l_id, 和logistics_company等可以根据实际需求进行填充或留空。

嵌套数组处理：

对于复杂结构的数据，如商品明细，通过嵌套数组实现。每个商品明细项包括商品编码和入库数量：

{
...
{
 “field”: “items”,
 “label”: “items”,
 “type”: “array”,
 “value”: “list”,
 “children”: [
   {“field”: “sku_id”, “label”: “商品编码”, “type”: “string”, “value”: “{{list.FMaterialIDSETY_FNumber}}”},
   {“field”: “qty”, “label”: “入库数量”, “type”: “string”, “value”: “{{list.FQtySETY}}”}
 ]
}
...
}

操作配置：

在操作部分，我们定义了如何合并多个源记录到一个目标记录中。具体配置如下：

{
...
”operation“: {
 ”method“: ”merge“,
 ”field“: ”FBillNo,F_POKM_JSTSTOCKNUMBER,F_POKM_JSTSTOCKNUMBER2“,
 ”bodyName“: ”list“,
 ”header“: [”FBillNo“, ”F_POKM_JSTSTOCKNUMBER“, ”F_POKM_JSTSTOCKNUMBER2“],
 ”body“: [”FMaterialIDSETY_FNumber“, ”FQtySETY“],
 ”bodySum“: [”FQtySETY“]
}
...
}

此配置确保将同一订单下的多个子项合并处理，并计算总数量。

通过以上详细的元数据配置，我们成功实现了从金蝶系统到聚水潭系统的数据ETL转换，并通过API接口顺利上传。这不仅提升了数据处理效率，还确保了数据的一致性和准确性。电商OMS与ERP系统接口开发配置

版权声明

该文章《轻易云集成案例：数据转换与上传到聚水潭API》为原创内容，版权归 广东轻亿云软件科技有限公司 所有。未经本公司书面授权，严禁转载、引用、复制或建立镜像等行为。若需转载或引用本文内容，请联系本公司获取授权，并在显著位置注明作者姓名、文章出处（包括原文链接）等信息。