Back to Details

wecomcli-smartsheet

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

企业微信智能表格管理

WeCom Smart Sheet Management

wecom-cli
是企业微信提供的命令行程序，所有操作通过执行 
wecom-cli
命令完成。
管理企业微信智能表格的结构（子表、字段/列）和数据（记录）。所有接口支持通过 
docid
或 
url
二选一定位文档。
wecom-cli
is a command-line program provided by WeCom. All operations are completed by executing 
wecom-cli
commands.
Manage the structure (sub-sheets, fields/columns) and data (records) of WeCom Smart Sheets. All interfaces support locating documents by choosing either 
docid
or 
url
.

调用方式

Calling Method

通过 
wecom-cli
调用，品类为 
doc
：
bash
wecom-cli doc <tool_name> '<json_params>'
Call via 
wecom-cli
, category is 
doc
:
bash
wecom-cli doc <tool_name> '<json_params>'

返回格式说明

Return Format Description

所有接口返回 JSON 对象，包含以下公共字段：
字段类型说明
errcode
integer返回码，
0
表示成功，非 
0
表示失败
errmsg
string错误信息，成功时为 
"ok"
当 
errcode
不为 
0
时，说明接口调用失败，可重试 1 次；若仍失败，将 
errcode
和 
errmsg
展示给用户。
All interfaces return JSON objects containing the following public fields:
FieldTypeDescription
errcode
integerReturn code, 
0
indicates success, non-
0
indicates failure
errmsg
stringError message, 
"ok"
when successful
When 
errcode
is not 
0
, it means the interface call failed. You can retry once; if it still fails, display 
errcode
and 
errmsg
to the user.

一、智能表格结构管理

I. Smart Sheet Structure Management

smartsheet_get_sheet

smartsheet_get_sheet

查询文档中所有子表信息，返回 sheet_id、title、类型等。
bash
wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'
Query all sub-sheet information in the document, returning sheet_id, title, type, etc.
bash
wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'

smartsheet_add_sheet

smartsheet_add_sheet

添加空子表。新子表不含视图、记录和字段，需通过其他接口补充。
bash
wecom-cli doc smartsheet_add_sheet '{"docid": "DOCID", "properties": {"title": "新子表"}}'
注意：新建智能表格文档默认已含一个子表，仅需多个子表时调用。
Add an empty sub-sheet. The new sub-sheet contains no views, records or fields, which need to be supplemented via other interfaces.
bash
wecom-cli doc smartsheet_add_sheet '{"docid": "DOCID", "properties": {"title": "New Sub-sheet"}}'
Note: A newly created Smart Sheet document contains one sub-sheet by default. Only call this when multiple sub-sheets are needed.

smartsheet_update_sheet

smartsheet_update_sheet

修改子表标题。需提供 sheet_id 和新 title。
bash
wecom-cli doc smartsheet_update_sheet '{"docid": "DOCID", "properties":{"sheet_id":"SHEET_ID", "title":"新子表"}}'
Modify the title of a sub-sheet. Need to provide sheet_id and new title.
bash
wecom-cli doc smartsheet_update_sheet '{"docid": "DOCID", "properties":{"sheet_id":"SHEET_ID", "title":"New Sub-sheet"}}'

smartsheet_delete_sheet

smartsheet_delete_sheet

永久删除子表，操作不可逆。
bash
wecom-cli doc smartsheet_delete_sheet '{"docid": "DOCID", "sheet_id": "SHEETID"}'
Permanently delete a sub-sheet, this operation is irreversible.
bash
wecom-cli doc smartsheet_delete_sheet '{"docid": "DOCID", "sheet_id": "SHEETID"}'

smartsheet_get_fields

smartsheet_get_fields

查询子表的所有字段信息，返回 field_id、field_title、field_type。
bash
wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'
Query all field information of a sub-sheet, returning field_id, field_title, field_type.
bash
wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'

smartsheet_add_fields

smartsheet_add_fields

向子表添加一个或多个字段。单个子表最多 150 个字段。
bash
wecom-cli doc smartsheet_add_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_title": "任务名称", "field_type": "FIELD_TYPE_TEXT"}]}'
在添加字段前，请先参阅所有字段类型和定义 字段类型参考。
Add one or more fields to a sub-sheet. A single sub-sheet can have a maximum of 150 fields.
bash
wecom-cli doc smartsheet_add_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_title": "Task Name", "field_type": "FIELD_TYPE_TEXT"}]}'
Before adding fields, please refer to all field types and definitions Field Type Reference.

smartsheet_update_fields

smartsheet_update_fields

更新字段标题。只能改名，不能改类型（field_type 必须传原始类型）。field_title 不能更新为原值。
bash
wecom-cli doc smartsheet_update_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_id": "FIELDID", "field_title": "新标题", "field_type": "FIELD_TYPE_TEXT"}]}'
Update field titles. Only the name can be changed, not the type (field_type must be the original type). field_title cannot be updated to its original value.
bash
wecom-cli doc smartsheet_update_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_id": "FIELDID", "field_title": "New Title", "field_type": "FIELD_TYPE_TEXT"}]}'

