金蝶云 K3Cloud

概述

金蝶云ERP集成处理器，支持与金蝶K3 Cloud系统的无缝对接。通过标准HTTP API调用，可以实现ERP数据的查询、录入、文件上传下载等业务操作。

功能特性

多场景支持：支持数据操作、文件上传下载等4种业务场景

智能请求识别：根据请求参数自动判断处理类型

分块传输：支持大文件的分块上传和下载

数据格式转换：自动处理JSON数据序列化

认证集成：支持金蝶云的OAuth认证机制

容错处理：完善的异常捕获和错误恢复

支持的业务场景

1. FormId数据请求

当请求体包含formid参数时，将data字段转换为JSON字符串格式。

2. 文件上传

请求路径包含"upload"时，支持文件上传，自动处理分块传输。

3. 文件下载

请求路径包含"download"时，支持文件下载，自动合并多块文件。

4. 普通数据请求

其他情况下的标准API调用。

配置参数

HttpAction 基础参数

endpoint：API端点，支持相对路径和完整URL

httpMethod：HTTP方法（GET/POST/PUT/DELETE）

contentType：内容类型

header：请求头

query：查询参数

path：路径参数

body：请求体（JSON格式）

K3Cloud特定参数

formid：表单ID（触发FormId请求模式）

data：业务数据（JSON对象）

SendByte：文件内容（Base64编码，用于文件操作）

使用方法

1. 数据查询请求

{
  "endpoint": "/api/query",
  "httpMethod": "POST",
  "body": {
    "formid": "BD_Customer",
    "data": {
      "FilterString": "FName like '%测试%'",
      "OrderString": "FCreateDate DESC"
    }
  }
}

2. 数据录入请求

{
  "endpoint": "/api/save",
  "httpMethod": "POST",
  "body": {
    "formid": "BD_Customer",
    "data": {
      "FName": "新客户",
      "FNumber": "CUST001",
      "FCreateDate": "2024-01-01"
    }
  }
}

3. 文件上传

{
  "endpoint": "/api/upload",
  "httpMethod": "POST",
  "body": {
    "data": {
      "SendByte": "https://example.com/file.pdf",
      "FileName": "合同.pdf"
    }
  }
}

4. 文件下载

{
  "endpoint": "/api/download",
  "httpMethod": "POST",
  "body": {
    "data": {
      "FileId": "file_123456"
    }
  }
}

执行逻辑

请求类型识别

系统根据以下规则自动判断请求类型：

FormId请求：body.data.formid 不为空

文件上传：endpoint 包含 "upload"

文件下载：endpoint 包含 "download"

普通请求：其他情况

FormId请求处理

提取data字段内容

转换为JSON字符串

重新构造请求体

文件上传处理

下载源文件（最大100MB）

小文件（≤4MB）：直接Base64编码上传

大文件（>4MB）：分块Base64编码上传

自动获取FileId进行续传

文件下载处理

发送下载请求获取第一块

检查是否为多块文件

自动下载所有分块并合并

生成临时访问URL

普通请求处理

标准HTTP请求处理

支持所有HTTP方法

自动参数映射

文件传输特性

分块上传

块大小：4MB

编码：Base64

续传：支持断点续传

校验：MD5完整性校验

分块下载

自动合并：多块文件自动合并

内存优化：流式处理避免内存溢出

进度跟踪：分块下载进度监控

最佳实践

1. 请求配置

使用正确的formid标识业务对象

设置合理的超时时间

选择合适的HTTP方法

2. 数据处理

验证必填字段

使用合适的数据类型

处理特殊字符编码

3. 文件操作

检查文件大小限制

验证文件格式

监控传输进度

4. 错误处理

实现重试机制

记录详细错误信息

提供降级处理方案

调试和监控

请求日志

API调用详情记录

参数和响应内容

执行时间统计

性能指标

请求成功率

平均响应时间

文件传输速率

常见问题

Q: 如何处理金蝶云的业务对象？

A: 使用正确的formid参数标识业务对象，如"BD_Customer"表示客户对象。参考金蝶云API文档获取准确的formid。

Q: 文件上传大小有限制吗？

A: 支持最大100MB的文件。超过4MB的文件会自动分块上传。建议根据业务需求控制文件大小。

Q: 如何处理多租户环境？

A: 通过endpoint参数指定不同的服务器地址，或在认证配置中设置租户信息。系统会自动处理多租户的权限隔离。

Q: 支持哪些数据格式？

A: 主要使用JSON格式。文件操作使用Base64编码。系统会自动处理数据类型转换。

Q: 如何监控API调用状态？

A: 系统提供详细的执行日志，包括请求参数、响应状态、错误信息等。可以通过日志分析工具进行监控和告警。

Q: 如何处理批量数据操作？

A: 对于批量操作，可以使用循环节点逐条处理，或构造包含多个数据对象的请求体。注意API的批量处理限制。

概述#

功能特性#

支持的业务场景#

1. FormId数据请求#

2. 文件上传#

3. 文件下载#

4. 普通数据请求#

配置参数#

HttpAction 基础参数#

K3Cloud特定参数#

使用方法#

1. 数据查询请求#

2. 数据录入请求#

3. 文件上传#

4. 文件下载#

执行逻辑#

请求类型识别#

FormId请求处理#

文件上传处理#

文件下载处理#

普通请求处理#

文件传输特性#

分块上传#

分块下载#

最佳实践#

1. 请求配置#

2. 数据处理#

3. 文件操作#

4. 错误处理#

调试和监控#

请求日志#

性能指标#

常见问题#

Q: 如何处理金蝶云的业务对象？#

Q: 文件上传大小有限制吗？#

Q: 如何处理多租户环境？#

Q: 支持哪些数据格式？#

Q: 如何监控API调用状态？#

Q: 如何处理批量数据操作？#

概述