首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API「Excel-Pro」接口功能介绍

数据鱼API「Excel-Pro」接口功能介绍

原创
作者头像
用户12862874
发布于 2026-11-21 21:27:44
发布于 2026-11-21 21:27:44
70
举报

接口简介

「Excel-Pro」是数据鱼API平台提供的 Excel 处理工具集接口,Base 路径 /api/excel,共 8 个端点。它由两块能力组成:一是 131 个常用 Excel 函数的速查库,覆盖查找引用、逻辑判断、文本处理、日期时间、数学计算、统计汇总、财务、信息与其他九个分类,每个函数带语法、参数说明、示例公式与适用场景;二是 JSON 与 XLSX 双向结构化转换,支持把对象数组导出为可下载的 .xlsx 文件,或把上传的 .xlsx 解析回 JSON。

函数语法基于 Microsoft Excel 官方文档整理,服务为纯 PHP 实现,不依赖数据库,导出与解析均在毫秒级完成。数据鱼API 把该接口设计为无状态服务:上传的文件与导出的临时文件不留存,适合对数据敏感性有要求的内部系统集成。

前端与后端场景都能用到它:后台管理系统可以直接调用导出端点实现「查询结果一键下载 Excel」,数据回导则交给导入端点;函数速查部分适合做办公助手、教学卡片或公式补全提示。

端点总览

方法

路径

说明

鉴权

GET

/api/excel/ping

健康检查,返回版本与时间

需要

GET

/api/excel/stats

数据规模与功能特性统计

需要

GET

/api/excel/categories

函数分类列表及各类数量

需要

GET

/api/excel/list

函数分页列表,支持分类筛选

需要

GET

/api/excel/search

函数关键词全文搜索

需要

GET

/api/excel/detail

单个函数详情,支持 @ 前缀取值

需要

POST

/api/excel/export

JSON 数组转 XLSX 文件下载

需要

POST

/api/excel/import

XLSX 文件解析为 JSON

需要

通用约定

鉴权使用数据鱼API 全站统一的 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011,无效返回 4013。JSON 端点响应为统一三段结构 {code, msg, data},code 为 0 表示成功;缺少参数返回 4001,参数非法或文件解析失败返回 4002,函数未收录返回 4004,导出失败(Zip 权限或系统错误)返回 5000。export 成功时返回二进制文件流而非 JSON。运行环境要求 PHP 8.0 以上并启用 zip 与 simplexml 扩展。

核心端点详解

JSON 转 XLSX export

把对象数组转换为标准 .xlsx 文件供下载,是后台导出功能的后端实现。

参数

类型

必填

默认

说明

data

array

是

—

数据对象数组,每个对象的键作为列

headers

object

否

—

表头映射,如键名到中文列名的对应关系

filename

string

否

export.xlsx

导出文件名

代码语言:javascript
复制
POST /api/excel/export
Content-Type: application/json

{"data": [{"name": "张三", "age": 25}, {"name": "李四", "age": 30}], "headers": {"name": "姓名", "age": "年龄"}, "filename": "users.xlsx"}

导出成功返回 .xlsx 二进制流,客户端以文件下载处理;单次导出建议不超过 5000 行以保证性能。传 headers 后列顺序与命名以映射为准,适合把内部字段名转换为业务列名。

XLSX 转 JSON import

解析上传的 .xlsx 文件并返回结构化数据,支持两种输入方式。

参数

类型

必填

默认

说明

file

file

二选一

—

multipart/form-data 上传的 XLSX 文件

content

string

二选一

—

Base64 编码的文件内容,用于无文件上传的场景

代码语言:javascript
复制
POST /api/excel/import
Content-Type: multipart/form-data

file=@data.xlsx

解析支持单元格文本、数字与共享字符串;当前版本解析 Sheet1,多 Sheet 工作簿请先拆分。文件解析失败返回 4002 并给出原因。服务端不保存上传文件,解析完成即释放。

函数速查 detail

按名称取单个函数的完整档案,速查场景的主力端点。

参数

类型

必填

默认

说明

name

string

是

—

函数名,支持 @ 前缀写法

代码语言:javascript
复制
GET /api/excel/detail?name=VLOOKUP&api_key=YOUR_KEY

实测返回 VLOOKUP 的完整档案:category(查找引用)、syntax(完整语法签名)、params(逐参数说明)、example(如 =VLOOKUP(A2,D:E,2,0))、scene(典型场景描述)与 note(易错点提示,如精确匹配与近似匹配的差别)。函数未收录时返回 4004。

其余三个速查端点配合使用:categories 返回九个分类及各类数量;list 支持分页与分类筛选(实测每页 items 含 name、category、syntax 等完整字段,total 全库 131);search 按关键词做全文匹配(实测搜 SUM 命中 5 条),适合补全提示框。stats 返回函数总数、分类清单与 features 标记(function_lookup、json_to_xlsx、xlsx_to_json)。

数据与限制

  • 函数库规模:131 个函数、9 个分类,各分类数量可通过 categories 获取;语法口径基于 Microsoft Excel 官方文档。
  • 导出建议单次不超过 5000 行;导入当前仅解析 Sheet1。
  • 无状态服务:不存储上传文件与导出临时文件,临时目录需具备写权限。
  • 运行依赖:PHP >= 8.0,zip 与 simplexml 扩展。
  • 无数据库依赖,部署即用;上游不可用类错误(5031/5032)不适用于本接口。

典型使用场景

  • 后台管理系统的报表导出:查询结果数组直接交 export 生成下载文件。
  • 数据回导与批量初始化:运营在 Excel 里整理数据,import 解析后入库。
  • 办公助手与教学工具:list、search、detail 组成函数速查三件套,做公式提示卡片。

注意事项

  • API.md 的函数速查端点清单列出六个 GET 端点,实测全量端点列表以 stats 返回的 endpoints 字段为准(ping、stats、categories、list、search、detail、export、import 共 8 个);文档正文对 ping/stats/categories/list/search/detail 的参数描述较简,分页与筛选参数以实测为准。
  • detail 支持的 @ 前缀写法用于取特定命名空间的函数,普通函数直接传名称即可;文档未给出 @ 语法的具体示例,遇到未收录报错(4004)时先用 search 确认名称。
  • import 仅解析 Sheet1,且共享字符串与内联文本的处理范围有限,复杂格式(合并单元格、公式缓存值)的解析结果需自行验证后再入库。
  • 导出大文件时 5000 行为性能建议值而非硬限制,超量导出应改用分页多次调用。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • JSON 转 XLSX export
    • XLSX 转 JSON import
    • 函数速查 detail
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档