691b8cdd0c
- 核心配置: IDENTITY, USER, SOUL, AGENTS, TOOLS, HEARTBEAT, MEMORY - memory/: 每日总结和临时记录 - skills/: 所有已安装技能 - notes/: 语音配置笔记
1053 lines
29 KiB
Markdown
1053 lines
29 KiB
Markdown
# 智能表格（SmartSheet）工具完整参考文档
|
||
|
||
腾讯文档智能表格（SmartSheet）提供了一套完整的表格操作 API，支持对工作表、视图、字段、记录进行增删改查操作。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [概念说明](#概念说明)
|
||
- [工作表（SubSheet）操作](#工作表subsheet操作)
|
||
- [smartsheet.list_tables - 列出工作表](#smartsheetlist_tables)
|
||
- [smartsheet.add_table - 新增工作表](#smartsheetadd_table)
|
||
- [smartsheet.delete_table - 删除工作表](#smartsheetdelete_table)
|
||
- [视图（View）操作](#视图view操作)
|
||
- [smartsheet.list_views - 列出视图](#smartsheetlist_views)
|
||
- [smartsheet.add_view - 新增视图](#smartsheetadd_view)
|
||
- [smartsheet.delete_view - 删除视图](#smartsheetdelete_view)
|
||
- [字段（Field）操作](#字段field操作)
|
||
- [smartsheet.list_fields - 列出字段](#smartsheetlist_fields)
|
||
- [smartsheet.add_fields - 新增字段](#smartsheetadd_fields)
|
||
- [smartsheet.update_fields - 更新字段](#smartsheetupdate_fields)
|
||
- [smartsheet.delete_fields - 删除字段](#smartsheetdelete_fields)
|
||
- [记录（Record）操作](#记录record操作)
|
||
- [smartsheet.list_records - 列出记录](#smartsheetlist_records)
|
||
- [smartsheet.add_records - 新增记录](#smartsheetadd_records)
|
||
- [smartsheet.update_records - 更新记录](#smartsheetupdate_records)
|
||
- [smartsheet.delete_records - 删除记录](#smartsheetdelete_records)
|
||
- [枚举值参考](#枚举值参考)
|
||
- [字段值格式参考](#字段值格式参考)
|
||
- [典型工作流示例](#典型工作流示例)
|
||
|
||
---
|
||
|
||
## 概念说明
|
||
|
||
| 概念 | 说明 |
|
||
|------|------|
|
||
| `file_id` | 智能表格文档的唯一标识符，每个文档有唯一的 file_id |
|
||
| `sheet_id` | 工作表 ID，一个智能表格文档可包含多个工作表 |
|
||
| `view_id` | 视图 ID，每个工作表可有多个视图（网格视图、看板视图等） |
|
||
| `field_id` | 字段 ID，对应表格的列 |
|
||
| `record_id` | 记录 ID，对应表格的行 |
|
||
|
||
**层级关系**：`file_id（文档）` → `sheet_id（工作表）` → `view_id（视图）` / `field_id（字段）` / `record_id（记录）`
|
||
|
||
---
|
||
|
||
## 工作表（SubSheet）操作
|
||
|
||
### smartsheet.list_tables
|
||
|
||
**功能**：列出文档下的所有工作表，返回工作表基本信息列表。
|
||
|
||
**使用场景**：
|
||
- 查看一个智能表格文档中有哪些工作表
|
||
- 获取 sheet_id 以便后续操作字段、记录、视图
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|-----------------------|------|------|
|
||
| `sheets` | array | 工作表列表 |
|
||
| `sheets[].sheet_id` | string | 工作表唯一标识符 |
|
||
| `sheets[].title` | string | 工作表名称 |
|
||
| `sheets[].is_visible` | bool | 工作表可见性 |
|
||
| `error` | string | 错误信息，操作失败时返回 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id"
|
||
}
|
||
```
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"sheets": [
|
||
{
|
||
"sheet_id": "sheet_abc123",
|
||
"title": "任务列表",
|
||
"is_visible": true
|
||
},
|
||
{
|
||
"sheet_id": "sheet_def456",
|
||
"title": "已归档",
|
||
"is_visible": false
|
||
}
|
||
],
|
||
"error": "",
|
||
"trace_id": "trace_xyz"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.add_table
|
||
|
||
**功能**：在文档中新增工作表，支持设置工作表名称和初始配置。
|
||
|
||
**使用场景**：
|
||
- 在已有智能表格文档中添加新的工作表（如新增"2024年Q2"工作表）
|
||
- 按业务模块拆分数据到不同工作表
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `properties` | object | ✅ | 工作表属性配置 |
|
||
| `properties.sheet_id` | string | ✅ | 工作表名称（注意：此字段实际含义为工作表名称） |
|
||
| `properties.title` | string | | 工作表标题 |
|
||
| `properties.index` | uint32 | | 工作表下标（位置） |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `properties` | object | 新创建工作表的属性信息 |
|
||
| `properties.sheet_id` | string | 工作表名称 |
|
||
| `properties.title` | string | 工作表标题 |
|
||
| `properties.index` | uint32 | 工作表下标 |
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"properties": {
|
||
"sheet_id": "新工作表",
|
||
"title": "2024年Q2数据",
|
||
"index": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.delete_table
|
||
|
||
**功能**：删除指定的工作表。
|
||
|
||
**使用场景**：
|
||
- 删除不再需要的工作表
|
||
- 清理测试数据工作表
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 要删除的工作表 ID |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `error` | string | 错误信息，操作失败时返回 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 视图（View）操作
|
||
|
||
### smartsheet.list_views
|
||
|
||
**功能**：列出工作表下的所有视图，返回视图基本信息和配置。
|
||
|
||
**使用场景**：
|
||
- 查看工作表有哪些视图（网格视图、看板视图）
|
||
- 获取 view_id 以便按视图筛选记录或字段
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `view_ids` | []string | | 需要查询的视图 ID 数组，不填则返回全部 |
|
||
| `offset` | uint32 | | 分页查询偏移量，默认 0 |
|
||
| `limit` | uint32 | | 分页大小，最大 100 |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `views` | array | 视图列表 |
|
||
| `views[].view_id` | string | 视图唯一标识符 |
|
||
| `views[].view_name` | string | 视图名称 |
|
||
| `views[].view_type` | uint32 | 视图类型，枚举值见下方 |
|
||
| `total` | uint32 | 符合条件的视图总数 |
|
||
| `hasMore` | bool | 是否还有更多项 |
|
||
| `next` | uint32 | 下一页偏移量 |
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**视图类型枚举值**：
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `1` | 网格视图（grid） |
|
||
| `2` | 看板视图（kanban） |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"offset": 0,
|
||
"limit": 20
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.add_view
|
||
|
||
**功能**：在工作表中新增视图，支持自定义视图名称和类型。
|
||
|
||
**使用场景**：
|
||
- 为工作表创建看板视图，按状态分组展示任务
|
||
- 创建多个网格视图，分别展示不同筛选条件的数据
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `view_title` | string | ✅ | 视图标题 |
|
||
| `view_type` | uint32 | | 视图类型：1-网格视图，2-看板视图 |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `view_id` | string | 新创建的视图 ID |
|
||
| `view_title` | string | 视图标题 |
|
||
| `view_type` | uint32 | 视图类型 |
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"view_title": "按状态分组",
|
||
"view_type": 2
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.delete_view
|
||
|
||
**功能**：删除指定的视图，支持批量删除多个视图。
|
||
|
||
**使用场景**：
|
||
- 删除不再使用的视图
|
||
- 批量清理多余视图
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `view_ids` | []string | ✅ | 要删除的视图 ID 列表 |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"view_ids": ["view_id1", "view_id2"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 字段（Field）操作
|
||
|
||
### smartsheet.list_fields
|
||
|
||
**功能**：列出工作表的所有字段，返回字段基本信息和类型配置。
|
||
|
||
**使用场景**：
|
||
- 查看工作表有哪些列（字段）及其类型
|
||
- 获取 field_id 以便后续更新或删除字段
|
||
- 在写入记录前，先了解字段结构和类型
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `view_id` | string | | 视图 ID，按视图筛选字段 |
|
||
| `field_ids` | []string | | 指定字段 ID 数组 |
|
||
| `field_titles` | []string | | 指定字段标题数组 |
|
||
| `offset` | uint32 | | 偏移量，初始值为 0 |
|
||
| `limit` | uint32 | | 分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部 |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `total` | uint32 | 符合条件的字段总数 |
|
||
| `has_more` | bool | 是否还有更多项 |
|
||
| `next` | uint32 | 下一页偏移量 |
|
||
| `fields` | array | 字段列表，详见 FieldInfo 结构 |
|
||
|
||
**FieldInfo 结构**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `field_id` | string | 字段唯一 ID |
|
||
| `field_title` | string | 字段标题（列名） |
|
||
| `field_type` | uint32 | 字段类型，枚举值见下方 |
|
||
| `property_*` | object | 字段属性，根据 field_type 不同而不同 |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.add_fields
|
||
|
||
**功能**：批量新增字段（列），支持同时添加多个不同类型的字段。
|
||
|
||
**使用场景**：
|
||
- 为工作表添加新列，如"优先级"（单选）、"截止日期"（日期）、"负责人"（用户）
|
||
- 初始化工作表结构
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `fields` | []FieldInfo | ✅ | 要添加的字段列表 |
|
||
|
||
**FieldInfo 参数说明**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `field_title` | string | ✅ | 字段标题（列名） |
|
||
| `field_type` | uint32 | ✅ | 字段类型，枚举值见下方 |
|
||
| `property_text` | object | | 文本类型属性（无需额外配置） |
|
||
| `property_number` | object | | 数字类型属性 |
|
||
| `property_checkbox` | object | | 复选框类型属性 |
|
||
| `property_date_time` | object | | 日期时间类型属性 |
|
||
| `property_url` | object | | 超链接类型属性 |
|
||
| `property_select` | object | | 多选类型属性 |
|
||
| `property_single_select` | object | | 单选类型属性 |
|
||
| `property_progress` | object | | 进度类型属性 |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `fields` | array | 添加成功的字段列表（含 field_id） |
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例（添加多种类型字段）**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"fields": [
|
||
{
|
||
"field_title": "任务名称",
|
||
"field_type": 1,
|
||
"property_text": {}
|
||
},
|
||
{
|
||
"field_title": "优先级",
|
||
"field_type": 17,
|
||
"property_single_select": {
|
||
"options": [
|
||
{ "text": "高", "style": 1 },
|
||
{ "text": "中", "style": 3 },
|
||
{ "text": "低", "style": 4 }
|
||
]
|
||
}
|
||
},
|
||
{
|
||
"field_title": "截止日期",
|
||
"field_type": 4,
|
||
"property_date_time": {
|
||
"format": "yyyy-mm-dd",
|
||
"auto_fill": false
|
||
}
|
||
},
|
||
{
|
||
"field_title": "完成进度",
|
||
"field_type": 14,
|
||
"property_progress": {
|
||
"decimal_places": 0
|
||
}
|
||
},
|
||
{
|
||
"field_title": "是否完成",
|
||
"field_type": 3,
|
||
"property_checkbox": {
|
||
"checked": false
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.update_fields
|
||
|
||
**功能**：批量更新字段属性，支持修改字段名称和配置信息。
|
||
|
||
**使用场景**：
|
||
- 修改字段标题（列名）
|
||
- 更新单选/多选字段的选项列表
|
||
- 修改数字字段的精度配置
|
||
|
||
> ⚠️ **注意**：`field_type`（字段类型）不允许被更新，但更新时必须传入原字段类型值。
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `fields` | []FieldInfo | ✅ | 要更新的字段列表，必须包含 field_id |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `fields` | array | 更新成功的字段列表 |
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例（修改字段标题和选项）**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"fields": [
|
||
{
|
||
"field_id": "field_id_001",
|
||
"field_title": "任务状态",
|
||
"field_type": 17,
|
||
"property_single_select": {
|
||
"options": [
|
||
{ "text": "待处理", "style": 7 },
|
||
{ "text": "进行中", "style": 3 },
|
||
{ "text": "已完成", "style": 4 },
|
||
{ "text": "已取消", "style": 1 }
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.delete_fields
|
||
|
||
**功能**：批量删除字段（列），支持同时删除多个字段。
|
||
|
||
**使用场景**：
|
||
- 删除不再需要的列
|
||
- 清理冗余字段
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `field_ids` | []string | ✅ | 要删除的字段 ID 数组 |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"field_ids": ["field_id_001", "field_id_002"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 记录（Record）操作
|
||
|
||
### smartsheet.list_records
|
||
|
||
**功能**：分页列出工作表记录（行），支持排序和按字段筛选。
|
||
|
||
**使用场景**：
|
||
- 读取工作表中的数据
|
||
- 按特定字段排序查看数据
|
||
- 分页获取大量数据
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `view_id` | string | | 视图 ID，按视图筛选记录 |
|
||
| `record_ids` | []string | | 指定记录 ID 数组，精确查询 |
|
||
| `field_titles` | []string | | 只返回指定字段标题的值，不填则返回全部字段 |
|
||
| `sort` | []Sort | | 排序配置 |
|
||
| `offset` | uint32 | | 偏移量，初始值为 0 |
|
||
| `limit` | uint32 | | 分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部 |
|
||
|
||
**Sort 排序配置**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `field_title` | string | ✅ | 需要排序的字段标题 |
|
||
| `desc` | bool | | 是否降序，默认 false（升序） |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `total` | uint32 | 符合条件的记录总数 |
|
||
| `has_more` | bool | 是否还有更多项 |
|
||
| `next` | uint32 | 下一页偏移量 |
|
||
| `records` | array | 记录列表，详见 RecordInfo 结构 |
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**RecordInfo 结构**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `record_id` | string | 记录唯一 ID |
|
||
| `field_values` | map | 字段值映射，key 为字段标题，value 为字段值 |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"field_titles": ["任务名称", "优先级", "截止日期"],
|
||
"sort": [
|
||
{ "field_title": "截止日期", "desc": false }
|
||
],
|
||
"offset": 0,
|
||
"limit": 50
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.add_records
|
||
|
||
**功能**：批量添加记录（行），支持同时添加多条记录数据。
|
||
|
||
**使用场景**：
|
||
- 批量导入数据到工作表
|
||
- 添加新任务、新条目
|
||
- 从其他数据源同步数据
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `records` | []AddRecord | ✅ | 要添加的记录列表 |
|
||
|
||
**AddRecord 结构**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `field_values` | map | ✅ | 字段值映射，key 为字段标题，value 为字段值（格式见下方） |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `records` | array | 添加成功的记录列表（含 record_id） |
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"records": [
|
||
{
|
||
"field_values": {
|
||
"任务名称": [{"text": "完成需求文档", "type": "text"}],
|
||
"优先级": [{"text": "高"}],
|
||
"截止日期": "1720000000000",
|
||
"完成进度": 30,
|
||
"是否完成": false
|
||
}
|
||
},
|
||
{
|
||
"field_values": {
|
||
"任务名称": [{"text": "代码评审", "type": "text"}],
|
||
"优先级": [{"text": "中"}],
|
||
"截止日期": "1720086400000",
|
||
"完成进度": 0,
|
||
"是否完成": false
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.update_records
|
||
|
||
**功能**：批量更新记录，支持修改多条记录的字段值。
|
||
|
||
**使用场景**：
|
||
- 更新任务状态、进度
|
||
- 修改记录中的某些字段值
|
||
- 批量修改多条数据
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `records` | []RecordInfo | ✅ | 要更新的记录列表，必须包含 record_id |
|
||
|
||
**RecordInfo 参数说明**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `record_id` | string | ✅ | 记录 ID，标识要更新哪条记录 |
|
||
| `field_values` | map | ✅ | 要更新的字段值映射 |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"records": [
|
||
{
|
||
"record_id": "record_id_001",
|
||
"field_values": {
|
||
"完成进度": 100,
|
||
"是否完成": true,
|
||
"优先级": [{"text": "高"}]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### smartsheet.delete_records
|
||
|
||
**功能**：批量删除记录（行），支持同时删除多条指定的记录。
|
||
|
||
**使用场景**：
|
||
- 删除已完成或过期的任务记录
|
||
- 清理测试数据
|
||
- 批量删除多条记录
|
||
|
||
**请求参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
|
||
| `sheet_id` | string | ✅ | 工作表 ID |
|
||
| `record_ids` | []string | ✅ | 要删除的记录 ID 列表 |
|
||
|
||
**返回字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `error` | string | 错误信息 |
|
||
| `trace_id` | string | 调用链追踪 ID |
|
||
|
||
**调用示例**：
|
||
|
||
```json
|
||
{
|
||
"file_id": "your_file_id",
|
||
"sheet_id": "sheet_abc123",
|
||
"record_ids": ["record_id_001", "record_id_002", "record_id_003"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 枚举值参考
|
||
|
||
### 字段类型（field_type）
|
||
|
||
| 枚举值 | 类型名称 | 对应 property 字段 | 说明 |
|
||
|--------|---------|-------------------|------|
|
||
| `1` | 文本 | `property_text` | 普通文本，无需额外配置 |
|
||
| `2` | 数字 | `property_number` | 整数或浮点数 |
|
||
| `3` | 复选框 | `property_checkbox` | 布尔值 true/false |
|
||
| `4` | 日期 | `property_date_time` | 毫秒时间戳字符串 |
|
||
| `5` | 图片 | `property_image` | 图片 ID 数组 |
|
||
| `8` | 超链接 | `property_url` | URL 数组 |
|
||
| `9` | 多选 | `property_select` | 选项数组（可多选） |
|
||
| `10` | 创建人 | `property_user` | 系统自动填充，无需配置 |
|
||
| `11` | 最后编辑人 | `property_modified_user` | 系统自动填充，无需配置 |
|
||
| `12` | 创建时间 | `property_created_time` | 系统自动填充，无需配置 |
|
||
| `13` | 最后编辑时间 | `property_modified_time` | 系统自动填充，无需配置 |
|
||
| `14` | 进度 | `property_progress` | 整数或浮点数（百分比） |
|
||
| `15` | 电话 | `property_phone_number` | 字符串，无需额外配置 |
|
||
| `16` | 邮件 | `property_email` | 字符串，无需额外配置 |
|
||
| `17` | 单选 | `property_single_select` | 选项数组（只能单选） |
|
||
| `18` | 关联 | - | 关联其他记录，值为 record_id 字符串数组 |
|
||
| `25` | 自动编号 | - | 系统自动生成编号，无需手动配置 |
|
||
| `26` | 货币 | - | 浮点数，表示货币金额 |
|
||
| `28` | 百分比 | - | 浮点数，如 0.75 表示 75% |
|
||
|
||
### 视图类型（view_type）
|
||
|
||
| 枚举值 | 说明 |
|
||
|--------|------|
|
||
| `1` | 网格视图（grid）- 传统表格形式 |
|
||
| `2` | 看板视图（kanban）- 按列分组展示 |
|
||
|
||
### 选项颜色（style）
|
||
|
||
| 枚举值 | 颜色 |
|
||
|--------|------|
|
||
| `1` | 红色 |
|
||
| `2` | 橘黄色 |
|
||
| `3` | 蓝色 |
|
||
| `4` | 绿色 |
|
||
| `5` | 紫色 |
|
||
| `6` | 粉色 |
|
||
| `7` | 灰色 |
|
||
| `8` | 白色 |
|
||
|
||
### 超链接展示样式（UrlFieldProperty.type）
|
||
|
||
| 枚举值 | 说明 |
|
||
|--------|------|
|
||
| `0` | 未知 |
|
||
| `1` | 文字 |
|
||
| `2` | 图标文字 |
|
||
|
||
---
|
||
|
||
## 字段值格式参考
|
||
|
||
在 `add_records` 和 `update_records` 中，`field_values` 的 value 格式因字段类型而异：
|
||
|
||
| 字段类型 | 值格式 | 示例 |
|
||
|---------|--------|------------------------------------------------------------|
|
||
| 文本（1） | JSON Array of TextValue | `[{"text": "内容", "type": "text"}]` |
|
||
| 数字（2） | number | `42` 或 `3.14` |
|
||
| 复选框（3） | bool | `true` 或 `false` |
|
||
| 日期（4） | string（毫秒时间戳） | `"1720000000000"` |
|
||
| 图片（5） | JSON Array of ImageIDValue | `[{"image_id": "图片id"}]` |
|
||
| 超链接（8） | JSON Array of UrlValue | `[{"text": "链接文字", "type": "url", "link": "https://..."}]` |
|
||
| 多选（9） | JSON Array of OptionValue | `[{"text": "选项1"}, {"text": "选项2"}]` |
|
||
| 进度（14） | number | `75` 或 `75.5` |
|
||
| 电话（15） | string | `"13800138000"` |
|
||
| 邮件（16） | string | `"user@example.com"` |
|
||
| 单选（17） | JSON Array of OptionValue（单个） | `[{"text": "选项文字"}]` |
|
||
| 关联（18） | array string | `["record_id_1", "record_id_2"]` |
|
||
| 自动编号（25） | JSON(AutoNumberValue) | `{"seq": "1", "text": "编号内容"}` |
|
||
| 货币（26） | double | `99.99` |
|
||
| 百分比（28） | double | `0.75`（表示 75%） |
|
||
|
||
### TextValue 结构
|
||
|
||
```json
|
||
{
|
||
"text": "文本内容",
|
||
"type": "text"
|
||
}
|
||
```
|
||
|
||
### UrlValue 结构
|
||
|
||
```json
|
||
{
|
||
"text": "链接显示文字",
|
||
"type": "url",
|
||
"link": "https://example.com"
|
||
}
|
||
```
|
||
|
||
### OptionValue 结构
|
||
|
||
```json
|
||
{
|
||
"id": "选项ID（可选）",
|
||
"text": "选项文字",
|
||
"style": 3
|
||
}
|
||
```
|
||
|
||
> ⚠️ **注意**：写入记录时，单选/多选字段的 `text` 必须与字段属性中已定义的选项文字完全匹配，否则可能写入失败。
|
||
|
||
---
|
||
|
||
## 字段属性（Property）详细说明
|
||
|
||
### NumberFieldProperty（数字字段属性）
|
||
|
||
```json
|
||
{
|
||
"decimal_places": 2,
|
||
"use_separate": true
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `decimal_places` | uint32 | 小数点位数（精度） |
|
||
| `use_separate` | bool | 是否使用千位符（如 1,000） |
|
||
|
||
### CheckboxFieldProperty（复选框字段属性）
|
||
|
||
```json
|
||
{
|
||
"checked": false
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `checked` | bool | 新增记录时是否默认勾选 |
|
||
|
||
### DateTimeFieldProperty（日期时间字段属性）
|
||
|
||
```json
|
||
{
|
||
"format": "yyyy-mm-dd",
|
||
"auto_fill": false
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `format` | string | 日期格式，支持格式见下方 |
|
||
| `auto_fill` | bool | 新建记录时是否自动填充当前时间 |
|
||
|
||
**支持的日期格式**：
|
||
|
||
| 格式字符串 | 示例 |
|
||
|-----------|------|
|
||
| `yyyy"年"m"月"d"日"` | 2018 年 4 月 20 日 |
|
||
| `yyyy-mm-dd` | 2018-04-20 |
|
||
| `yyyy/m/d` | 2018/4/20 |
|
||
| `m"月"d"日"` | 4 月 20 日 |
|
||
| `[$-804]yyyy"年"m"月"d"日" dddd` | 2018 年 4 月 20 日 星期五 |
|
||
| `yyyy"年"m"月"d"日" hh:mm` | 2018 年 4 月 20 日 14:00 |
|
||
| `yyyy-mm-dd hh:mm` | 2018-04-20 14:00 |
|
||
| `m/d/yyyy` | 4/20/2018 |
|
||
| `d/m/yyyy` | 20/4/2018 |
|
||
|
||
### UrlFieldProperty（超链接字段属性）
|
||
|
||
```json
|
||
{
|
||
"type": 1
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `type` | uint32 | 展示样式：0-未知，1-文字，2-图标文字 |
|
||
|
||
### SelectFieldProperty（多选字段属性）
|
||
|
||
```json
|
||
{
|
||
"options": [
|
||
{ "id": "opt_001", "text": "选项A", "style": 3 },
|
||
{ "id": "opt_002", "text": "选项B", "style": 4 }
|
||
],
|
||
"is_multiple": true,
|
||
"is_quick_add": false
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `options` | []Option | 选项列表 |
|
||
| `is_multiple` | bool | 是否多选（系统参数，用户无需设置） |
|
||
| `is_quick_add` | bool | 是否允许填写时新增选项（系统参数，用户无需设置） |
|
||
|
||
### SingleSelectFieldProperty（单选字段属性）
|
||
|
||
结构与 `SelectFieldProperty` 相同，但只允许单选。
|
||
|
||
### ProgressFieldProperty（进度字段属性）
|
||
|
||
```json
|
||
{
|
||
"decimal_places": 0
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `decimal_places` | uint32 | 小数位数 |
|
||
|
||
---
|
||
|
||
## 典型工作流示例
|
||
|
||
### 工作流一：从零创建表
|
||
|
||
```
|
||
步骤 1：获取文档的工作表列表
|
||
→ smartsheet.list_tables（获取 sheet_id）
|
||
|
||
步骤 2：为工作表添加字段
|
||
→ smartsheet.add_fields（添加：任务名称、优先级、负责人、截止日期、状态、进度）
|
||
|
||
步骤 3：批量添加任务记录
|
||
→ smartsheet.add_records（写入多条任务数据）
|
||
|
||
步骤 4：删除默认空行和默认列
|
||
→ smartsheet.list_records（获取建表时自动生成的空行 record_id 列表）
|
||
→ smartsheet.delete_records（传入空行 record_ids，批量删除默认空行）
|
||
→ smartsheet.list_fields（获取建表时自动生成的默认列 field_id 列表）
|
||
→ smartsheet.delete_fields（传入默认列 field_ids，批量删除默认列）
|
||
|
||
步骤 5：（可选）创建看板视图
|
||
→ smartsheet.add_view（view_type=2，按状态分组）
|
||
```
|
||
|
||
### 工作流二：查询并更新任务状态
|
||
|
||
```
|
||
步骤 1：列出工作表
|
||
→ smartsheet.list_tables（获取 sheet_id）
|
||
|
||
步骤 2：查询记录
|
||
→ smartsheet.list_records（获取 record_id 和当前字段值）
|
||
|
||
步骤 3：更新指定记录
|
||
→ smartsheet.update_records（传入 record_id 和新的字段值）
|
||
```
|
||
|
||
### 工作流三：读取数据并分析
|
||
|
||
```
|
||
步骤 1：列出工作表
|
||
→ smartsheet.list_tables
|
||
|
||
步骤 2：了解字段结构
|
||
→ smartsheet.list_fields（了解有哪些列及其类型）
|
||
|
||
步骤 3：分页读取所有记录
|
||
→ smartsheet.list_records（offset=0, limit=100）
|
||
→ 若 has_more=true，继续请求下一页（offset=100）
|
||
|
||
步骤 4：处理数据
|
||
→ 根据 field_values 中的数据进行统计分析
|
||
```
|
||
|
||
### 工作流四：清理过期数据
|
||
|
||
```
|
||
步骤 1：列出工作表
|
||
→ smartsheet.list_tables
|
||
|
||
步骤 2：查询需要删除的记录
|
||
→ smartsheet.list_records（获取目标 record_id 列表）
|
||
|
||
步骤 3：批量删除记录
|
||
→ smartsheet.delete_records（传入 record_ids 数组）
|
||
```
|
||
|
||
---
|
||
|
||
> 📌 **提示**：所有操作都需要先获取 `file_id`（智能表格文档 ID）和 `sheet_id`（工作表 ID）。
|
||
> 可通过 `manage.search_file` 搜索文档获取 `file_id`，再通过 `smartsheet.list_tables` 获取 `sheet_id`。
|
||
|
||
|
||
## 注意事项
|
||
|
||
- **前置条件**：所有 smartsheet.* 工具都需要 `file_id` 和 `sheet_id`，操作前先调用 `smartsheet.list_tables` 获取 sheet_id
|
||
- **图片字段写入**：向图片类型字段（field_type=5）写入数据时，需先调用 `upload_image` 工具上传图片获取 `image_id`，再以 `[{"image_id": "xxx"}]` 格式填入字段值
|
||
- **字段类型不可变**：`update_fields` 时 `field_type` 不能修改，但必须传入原值；支持的字段类型详见字段类型枚举表
|
||
- **记录字段值格式**：不同字段类型的值格式不同，详见上方"字段值格式参考"章节
|