smartsheet_delete_fields

smartsheet_delete_fields

删除一列或多列字段，操作不可逆。field_id 可通过 
smartsheet_get_fields
获取。
bash
wecom-cli doc smartsheet_delete_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "field_ids": ["FIELDID"]}'
Delete one or more fields, this operation is irreversible. field_id can be obtained via 
smartsheet_get_fields
.
bash
wecom-cli doc smartsheet_delete_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "field_ids": ["FIELDID"]}'

二、智能表格数据管理

II. Smart Sheet Data Management

smartsheet_get_records

smartsheet_get_records

查询子表全部记录。
  • 通过 docid：
bash
wecom-cli doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'
  • 或通过 URL：
bash
wecom-cli doc smartsheet_get_records '{"url": "https://doc.weixin.qq.com/smartsheet/xxx", "sheet_id": "SHEETID"}'
参见 API 详情。
Query all records of a sub-sheet.
  • Via docid:
bash
wecom-cli doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'
  • Or via URL:
bash
wecom-cli doc smartsheet_get_records '{"url": "https://doc.weixin.qq.com/smartsheet/xxx", "sheet_id": "SHEETID"}'
See API Details.

smartsheet_add_records 添加一行或多行记录(不带图片或文件)

smartsheet_add_records Add one or more records (without images or files)

添加一行或多行记录，单次建议 500 行内。
调用前必须先了解目标表的字段类型（通过 
smartsheet_get_fields
），重点关注 
field_type
。对于单选/多选（Option）字段，需注意匹配已有选项的 
id
。
bash
wecom-cli doc smartsheet_add_records '{"docid": "DOCID", "sheet_id": "SHEETID", "records": [{"values": {"任务名称": [{"type": "text", "text": "完成需求文档"}], "优先级": [{"text": "高"}]}}]}'
各字段类型的值格式参见 单元格值格式参考。
Add one or more records, it is recommended to add within 500 rows at a time.
Before calling, you must understand the field types of the target sheet (via 
smartsheet_get_fields
), focusing on 
field_type
. For single-select/multi-select (Option) fields, note to match the 
id
of existing options.
bash
wecom-cli doc smartsheet_add_records '{"docid": "DOCID", "sheet_id": "SHEETID", "records": [{"values": {"Task Name": [{"type": "text", "text": "Complete Requirements Document"}], "Priority": [{"text": "High"}]}}]}'
Refer to Cell Value Format Reference for the value format of each field type.

+smartsheet_add_records_auto_file 添加一行或多行记录(带图片或文件)

+smartsheet_add_records_auto_file Add one or more records (with images or files)

添加一行或多行记录，单次建议 500 行内。与 
smartsheet_add_records
不同之处在于，可支持本地路径传入图片、文件。对于需要添加带图片或文件的记录，请使用此接口。传入后台后，后台将自动存储并转换为image_url。
bash
wecom-cli doc +smartsheet_add_records_auto_file '{"docid":"DOCID","sheet_id":"SHEETID","records":[{"values":{"图片":[{"image_path":"/path/to/image.jpg"}],"文件":[{"file_path":"/path/to/file.txt"}]}}]}'
Add one or more records, it is recommended to add within 500 rows at a time. Different from 
smartsheet_add_records
, this interface supports passing in images and files via local paths. For adding records with images or files, please use this interface. After being passed to the backend, the backend will automatically store and convert them to image_url.
bash
wecom-cli doc +smartsheet_add_records_auto_file '{"docid":"DOCID","sheet_id":"SHEETID","records":[{"values":{"Image":[{"image_path":"/path/to/image.jpg"}],"File":[{"file_path":"/path/to/file.txt"}]}}]}'

smartsheet_update_records 更新记录(不带图片或文件)

smartsheet_update_records Update records (without images or files)

更新一行或多行记录，单次建议在 500 行内。需提供 record_id（通过 
smartsheet_get_records
获取）。支持通过 
key_type
指定 values 的 key 使用字段标题或字段 ID：
  • CELL_VALUE_KEY_TYPE_FIELD_TITLE
    ：key 为字段标题
  • CELL_VALUE_KEY_TYPE_FIELD_ID
    ：key 为字段 ID
bash
wecom-cli doc smartsheet_update_records '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"任务名称": [{"type": "text", "text": "更新后的内容"}]}}]}'
注意：创建时间、最后编辑时间、创建人、最后编辑人字段不可更新。
Update one or more records, it is recommended to update within 500 rows at a time. Need to provide record_id (obtained via 
smartsheet_get_records
). Supports specifying the key of values to use field title or field ID via 
key_type
:
  • CELL_VALUE_KEY_TYPE_FIELD_TITLE
    : key is field title
  • CELL_VALUE_KEY_TYPE_FIELD_ID
    : key is field ID
