企业内部开发
基础
连接微信
办公
会议
会议统计管理
企业内部开发
服务端API
文档
获取智能表格数据
查询记录
查询记录
最后更新:2024/10/28

目录

  • 查询记录
  • 参数详细说明
  •       CellValueKeyType
  •       Sort
  •       Record
  •       Value
  •       CellTextValue
  •       CellImageValue
  •       CellAttachmentValue
  •       CellUserValue
  •       CellUrlValue
  •       Option
  •       CellLocationValue
  •       CellAutoNumberValue
  • 查询记录

    本接口用于获取 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
    }

    参数说明

    参数类型是否必须说明
    docidstring文档的docid
    sheet_idstringSmartsheet 子表ID
    view_idstring视图 ID
    record_idsstring[]由记录 ID 组成的 JSON 数组
    key_typestring(CellValueKeyType)返回记录中单元格的key类型
    field_titlesstring[]返回指定列,由字段标题组成的 JSON 数组 ,key_type 为 CELL_VALUE_KEY_TYPE_FIELD_TITLE 时有效
    field_idsstring[]返回指定列,由字段 ID 组成的 JSON 数组 ,key_type 为 CELL_VALUE_KEY_TYPE_FIELD_ID 时有效
    sortObject[](Sort)对返回记录进行排序
    offsetuint32偏移量,初始值为 0
    limituint32分页大小 , 每页返回多少条数据;当不填写该参数或将该参数设置为 0 时,如果总数大于 1000,一次性返回 1000 行记录,当总数小于 1000 时,返回全部记录;limit 最大值为 1000

    权限说明

    • 自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用(accesstoken如何获取?
    • 第三方应用需具有“文档”权限
    • 代开发自建应用需具有“文档”权限

    返回示例

    {
        "errcode": 0,
        "errmsg": "ok"
    }

    参数说明

    参数类型说明
    errcodeint32错误码
    errmsgstring错误码说明
    totaluint32符合筛选条件的视图总数
    has_morebool是否还有更多项
    nextuint32下次下一个搜索结果的偏移量
    recordsObject[](Record)由查询记录的具体内容组成的 JSON 数组

    参数详细说明

    CellValueKeyType

    记录(Record)中key的类型

    枚举类型描述
    CELL_VALUE_KEY_TYPE_FIELD_TITLEkey用字段标题表示
    CELL_VALUE_KEY_TYPE_FIELD_IDkey用字段 ID 表示

    Sort

    示例
    字段标题为文本列的降序排序,字段标题为数字列的升序序排序。需要一个Sort数组:

    [
    	{
    		"field_title": "文本列",
    		"desc": true
    	},
    	{
    		"field_title": "数字列",
    		"desc": false
    	}
    ]

    在 Smartsheet 的某个表格中对记录进行排序的参数:

    参数名类型是否必须描述
    field_titlestring需要排序的字段标题
    descbool是否进行降序排序,默认值为 false

    Record

    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_idstring记录 ID
    create_timestring记录的创建时间
    update_timestring记录的更新时间
    valuesObject记录的具体内容,key 为字段标题或字段 ID ,value 详见(Value)
    creator_namestring创建者名字
    updater_namestring最后编辑者名字

     

    Value

    各种类型的字段对应的单元格的值

    字段类型单元格值类型描述
    文本(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

     

    CellTextValue

    文本类型字段的单元值类型

    参数名类型描述
    typestring内容为文本(值为text)、内容为链接(值为url)
    textstring单元格内容
    linkstring当type时url时,表示链接跳转url

    CellImageValue

    参数名类型描述
    idstring图片 ID
    titlestring图片标题
    image_urlstring图片url
    widthint32图片宽度
    heightint32图片高度

    CellAttachmentValue

    示例

    {
    	"doc_type": 2,
    	"file_ext": "SMARTSHEET",
    	"file_type": "70",
    	"file_url": "https://doc.weixin.qq.com/smartsheet/xxx",
    	"name": "智能表格",
    	"size": 3267
    }
    参数名类型描述
    namestring文件名
    sizeint32文件大小
    file_extstring文件扩展名
    file_urlstring文件url
    file_typestring文件类型,文件夹为Folder,微盘文件为Wedrive,文件夹为Folder,微盘文件为Wedrive,收集表为30,文档为50,表格是51,幻灯片为52,思维导图为54,流程图为55,智能表为70
    doc_typestring接口返回的文件类型,1为文件夹,2为文件

    CellUserValue

    参数名类型描述
    user_idstring成员ID
    tmp_external_useridstring外部用户临时id,同一个用户在不同的智能表中返回的该id不一致。可进一步通过tmp_external_userid的转换接口转换成external_userid,方便识别外部用户的身份。

    CellUrlValue

    数组类型为预留能力,目前只支持展示一个链接,建议只传入一个链接
    示例

    {
    	"link": "https://developer.work.weixin.qq.com/document/path/97392",
    	"text": "企业微信开发者中心",
    	"type": "url"
    }
    参数名类型描述
    typestringurl
    textstring链接显示文本
    linkstring链接跳转url

     

    Option

    示例

    {
    	"id": "1",
    	"style": 1,
    	"text": "one"
    }
    参数名类型描述
    idstring选项ID
    styleuint32选项颜色(Style)
    textstring选项内容

    CellLocationValue

    示例

    {
    	"id": "14313005936863363130",
    	"latitude": "23.10647",
    	"longitude": "113.32446",
    	"source_type": 1,
    	"title": "广州塔"
    }
    参数名类型描述
    source_typeuint321,表示来源为腾讯地图。目前只支持腾讯地图来源
    idstring地点ID
    latitudestring纬度
    longitudestring经度
    titlestring地点名称

    CellAutoNumberValue

    示例

    {
    	"seq": "3",
    	"text": "3"
    }
    参数名类型描述
    seqstring序号
    textstring展示的文本

     

    上一篇查询字段
    下一篇获取文档权限信息
      本节内容
    服务端API
    基础
    连接微信
    办公
    会议
    会议统计管理
    客户端API
    小程序
    基础
    连接微信
    办公
    WECOM-JSSDK
    JS-SDK
    基础
    连接微信
    办公
    更新日志
    联系我们