管理工作簿与版本

工作簿用于保存 SQL 编辑器中的内容和版本。创建或保存工作簿不会运行 SQL；需要运行时，请把版本中的 SQL 发送到 SQL 运行接口。

创建工作簿

curl -X POST "$PRODUCT_API_BASE_URL/workbook/create" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "<WORKBOOK_NAME>"}'

{
  "code": 200,
  "data": {
    "workbook_id": "<WORKBOOK_ID>",
    "name": "<WORKBOOK_NAME>"
  }
}

保存 workbook_id。工作簿名称用于显示和查找，但后续详情、更新和删除都使用 ID。

创建并保存版本

创建版本时提交工作簿 ID 和 SQL 内容：

curl -X POST "$PRODUCT_API_BASE_URL/workbook/version/create" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "<WORKBOOK_ID>",
    "sql_content": "SELECT 1 AS n"
  }'

成功响应返回版本 ID、版本标识和状态：

{
  "code": 200,
  "data": {
    "id": "<VERSION_ID>",
    "version": "<VERSION>",
    "status": "<STATUS>"
  }
}

在草稿阶段使用 POST /workbook/version/update 更新内容；需要保存当前版本时，调用 POST /workbook/version/save。两者都需要 workbook_id 和 version_id，更新还需要 sql_content。

读取工作簿

方法与路径

关键输入

返回内容

POST /workbook/list

搜索、页大小和 page_token

total、result[] 和下一页 Token

POST /workbook/version/list

workbook_id、分页字段

版本列表和下一页 Token

POST /workbook/detail

workbook_id、version_id

SQL 内容和创建、更新时间

POST /workbook/update

workbook_id、name

更新工作簿名称

POST /workbook/delete

workbook_id

删除工作簿

覆盖版本前先读取最新内容。Product API 没有把工作簿保存成功定义为 SQL 语义正确；需要验证时，在明确的数据库上下文中运行 SQL。

常见问题

现象

先检查

下一步

找不到工作簿

工作区 ID、分页 Token 和搜索条件

清除搜索条件并重新列出工作簿。

详情为空或版本不匹配

workbook_id 和 version_id

先列出版本，再使用同一工作簿下的版本 ID。

保存后查询结果没有变化

是否实际调用了 SQL 运行接口

将版本 SQL 发送到 /query/execute；保存本身不会运行 SQL。

协作内容被覆盖

更新前读取的版本是否为最新

重新读取详情并合并内容后再保存。

下一步

最后更新于