吉客云数据集成到金蝶云星空案例分享：吉客云盘亏单-其他入库-负数

在实际项目中，企业常需要高效、可靠地将分散于各个系统中的数据进行对接和集成。本文将通过一个具体的技术案例——“吉客云盘亏单-其他入库-负数”详细解析如何使用轻易云平台实现吉客云与金蝶云星空之间的数据对接。

背景与需求分析

在该项目中，我们主要任务是将吉客云中的盘亏单数据，通过API接口erp.storage.goodsdocout.v2定时抓取，并批量写入至金蝶云星空系统中的库存模块，对应API为batchSave。为了确保整个流程的稳定性和一致性，需要处理以下几个关键问题：

1. 如何调用和管理两个不同系统的API接口：包括分页处理、限流机制以及错误重试。
2. 数据格式差异的转换：吉客云和金蝶云星空可能采用不同的数据结构，需要在传输过程中进行格式转换。
3. 大规模数据的快速写入能力：保障大量数据能够及时准确地写入到目标系统。
4. 实时监控与异常告警机制：实时跟踪每一次操作，确保第一时间捕捉并处理潜在的问题。

技术要点解析

一、 API调用及分页处理

首先，我们根据业务需求，每隔一定时间从吉客云中抓取最新一批次的盘亏单数据。在这个过程中，为了避免因请求频率过高导致服务不可用或被限流，我们设计了一套基于动态窗口大小调整算法的自动化分页策略，并结合错误重试机制，保证即便网络波动或者临时故障，也能最大程度上完成完整的数据获取。

def fetch_data_from_jike_cloud(api_endpoint, page_size):
    current_page = 1
    while True:
        response = call_api(api_endpoint, params={'page': current_page, 'size': page_size})
        if not response or len(response['data']) == 0:
            break
        # 数据逻辑处理...
        current_page += 1 

二、 数据格式转换及自定义映射规则

由于两者间存在较大的数据结构差异，因此我们采用可视化工具来配置自定义映射规则，将输入源（吉客/库存）字段映射至目标（K/3）字段。在此基础上，还引入了特定业务逻辑，比如某些字段需要加权平均值计算等，以适应企业独特需求。

mappings:
  - source_field: "jike_goods_id"