bash
wecom-cli doc smartsheet_update_records '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"Task Name": [{"type": "text", "text": "Updated Content"}]}}]}'
Note: Fields of creation time, last edit time, creator, and last editor cannot be updated.

+smartsheet_update_records_auto_file 更新记录(更新图片或文件字段)

+smartsheet_update_records_auto_file Update records (update image or file fields)

更新一行或多行记录，单次建议在 500 行内。与 
smartsheet_update_records
不同之处在于，可支持本地路径传入图片、文件。对于需要更新记录中的图片或文件，请使用此接口。传入后台后，后台将自动存储并转换为image_url。
bash
wecom-cli doc +smartsheet_update_records_auto_file '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"values":{"图片":[{"image_path":"/path/to/image.jpg"}],"文件":[{"file_path":"/path/to/file.txt"}]}}}]}'
Update one or more records, it is recommended to update within 500 rows at a time. Different from 
smartsheet_update_records
, this interface supports passing in images and files via local paths. For updating images or files in records, please use this interface. After being passed to the backend, the backend will automatically store and convert them to image_url.
bash
wecom-cli doc +smartsheet_update_records_auto_file '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"values":{"Image":[{"image_path":"/path/to/image.jpg"}],"File":[{"file_path":"/path/to/file.txt"}]}}}]}'

smartsheet_delete_records

smartsheet_delete_records

删除一行或多行记录，单次必须在 500 行内。操作不可逆。record_id 通过 
smartsheet_get_records
获取。极速版智能表格不支持此接口。
bash
wecom-cli doc smartsheet_delete_records '{"docid": "DOCID", "sheet_id": "SHEETID", "record_ids": ["RECORDID1", "RECORDID2"]}'
Delete one or more records, must delete within 500 rows at a time. This operation is irreversible. record_id is obtained via 
smartsheet_get_records
. Express Smart Sheet does not support this interface.
bash
wecom-cli doc smartsheet_delete_records '{"docid": "DOCID", "sheet_id": "SHEETID", "record_ids": ["RECORDID1", "RECORDID2"]}'

典型工作流

Typical Workflows

智能表格结构操作

Smart Sheet Structure Operations

  1. 了解表结构 →
bash
wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'
→
bash
wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'
  1. 创建表结构 → 
    smartsheet_add_sheet
    添加子表 → 
    smartsheet_add_fields
    定义列
  2. 修改表结构 → 
    smartsheet_update_fields
    改列名 / 
    smartsheet_delete_fields
    删列
  1. Understand sheet structure →
bash
wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'
→
bash
wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'
  1. Create sheet structure → 
    smartsheet_add_sheet
    to add sub-sheet → 
    smartsheet_add_fields
    to define columns
  2. Modify sheet structure → 
    smartsheet_update_fields
    to rename columns / 
    smartsheet_delete_fields
    to delete columns

智能表格数据操作

Smart Sheet Data Operations

  1. 读取数据 →
bash
wecom-cli doc smartsheet_get_records '{"docid":"DOCID","sheet_id":"SHEETID"}'
  1. 写入数据 → 先 
    smartsheet_get_fields
    了解列类型 → 若涉及成员（USER）字段，先通过 
    wecomcli-contact
    的 
    get_userlist
    查找人员 userid → 
    smartsheet_add_records
    写入
  2. 更新数据 → 先 
    smartsheet_get_records
    获取 record_id → 若涉及成员（USER）字段，先通过 
    wecomcli-contact
    的 
    get_userlist
    查找人员 userid → 
    smartsheet_update_records
    更新
  3. 删除数据 → 先 
    smartsheet_get_records
    确认 record_id → 
    smartsheet_delete_records
    删除
注意：成员（USER）类型字段需要填写 
user_id
，不能直接使用姓名。必须先通过 
wecomcli-contact
技能的 
get_userlist
接口按姓名查找到对应的 
userid
后再使用。
  1. Read data →
bash
wecom-cli doc smartsheet_get_records '{"docid":"DOCID","sheet_id":"SHEETID"}'
  1. Write data → First use 
    smartsheet_get_fields
    to understand column types → If involving member (USER) fields, first find the userid via 
    get_userlist
    of 
    wecomcli-contact
    → Use 
    smartsheet_add_records
    to write
  2. Update data → First use 
    smartsheet_get_records
    to get record_id → If involving member (USER) fields, first find the userid via 
    get_userlist
    of 
    wecomcli-contact
    → Use 
    smartsheet_update_records
    to update
  3. Delete data → First use 
    smartsheet_get_records
    to confirm record_id → Use 
    smartsheet_delete_records
    to delete
Note: Member (USER) type fields require filling in 
user_id
, not directly using the name. You must first find the corresponding 
userid
by name via the 
get_userlist
interface of the 
wecomcli-contact
skill before using it.