案例分享：样品销售订单同步简道云

在复杂的业务环境中，通过有效的数据集成实现系统间的信息互通是各企业数字化转型的重要一环。本文将深入探讨如何通过轻易云数据集成平台，将金蝶云星空的样品销售订单高效、准确地同步至简道云。这一过程涉及API接口调用、数据转换和异常处理等多个技术要点。

金蝶云星空与简道云的对接挑战

作为企业资源管理系统，金蝶云星空承载了大量核心业务数据，而这些数据需要及时更新到以工作流为核心的平台——简道云，以确保业务流程无缝进行。然而，不同系统之间的数据格式差异、接口调用限流问题以及大批量数据写入性能瓶颈，都给这一集成任务带来了诸多挑战。

方案概述

为解决上述问题，我们采用了以下策略：

1. 定时抓取与可靠同步：通过executeBillQuery API定时从金蝶云星空获取最新的样品销售订单信息，并利用自定义逻辑处理分页和限流。
2. 高效批量写入：使用简道云提供的数据创建API（/api/v2/app/{app_id}/entry/{entry_id}/data_create）实现大量数据快速写入，同时配合告警监控机制保障任务执行可靠性。
3. 实时监控与质量检测：配置集中监控和告警系统，即时跟踪每个集成操作的状态，并通过异常重试机制提高整个流程稳健性。
4. 灵活的数据转换：根据具体业务需求，对不同格式的数据进行自定义映射与转换，使其符合目标系统要求，提高兼容性和一致性。

接下来，我们将详细介绍各个关键步骤及其具体实现方式。

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

在数据集成过程中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的executeBillQuery接口，获取并加工样品销售订单数据。

接口配置与请求参数

首先，我们需要配置元数据，以便正确调用金蝶云星空的API接口。以下是关键的元数据配置：

{
  "api": "executeBillQuery",
  "effect": "QUERY",
  "method": "POST",
  "number": "FBillNo",
  "id": "FSaleOrderEntry_FEntryID",
  "name": "FBillNo",
  "idCheck": true,
  "request": [
    {"field":"FSaleOrderEntry_FEntryID","label":"FSaleOrderEntry_FEntryID","type":"string","describe":"FSaleOrderEntry_FEntryID","value":"FSaleOrderEntry_FEntryID"},
    {"field":"FID","label":"实体主键","type":"string","describe":"FID","value":"FID"},
    {"field":"FBillNo","label":"销售单号","type":"string","describe":"单据编号","value":"FBillNo"},
    {"field":"FDocumentStatus","label":"单据状态","type":"string","describe":"单据状态","value":"FDocumentStatus"},
    {"field":"FSaleOrgId_FNumber","label":"销售组织","type":"string","describe":"销售组织","value":"FSaleOrgId.FNumber"},
    {"field":"FDate","label":"日期","type":"string","describe":"日期","value":"FDate"},
    {"field":"FCustId_FNumber","label":"客户","type":"string","describe":"客户","value":"FCustId.FNumber"},
    {"field":...}
  ],
  "otherRequest": [
    {"field":...}
  ],
  "autoFillResponse": true
}

请求参数详解

1. 基本字段：

   • FSaleOrderEntry_FEntryID：销售订单分录ID，用于唯一标识每条记录。
   • FID：实体主键。
   • FBillNo：销售单号，用于标识具体的销售订单。
   • FDocumentStatus：单据状态，表示订单的当前处理状态。
   • FSaleOrgId_FNumber：销售组织编号，标识订单所属的销售组织。
   • FDate：订单日期。

2. 其他字段：

   • 包括客户信息、收货地址、物料信息、金额等，这些字段在实际业务处理中可能会用到。

3. 分页参数：

   • Limit：最大行数，用于控制每次查询返回的数据量。
   • StartRow：开始行索引，用于分页查询。
   • TopRowCount：返回总行数，用于统计查询结果总数。

4. 过滤条件：

   • FilterString：用于指定查询条件，例如根据创建日期、销售组织编号和单据类型进行过滤。

5. 业务对象表单Id：

   • FormId：必须填写金蝶的表单ID，如样品销售订单对应的是SAL_SaleOrder。

调用API并处理响应

在配置好请求参数后，通过轻易云平台发起POST请求调用金蝶云星空的API接口：

{
  "FormId": "SAL_SaleOrder",
  "FieldKeys": ["FBillNo", "FDate", ...],
  "FilterString": "FCreateDate>='2023-01-01' and FSaleOrgId.FNumber = '103' and FBillTypeID.FName = '样品单-适用业务' and FDocumentStatus='B'",
  ...
}

响应结果将包含符合条件的样品销售订单数据。我们可以通过轻易云平台对这些数据进行进一步清洗和转换，以满足下游系统（如简道云）的需求。

数据清洗与转换

在获取到原始数据后，需要对其进行清洗和转换。例如，将日期格式统一为标准格式，将金额字段转换为浮点数等。这些操作可以通过轻易云平台提供的数据处理工具来实现。