![用友与CRM系统接口开发配置](https://pic.qeasy.cloud/D17.png~tplv-syqr462i7n-qeasy.image)
### 调用吉客云接口获取并加工数据的技术案例

在轻易云数据集成平台中，生命周期的第一步是调用源系统接口获取数据。本文将详细探讨如何通过调用吉客云接口`erp.storage.goodsdocout.v2`来获取盘亏单的相关数据，并进行初步加工。

#### 接口配置与请求参数

首先，我们需要配置API接口的元数据。根据提供的元数据配置，我们可以看到该接口采用POST方法进行数据请求，主要参数如下：

- `pageIndex`：分页页码
- `pageSize`：分页页数，默认值为50
- `goodsDocNo`：出库单号
- `startDate`：创建时间的起始时间，使用占位符`{{LAST_SYNC_TIME|datetime}}`
- `endDate`：创建时间的结束时间，使用占位符`{{CURRENT_TIME|datetime}}`
- `inouttype`：类型，此处固定为203（盘亏出库）
- 其他可选参数如来源单号、仓库编号、供应商编号等

这些参数确保了我们能够精准地获取所需的数据。

#### 数据请求与清洗

在实际操作中，我们需要编写代码来调用该API接口，并处理返回的数据。以下是一个示例代码片段：

```python
import requests
import datetime

# 定义请求URL和头部信息
url = "https://api.jikecloud.com/erp.storage.goodsdocout.v2"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

# 获取当前时间和上次同步时间
current_time = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
last_sync_time = (datetime.datetime.now() - datetime.timedelta(days=1)).strftime('%Y-%m-%d %H:%M:%S')

# 定义请求体
payload = {
    "pageIndex": "1",
    "pageSize": "50",
    "startDate": last_sync_time,
    "endDate": current_time,
    "inouttype": "203"
}

# 发送POST请求
response = requests.post(url, headers=headers, json=payload)
data = response.json()

# 打印返回的数据
print(data)

在这个示例中，我们首先定义了请求URL和头部信息，然后构建了请求体，其中包含分页信息、起始和结束时间以及出库类型。接着，通过发送POST请求获取数据，并将返回的数据打印出来。

数据转换与写入

获取到原始数据后，我们需要对其进行清洗和转换，以便后续处理。在元数据配置中，我们可以看到有一个关键字段goodsDocDetailList.quantity，其值小于0时表示负数盘亏单。我们可以利用这一条件对数据进行过滤和处理。

以下是一个示例代码片段，用于过滤并处理返回的数据：

# 过滤负数盘亏单
filtered_data = [item for item in data['data'] if any(detail['quantity'] < 0 for detail in item['goodsDocDetailList'])]

# 转换并写入目标系统（示例）
for item in filtered_data:
    transformed_item = {
        "goodsDocNo": item["goodsdocNo"],
        "inOutDate": item["inOutDate"],
        "warehouseCode": item["warehouseCode"],
        # 添加其他需要的字段转换逻辑
    }

    # 假设目标系统有一个API用于接收转换后的数据
    target_url = "https://target-system.com/api/receive-data"
    response = requests.post(target_url, headers=headers, json=transformed_item)

    if response.status_code == 200:
        print(f"Data for goodsDocNo {item['goodsdocNo']} successfully written to target system.")
    else:
        print(f"Failed to write data for goodsDocNo {item['goodsdocNo']} to target system.")

在这个示例中，我们首先过滤出所有数量小于0的盘亏单，然后对每个符合条件的记录进行转换，并通过POST请求将其写入目标系统。

自动化与异常处理

为了确保数据集成过程的稳定性和可靠性，我们还需要设置自动化任务和异常处理机制。在元数据配置中，有一个自动补救机制（omissionRemedy），用于定期检查并补救遗漏的数据。例如，每天凌晨2点执行一次任务，确保没有遗漏的数据。

"omissionRemedy": {
    "crontab": "1 2 * * *",
    "takeOverRequest": [
        {
            "field": "startDate",
            "value": "_function FROM_UNIXTIME( unix_timestamp() -259200 , '%Y-%m-%d %H:%i:%s' )",
            "type": "string",
            "label": "接管字段"
        }
    ]
}

通过这种方式，可以有效地避免由于网络波动或其他原因导致的数据遗漏问题。

综上所述，通过合理配置API接口元数据，并结合轻易云平台提供的自动化工具，我们可以高效地实现吉客云盘亏单数据的获取、清洗、转换与写入，从而提升业务透明度和效率。

使用轻易云数据集成平台实现吉客云盘亏单数据写入金蝶云星空API接口

在数据集成的生命周期中，ETL（提取、转换、加载）是关键步骤之一。本文将深入探讨如何使用轻易云数据集成平台，将吉客云盘亏单的数据转换为金蝶云星空API接口所能接收的格式，并最终写入目标平台。

数据请求与清洗

首先，我们需要从源系统（吉客云）提取盘亏单数据。这一步骤包括了对原始数据的清洗和预处理，确保数据的完整性和一致性。假设我们已经完成了这部分工作，现在进入数据转换与写入阶段。

数据转换与写入

在轻易云平台上，我们可以配置元数据来定义如何将源数据转换为目标格式。以下是具体的元数据配置示例：

{
  "api": "batchSave",
  "effect": "EXECUTE",
  "method": "POST",
  "idCheck": true,
  "operation": {
    "rowsKey": "array",
    "rows": 1,
    "method": "merge",
    "field": "goodsDocDetailList_ownerName,goodsdocNo",
    "bodyName": "items",
    "header": ["goodsdocNo", "inOutDate", "goodsDocDetailList_ownerName"],
    "body": ["goodsDocDetailList_goodsNo", "goodsDocDetailList_quantity", "warehouseCode"]
  },
  "request": [
    {"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号"},
    {"field":"FJKYNo","label":"吉客云单号","type":"string","value":"{goodsdocNo}"},
    {"field":"FBillTypeID","label":"单据类型","type":"string","describe":"单据类型","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"QTRKD98_SYS"},
    {"field":"FStockOrgId","label":"库存组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{goodsDocDetailList_ownerName}","mapping":{"direction":"positive","target":"6441f0214af70a2f240adb22"}},
    {"field":"FStockDirect","label":"库存方向","type":"string","describe":"下拉列表","value":"GENERAL"},
    {"field":"FDate","label":"日期","type":"string","describe":"日期","value":"{inOutDate}"},
    {"field":"FDEPTID","label":"部门","type":"string","describe":"基础资料","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"BM000029"},
    {"field":"FOwnerTypeIdHead","label":"货主类型","type":"string","describe":"多类别基础资料列表","value":"BD_OwnerOrg"},
    {"field":"FOwnerIdHead","label":"货主","type":"","describe":"","parser":{"name":"","params":""},"value":"","mapping":{"target":"","direction":""}},
    {"field":"",
     ...
  ],
  ...
}

元数据解析与应用

1. API接口配置："api"字段指定了调用的API接口名称，这里使用的是batchSave。"method"字段指定HTTP方法为POST。

2. 操作配置："operation"字段定义了如何处理请求体中的数组和字段映射关系。"rowsKey"表示数组的键名，"bodyName"表示请求体中数组部分的名称。

3. 请求字段映射：

   • "FBillNo"：映射到源数据中的单据编号。
   • "FJKYNo"：映射到吉客云单号。
   • "FBillTypeID"：固定值为QTRKD98_SYS。
   • "FStockOrgId"：通过解析器将库存组织名称转换为金蝶系统识别的编码。
   • "FDate"：映射到盘亏单日期。
   • "FOwnerIdHead"：通过解析器将货主名称转换为金蝶系统识别的编码。

4. 明细信息处理：

   • FMATERIALID: 映射物料编码。
   • FSTOCKID: 映射收货仓库。
   • FQty: 实收数量乘以-1，表示负数入库。

5. 其他请求参数：

   • "FormId"：业务对象表单ID，固定值为STK_MISCELLANEOUS。
   • "IsVerifyBaseDataField"：设置为true以验证基础资料有效性。
   • "Operation"：执行操作为保存（Save）。
   • "IsAutoSubmitAndAudit"：设置为自动提交并审核。

实际案例应用

假设我们有如下源数据：

{
  "goodsdocNo": "JKY20231001",
  "inOutDate": "2023-10-01",
  ...
}

通过上述元数据配置，轻易云平台会自动将这些源数据转换为符合金蝶云星空API要求的格式，并通过HTTP POST请求发送到目标系统，实现无缝的数据集成。

总结

通过详细配置元数据，我们能够精确控制从吉客云盘亏单到金蝶云星空API接口的数据转换过程。这不仅提高了集成效率，还确保了数据的一致性和准确性。在实际应用中，依据具体业务需求调整元数据配置，可以灵活应对各种复杂的数据集成场景。