⚡

Coda文档管理API工具 coda

Coda文档管理API工具是一个专门用于通过REST API v1自动化管理Coda文档的Python技能。支持文档的创建、更新、删除、表格数据操作、页面管理、自动化触发等功能。关键词：Coda API，文档管理，自动化，表格操作，Python CLI，REST API，低代码平台，数据同步，批量操作，API集成。

低代码开发 0 次安装 0 次浏览 更新于 2/24/2026

name: coda description: 通过REST API v1进行通用Coda文档管理。支持列出/创建/更新/删除文档、管理表格/行/页面、触发自动化操作以及探索文档结构。需要设置CODA_API_TOKEN环境变量。删除操作需要明确确认；发布和权限变更需要明确的用户意图。

Coda API 技能

通过Coda REST API v1与文档、表格、行、页面和自动化功能进行交互。

使用场景

当用户想要执行以下操作时使用此技能：

  • 列出、搜索、创建或删除Coda文档
  • 从表格读取或写入数据（插入、更新插入、更新、删除行）
  • 探索文档结构（页面、表格、列、公式、控件）
  • 触发自动化操作（点击按钮）
  • 导出文档内容或分析数据

不适用场景

  • 请勿用于与API无关的通用文档编辑建议
  • 请勿用于Pack开发（此技能涵盖文档管理，而非Pack创建）
  • 请勿用于需要文档制作者权限的操作，除非确认用户拥有相应权限

前提条件

  1. API令牌：设置环境变量CODA_API_TOKEN，包含您的Coda API令牌
  2. Python 3.7+ 并安装requests库
  3. 权限：某些操作（创建文档、更新文档标题、创建页面）需要在工作区中拥有文档制作者角色

CLI工具使用

技能包含位于scripts/coda_cli.py的Python CLI工具：

# 设置
export CODA_API_TOKEN="your_token_here"

# 列出文档
python scripts/coda_cli.py docs list --query "项目"

# 获取文档信息
python scripts/coda_cli.py docs get <文档ID>

# 创建文档
python scripts/coda_cli.py docs create --title "我的新文档"

# 列出文档中的表格
python scripts/coda_cli.py tables list <文档ID>

# 列出表格中的行
python scripts/coda_cli.py rows list <文档ID> <表格ID>

# 插入行
python scripts/coda_cli.py rows insert <文档ID> <表格ID> --data '{"名称": "任务1", "状态": "已完成"}'

# 更新行
python scripts/coda_cli.py rows update <文档ID> <表格ID> <行ID> --data '{"状态": "进行中"}'

# 删除行（需要确认）
python scripts/coda_cli.py rows delete <文档ID> <表格ID> <行ID>

# 列出页面
python scripts/coda_cli.py pages list <文档ID>

# 触发自动化（点击按钮）
python scripts/coda_cli.py automations trigger <文档ID> <按钮ID>

# 强制删除无需确认（谨慎使用）
python scripts/coda_cli.py docs delete <文档ID> --force

工作流程指南

1. 文档ID提取

Coda文档ID可从浏览器URL中提取：

  • URL：https://coda.io/d/_dAbCDeFGH/项目跟踪器
  • 文档ID：AbCDeFGH（移除_d前缀）

CLI工具接受完整URL和原始ID。

2. 速率限制处理

API有严格的速率限制：

  • 读取：每6秒100个请求
  • 写入（POST/PUT/PATCH）：每6秒10个请求
  • 写入文档内容：每10秒5个请求
  • 列出文档：每6秒4个请求

CLI工具对429响应自动实施指数退避。

3. 异步操作

写入操作返回HTTP 202并附带requestId。CLI工具可使用--wait标志可选地轮询完成状态。

4. 安全防护

删除操作（行、文档、页面、文件夹）：

  • 在交互模式下始终需要明确的用户确认
  • 仅在自动化/脚本中使用--force标志
  • 显示将要删除内容的预览

发布（docs publish）：

  • 需要明确的--confirm-publish标志
  • 不能与--force结合使用

权限（acl命令）：

  • 任何变更都需要明确的--confirm-permissions标志
  • 读取操作（列出权限）始终允许

自动化触发器：

  • 无需特殊标志但会记录日志
  • 用户应知晓自动化可能触发通知或外部操作

5. 分页

列表命令支持：

  • --limit：最大结果数（默认25，各端点最大值不同）
  • --page-token：用于获取后续页面
  • CLI使用--all标志自动跟随页面

常见模式

批量行操作

# 从JSON文件插入多行
python scripts/coda_cli.py rows insert-batch <文档ID> <表格ID> --file rows.json

# 使用关键列更新插入行（存在则更新，不存在则插入）
python scripts/coda_cli.py rows upsert <文档ID> <表格ID> --file rows.json --keys "邮箱"

文档间同步

# 从源导出
python scripts/coda_cli.py rows list <源文档> <表格ID> --format json > export.json

# 导入到目标
python scripts/coda_cli.py rows insert-batch <目标文档> <表格ID> --file export.json

探索结构

# 获取完整文档结构
python scripts/coda_cli.py docs structure <文档ID>

# 列出所有公式
python scripts/coda_cli.py formulas list <文档ID>

# 列出所有控件
python scripts/coda_cli.py controls list <文档ID>

错误处理

常见HTTP状态码：

  • 400：错误请求（无效参数）
  • 401：无效/过期的API令牌
  • 403：权限不足（需要文档制作者角色）
  • 404：资源未找到
  • 429：速率限制（实施退避）
  • 202：已接受但尚未处理（异步操作）

安全考虑

  1. 令牌存储：切勿将CODA_API_TOKEN提交到版本控制
  2. 令牌范围：令牌对用户可访问的所有文档拥有完全访问权限
  3. 工作区限制：创建文档需要在目标工作区中拥有文档制作者角色
  4. 数据暴露：行数据可能包含敏感信息；谨慎处理导出

示例

列出和筛选文档

python scripts/coda_cli.py docs list --is-owner --query "项目"

从模板创建文档

python scripts/coda_cli.py docs create --title "第四季度规划" --source-doc "模板文档ID"

更新行状态

python scripts/coda_cli.py rows update AbCDeFGH grid-xyz row-123 \
  --data '{"状态": "已完成", "完成日期": "2024-01-15"}'

删除多行（需要确认）

python scripts/coda_cli.py rows delete-batch AbCDeFGH grid-xyz \
  --filter '{"状态": "已归档"}' \
  --confirm "删除所有已归档的行？"

导出表格到CSV

python scripts/coda_cli.py rows list AbCDeFGH grid-xyz --format csv > export.csv

参考