EtherCalc API 使用指南：实时协作表格的编程接口详解

EtherCalc API 使用指南：实时协作表格的编程接口详解

前言

EtherCalc 是一个开源的实时协作电子表格工具，其强大的 API 接口允许开发者通过编程方式与表格进行交互。本文将全面解析 EtherCalc 的 RESTful API，帮助开发者掌握如何创建、修改和导出表格数据。

API 基础

EtherCalc API 遵循 REST 设计原则，支持多种数据格式的交互。在使用 API 时，需要注意以下要点：

1. 所有 API 端点均以 /_/ 开头
2. 支持 JSON、CSV、SocialCalc 和 Excel XML 等多种数据格式
3. 使用 PUT 方法时，必须使用 --data-binary 而非 --data 参数

核心 API 功能详解

1. 表格创建

EtherCalc 提供多种创建表格的方式：

1.1 创建空白表格

通过 POST 请求到 /_/ 端点可以创建新表格，可选择指定表格 ID 或让系统自动生成。

curl -X POST http://127.0.0.1:8000/_/

1.2 从不同格式导入创建

支持从多种格式创建表格：

• CSV 格式：

  curl -X POST -H "Content-Type: text/csv" \
       --data-binary @data.csv http://127.0.0.1:8000/_/
  

• SocialCalc 格式：

  curl -X POST -H "Content-Type: text/x-socialcalc" \
       --data-binary @data.sc http://127.0.0.1:8000/_/
  

• Excel XML 格式：

  curl -X POST -H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
       --data-binary @data.xlsx http://127.0.0.1:8000/_/
  

2. 表格内容操作

2.1 获取表格内容

获取指定 ID 表格的内容：

curl http://127.0.0.1:8000/_/test

支持多种格式获取：

• SocialCalc 格式（默认）
• HTML 格式：/_/test.html
• CSV 格式：/_/test.csv
• JSON 格式：/_/test.csv.json
• Excel XML 格式：/_/test.xlsx
• Markdown 格式：/_/test.md

2.2 修改表格内容

支持多种格式覆盖表格内容：

# 使用 CSV 覆盖
curl -X PUT -H "Content-Type: text/csv" \
     --data-binary @newdata.csv http://127.0.0.1:8000/_/test

# 使用 SocialCalc 覆盖
curl -X PUT -H "Content-Type: text/x-socialcalc" \
     --data-binary @newdata.sc http://127.0.0.1:8000/_/test

2.3 执行表格命令

可以通过 API 发送命令来修改表格：

curl -X POST -H "Content-Type: application/json" \
     -d '{"command": "set A1 text Hello"}' http://127.0.0.1:8000/_/test

命令格式可以通过 Web 界面的"审计"选项卡查看。

2.4 追加行数据

向表格末尾追加 CSV 数据：

curl -X POST -H "Content-Type: text/csv" \
     --data-binary @append.csv http://127.0.0.1:8000/_/test

也可指定行号插入：

curl -X POST -H "Content-Type: text/csv" \
     --data-binary @insert.csv http://127.0.0.1:8000/_/test?row=5

3. 单元格操作

3.1 获取所有单元格数据

curl http://127.0.0.1:8000/_/test/cells

3.2 获取特定单元格数据

curl http://127.0.0.1:8000/_/test/cells/A1

4. 表格管理

4.1 删除表格

curl -X DELETE http://127.0.0.1:8000/_/test

4.2 检查表格是否存在

curl http://127.0.0.1:8000/_exists/test

4.3 获取所有表格列表

curl http://127.0.0.1:8000/_rooms

高级功能

多表格操作

EtherCalc 支持将多个表格打包成 Excel 文件：

# 导出
curl http://127.0.0.1:8000/=/multi.xlsx

# 导入
curl -X PUT -H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
     --data-binary @multi.xlsx http://127.0.0.1:8000/=/

最佳实践

1. 批量操作：对于大量数据修改，建议先导出为 SocialCalc 格式，修改后再导入，比单个命令更高效。

2. 错误处理：检查 HTTP 状态码，200 系列表示成功，400 系列表示客户端错误，500 系列表示服务器错误。

3. 性能优化：对于大型表格，使用单元格级 API 而非全表操作可以提高性能。

4. 数据备份：定期导出重要表格数据到本地存储。

结语

EtherCalc 的 API 提供了强大的表格操作能力，使得它不仅能作为协作工具，还能集成到各种自动化流程中。通过合理使用这些 API，开发者可以构建出基于表格的复杂应用系统。