目录
本接口用于获取 Smartsheet 中某个子表下记录信息,该接口可以完成下面三种功能:获取全部记录信息、依据字段名和记录 ID 获取对应记录、对记录进行排序。
请求方式:POST(HTTPS)
请求地址:https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_records?access_token=ACCESS_TOKEN
请求包体:
{
"docid": "DOCID",
"sheet_id": "123Abc",
"view_id": "vCRl8n",
"record_ids": [],
"key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE",
"field_titles": [],
"field_ids": [],
"sort": [],
"offset": 0,
"limit": 100
}
参数说明
参数 | 类型 | 是否必须 | 说明 |
---|---|---|---|
docid | string | 是 | 文档的docid |
sheet_id | string | 是 | Smartsheet 子表ID |
view_id | string | 否 | 视图 ID |
record_ids | string[] | 否 | 由记录 ID 组成的 JSON 数组 |
key_type | string(CellValueKeyType) | 否 | 返回记录中单元格的key类型 |
field_titles | string[] | 否 | 返回指定列,由字段标题组成的 JSON 数组 ,key_type 为 CELL_VALUE_KEY_TYPE_FIELD_TITLE 时有效 |
field_ids | string[] | 否 | 返回指定列,由字段 ID 组成的 JSON 数组 ,key_type 为 CELL_VALUE_KEY_TYPE_FIELD_ID 时有效 |
sort | Object[](Sort) | 否 | 对返回记录进行排序 |
offset | uint32 | 否 | 偏移量,初始值为 0 |
limit | uint32 | 否 | 分页大小 , 每页返回多少条数据;当不填写该参数或将该参数设置为 0 时,如果总数大于 1000,一次性返回 1000 行记录,当总数小于 1000 时,返回全部记录;limit 最大值为 1000 |
权限说明
返回示例
{
"errcode": 0,
"errmsg": "ok"
}
参数说明
参数 | 类型 | 说明 |
---|---|---|
errcode | int32 | 错误码 |
errmsg | string | 错误码说明 |
total | uint32 | 符合筛选条件的视图总数 |
has_more | bool | 是否还有更多项 |
next | uint32 | 下次下一个搜索结果的偏移量 |
records | Object[](Record) | 由查询记录的具体内容组成的 JSON 数组 |
记录(Record)中key的类型
枚举类型 | 描述 |
---|---|
CELL_VALUE_KEY_TYPE_FIELD_TITLE | key用字段标题表示 |
CELL_VALUE_KEY_TYPE_FIELD_ID | key用字段 ID 表示 |
示例
字段标题为文本列
的降序排序,字段标题为数字列
的升序序排序。需要一个Sort数组:
[
{
"field_title": "文本列",
"desc": true
},
{
"field_title": "数字列",
"desc": false
}
]
在 Smartsheet 的某个表格中对记录进行排序的参数:
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
field_title | string | 是 | 需要排序的字段标题 |
desc | bool | 否 | 是否进行降序排序,默认值为 false |
Smartsheet 的某个表格中记录相关的参数:
示例1
按字段标题
返回各行的单元格内容
{
"record_id": "r5ud8u",
"create_time": "1715846245084",
"update_time": "1715846248810",
"values": {
"文本字段1-标题": [
{
"type": "text",
"text": "XXXX"
}
],
"数字字段1-标题": 123
},
"creator_name":"NAME",
"updater_name":"NAME"
}
示例2
按字段ID
返回各行的单元格内容
{
"record_id": "r5ud8u",
"create_time": "1715846245084",
"update_time": "1715846248810",
"values": {
"TextField1Id": [
{
"type": "text",
"text": "XXXX"
}
],
"NumField1Id": 123
},
"creator_name":"NAME",
"updater_name":"NAME"
}
参数名 | 类型 | 描述 |
---|---|---|
record_id | string | 记录 ID |
create_time | string | 记录的创建时间 |
update_time | string | 记录的更新时间 |
values | Object | 记录的具体内容,key 为字段标题或字段 ID ,value 详见(Value) |
creator_name | string | 创建者名字 |
updater_name | string | 最后编辑者名字 |
各种类型的字段对应的单元格的值
字段类型 | 单元格值类型 | 描述 |
---|---|---|
文本(FIELD_TYPE_TEXT) | Object[](CellTextValue) | |
数字(FIELD_TYPE_NUMBER) | double | |
复选框(FIELD_TYPE_CHECKBOX) | bool | |
日期(FIELD_TYPE_DATE_TIME) | string(以毫秒为单位的unix时间戳) | |
图片(FIELD_TYPE_IMAGE) | Object[](CellImageValue) | |
文件(FIELD_TYPE_ATTACHMENT) | Object[](CellAttachmentValue) | |
成员(FIELD_TYPE_USER) | Object[](CellUserValue) | |
链接(FIELD_TYPE_URL) | Object[](CellUrlValue) | 数组类型为预留能力,目前只支持展示一个链接,建议只传入一个链接 |
多选(FIELD_TYPE_SELECT) | Object[](Option) | |
进度(FIELD_TYPE_PROGRESS) | double | |
电话(FIELD_TYPE_PHONE_NUMBER) | string | |
邮箱(FIELD_TYPE_EMAIL) | string | |
单选(FIELD_TYPE_SINGLE_SELECT) | Object[](Option) | |
地理位置(FIELD_TYPE_LOCATION) | Object[](CellLocationValue) | 长度不大于1的数组。 |
关联(FIELD_TYPE_REFERENCE) | string [] | 关联的记录id |
货币(FIELD_TYPE_CURRENCY) | double | |
自动编号(FIELD_TYPE_AUTONUMBER) | Object[](CellAutoNumberValue |
文本类型字段的单元值类型
参数名 | 类型 | 描述 |
---|---|---|
type | string | 内容为文本(值为text )、内容为链接(值为url ) |
text | string | 单元格内容 |
link | string | 当type时url 时,表示链接跳转url |
参数名 | 类型 | 描述 |
---|---|---|
id | string | 图片 ID |
title | string | 图片标题 |
image_url | string | 图片url |
width | int32 | 图片宽度 |
height | int32 | 图片高度 |
示例
{
"doc_type": 2,
"file_ext": "SMARTSHEET",
"file_type": "70",
"file_url": "https://doc.weixin.qq.com/smartsheet/xxx",
"name": "智能表格",
"size": 3267
}
参数名 | 类型 | 描述 |
---|---|---|
name | string | 文件名 |
size | int32 | 文件大小 |
file_ext | string | 文件扩展名 |
file_url | string | 文件url |
file_type | string | 文件类型,文件夹为Folder,微盘文件为Wedrive,文件夹为Folder,微盘文件为Wedrive,收集表为30,文档为50,表格是51,幻灯片为52,思维导图为54,流程图为55,智能表为70 |
doc_type | string | 接口返回的文件类型,1为文件夹,2为文件 |
参数名 | 类型 | 描述 |
---|---|---|
user_id | string | 成员ID |
tmp_external_userid | string | 外部用户临时id,同一个用户在不同的智能表中返回的该id不一致。可进一步通过tmp_external_userid的转换接口转换成external_userid,方便识别外部用户的身份。 |
数组类型为预留能力,目前只支持展示一个链接,建议只传入一个链接
示例
{
"link": "https://developer.work.weixin.qq.com/document/path/97392",
"text": "企业微信开发者中心",
"type": "url"
}
参数名 | 类型 | 描述 |
---|---|---|
type | string | 填url |
text | string | 链接显示文本 |
link | string | 链接跳转url |
示例
{
"id": "1",
"style": 1,
"text": "one"
}
参数名 | 类型 | 描述 |
---|---|---|
id | string | 选项ID |
style | uint32 | 选项颜色(Style) |
text | string | 选项内容 |
示例
{
"id": "14313005936863363130",
"latitude": "23.10647",
"longitude": "113.32446",
"source_type": 1,
"title": "广州塔"
}
参数名 | 类型 | 描述 |
---|---|---|
source_type | uint32 | 填1 ,表示来源为腾讯地图 。目前只支持腾讯地图来源 |
id | string | 地点ID |
latitude | string | 纬度 |
longitude | string | 经度 |
title | string | 地点名称 |
示例
{
"seq": "3",
"text": "3"
}
参数名 | 类型 | 描述 |
---|---|---|
seq | string | 序号 |
text | string | 展示的文本 |