2. 接口-获取记录（api-get-records）
1. 接口地址
接口请求域名：https://api.vika.cn
请求方法：GET
GET /datasheets/{datasheetId}/records
2. 接口描述
获取指定维格表的若干条记录。
3. 输入参数说明
注意：参数对大小写敏感，注意驼峰写法。
| 参数名称 | 参数类型 | 说明 |
|---|---|---|
| datasheetId (String) | Path | 维格表ID |
| recordIds (Array Of Strings) | Query | （选填）recordIds 数组。如果附带此参数，则返回参数中指定的 records 数组。 返回值按照传入数组的顺序排序。此时无视筛选、排序。无分页，每次最多查询 1000 条 |
| viewId (String) | Query | （选填）视图 ID ，默认为维格表中第一个视图。 请求会返回视图中经过视图中筛选/排序后的结果，可以搭配使用fields参数过滤不需要的字段数据 |
| fields (Array Of Strings) | Query | （选填）指定要返回的字段（默认为字段名, 也可以通过 fieldKey 指定为字段 Id ）。 如果附带此参数，则返回的记录合集将会被过滤，只有指定的字段会返回。 例： fields[]=年龄&fields[]=性别&fields[]=姓名 |
| maxRecords (Int) | Query | （选填）限制返回记录的总数量。 如果该值小于表中实际的记录总数，则返回的记录总数会被限制为该值。 |
| pageNum (Int) | Query | （选填）指定分页的页码，默认为 1 。 与参数 pageSize 配合使用。 |
| pageSize (Int) | Query | （选填）指定每页返回的记录总数，默认为 100 。 此参数只接受 1-1000 的整数。 |
| sort (Array Of Objects) | Query | （选填）对指定维格表的记录进行排序，由多个“排序对象”组成的数组。 一个 Sort Object 的结构为 {field: 'fieldname', order: 'asc/desc'} 。注：此参数指定的排序条件将会覆盖视图里的排序条件。 例： sort[0][field]=date&sort[0][order]=asc |
| filterByFormula (String) | Query | （选填）使用公式作为筛选条件，返回匹配的记录，访问《一分钟上手公式》了解公式使用方式 |
| cellFormat (String) | Query | （选填）单元格值类型，默认为 json ，指定为 string 时所有值都将被自动转换为 string 格式。 |
| fieldKey (String) | Query | （选填）指定 field 的查询和返回的 key ，默认使用列名 'name' 。 指定为 'id' 时将以 fieldId 作为查询和返回方式（使用 id 可以避免因修改列名而导致的代码失效问题） |
4. 示例
示例1：获取维格表ID为 dstWUHwzTHd2YQaXEE ，视图 viw4mnkqkaqdh 下的 5 条数据，并且使用 filterByFormula 参数，筛选符合{性别}='男孩'的记录。
请求示例（cURL）：
curl -X GET \
"https://api.vika.cn/fusion/v1/datasheets/dstWUHwzTHd2YQaXEE/records?viewId=viw4mnkqkaqdh&maxRecords=5&filterByFormula=%7B%E6%80%A7%E5%88%AB%7D%3D'%E7%94%B7%E5%AD%A9'" \
-H "Authorization: Bearer {你的 API Token}"
返回示例：
正常情况下，维格表服务端会返回下述JSON数据包
{
"code": 200,
"success": true,
"data": {
"total": 1,
"pageNum": 1,
"pageSize": 1,
"records": [
{
"recordId": "recbaKEuZ9gDC",
"createdAt": 1600431195000,
"fields": {
"体重": "90公斤",
"肩高": "65厘米",
"登记日期": "2020/09/15 17:14",
"胸围": "87厘米",
"体长": "1.2米",
"拍照": [
{
"id": "atcUJME9gbmFQ",
"name": "1.png",
"size": 207456,
"mimeType": "image/png",
"token": "space/2020/09/21/f577af8bd73f44c79dfc28408eaeff83",
"width": 374,
"height": 347,
"url": "https://s1.vika.cn/space/2020/09/21/f577af8bd73f44c79dfc28408eaeff83"
}
],
"登记员": [
{
"unitId": "1286184164530659329",
"unitType": 3,
"unitName": "Bruce · K",
"avatar": "https://s1.vika.cn/public/2020/08/03/574bcee4cfc54f6fbb7d686bb237f6f3"
}
],
"性别": "男孩",
"昵称": "安安",
"年龄": "5岁"
}
}
]
},
"message": "SUCCESS"
}
返回对象说明：
| 参数名称 | 数据类型 | 说明 |
|---|---|---|
| code | Int | 业务状态码，200表示业务请求成功，其他状态码详见《附录：全局业务状态码列表》 |
| success | Boolean | 全局状态值，如果为false，则表示发生了业务错误或接口调用错误。 |
| message | String | 返回信息，执行错误时返回错误信息。 |
| data | Object | 返回的业务数据体 |
| - total | Number | 符合筛选条件的总记录数 |
| - pageNum | Number | 当前的分页页码 |
| - pageSize | Number | 每页返回的实际记录数。 如果请求时指定 pageSize=100 ，但实际记录数只有 35 ，则返回 35 。 |
| - records | Array Of Record Objects | 见下方 Record Object 的说明 |
Record Object 说明：
| 属性 | 数据类型 | 说明 |
|---|---|---|
| recordId | String | 新记录的唯一 ID （注意：只在表内唯一） |
| createdAt | Int | 新记录的创建时间，精确到毫秒的时间戳 |
| fields | Object | 新记录的字段数据，具体的类型介绍请参考《附录：字段类型列表》 |