{
  // 清洗后的数据示例
  {
    "FBillNo": "SO12345",
    "FDate": "2023-01-01T00:00:00Z",
    ...
  }
}

通过上述步骤，我们成功实现了从金蝶云星空获取样品销售订单数据，并对其进行必要的清洗和转换，为后续的数据写入和业务处理打下了坚实基础。

样品销售订单同步简道云的ETL转换与写入

在数据集成过程中，第二步是将已经集成的源平台数据进行ETL转换，并转为目标平台简道云API接口所能够接收的格式，最终写入目标平台。本文将详细探讨如何利用轻易云数据集成平台配置元数据，实现样品销售订单同步到简道云。

API接口配置

首先，我们需要明确简道云API接口的配置。根据元数据配置，我们使用POST方法，通过/api/v2/app/{app_id}/entry/{entry_id}/data_create接口来创建数据。以下是具体的请求字段和参数：

{
  "api": "/api/v2/app/{app_id}/entry/{entry_id}/data_create",
  "effect": "EXECUTE",
  "method": "POST",
  "idCheck": true,
  "request": [
    {"field":"_widget_1683766778462","label":"销售单号","type":"string","value":"{FBillNo}","parser":{"name":"ConvertObjectParser","params":"value"}},
    {"field":"_widget_1683766778471","label":"客户编码","type":"string","value":"{FCustId_FNumber}","parser":{"name":"ConvertObjectParser","params":"value"}},
    {"field":"_widget_1683769057773","label":"单据状态","type":"string","value":"{FDocumentStatus}","parser":{"name":"ConvertObjectParser","params":"value"}},
    {"field":"_widget_1683766778472","label":"收货方","type":"string","value":"{FReceiveId}","parser":{"name":"ConvertObjectParser","params":"value"}},
    {"field":"_widget_1683769057766","label":"日期","type":"datetime","value":"{FDate}","parser":{"name":"ConvertObjectParser","params":"value"}},
    {"field":"_widget_1683766778474","label":"结算币别","type":"string","value":"{FSettleCurrId}","parser":{"name":"ConvertObjectParser","params":"value"}},
    {"field":"_widget_1683769057762","label":"销售员","type":"string","value":"{FSalerId}","parser":{"name":"ConvertObjectParser","params":"value"}},
    {"field":"_widget_1683766778476","label":"价税合计", "type": "string", "value": "{FBillAllAmount}", "parser": {"name": "ConvertObjectParser", "params": "value"}}
  ],
  ...
}

数据转换

在ETL过程中，数据转换是关键步骤之一。我们需要将源平台的数据字段映射到目标平台所需的字段，并进行必要的格式转换。例如：

• FBillNo（源平台） -> _widget_1683766778462（目标平台）
• FCustId_FNumber（源平台） -> _widget_1683766778471（目标平台）

每个字段都通过ConvertObjectParser进行解析和转换，确保数据格式符合目标平台要求。

明细处理

对于复杂结构的数据，如包含明细项的订单，需要特别处理。以下是明细项的配置示例：

{
  "field": "_widget_1683766778463",
  "label": "明细",
  "type": "object",
  "children": [
    {
      "field": "value",
      "label": "值",
      "type": "array",
      "children": [
        {"field": "_widget_1683766778465", "label": "物料编号", "type": "string", "value": "{FMaterialId_Fnumber}", "parser":{"name": "ConvertObjectParser", "params": ["value"]}},
        {"field": "_widget_1683766778466", "label": "物料名称",  ...
      ]
    }
  ]
}

在这里，我们定义了一个名为“明细”的对象，其下包含多个子字段，如“物料编号”、“物料名称”等。这些子字段同样通过ConvertObjectParser进行解析和转换。

特殊字段处理

某些特殊字段可能需要额外处理，例如日期时间类型、布尔类型等。在元数据配置中，我们可以通过指定解析器来处理这些特殊类型。例如：

{"field": "_widget_1683769057766", 
"label": 
"日期", 
"type":
"datetime", 
"value":
"{FDate}", 
"parser":
{"name":
"ConvertObjectParser", 
"params":
"value"}}

这里，“日期”字段被定义为datetime类型，通过解析器将源数据中的日期字符串转换为目标平台所需的格式。

最终写入

完成所有字段的映射和转换后，通过API接口将数据写入简道云。请求体将包含所有经过转换后的字段和值，如下所示：

{
  "_widget_1683766778462": "{FBillNo}",
  "_widget_1683766778471": "{FCustId_FNumber}",
  "_widget_1683769057773": "{FDocumentStatus}",
  "_widget_1683766778472": "{FReceiveId}",
  ...
}

通过发送这个请求体到简道云API接口，即可完成样品销售订单的数据同步。

总结

本文详细介绍了如何利用轻易云数据集成平台，将源平台的数据进行ETL转换，并通过简道云API接口实现数据写入。关键步骤包括API接口配置、数据字段映射与转换、明细项处理以及特殊字段处理。通过这些技术手段，可以高效地实现不同系统间的数据无缝对接。