获取记录(GET)

aki发表于:2016年08月29日 15:21:09更新于:2019年07月11日 15:29:52

Index

获取记录(1条)

有权限查看记录的用户可通过指定记录ID来获取记录内容。

HTTP 方法

GET

URI

https://(子域名).cybozu.cn/k/v1/record.json

来宾空间内的应用

https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/record.json 

请求参数

参数名称要指定的值必须说明
app数值或字符串必须指定应用的ID。
id数值或字符串必须指定记录ID。

请求的范例

(1)使用 HTTP的查询字符串来发送参数时

使用【&】将【app】和【id】参数连起来,作为HTTP的查询字符串来发送。

查询字符串
app=8&id=100
请求头部中包含的字符串
GET /k/v1/record.json?app=8&id=100 HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
  • Content-Type头部不需要。

(2)使用 JSON格式发送参数时(JSON数据写在HTTP请求的请求正文中时)

请求的头部和正文的范例

请求头部
GET /k/v1/record.json HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json
  • 请在Content-Type中指定application/json。如不指定,JSON 无法识别,执行时将报错。

正文
{
    "app": 8,
    "id": 100
 }

应答的范例

处理成功时,以JSON格式返回记录的内容。※关于各字段的格式请参考 字段格式

{
    "record": {
        "单行文本框": {
            "type": "SINGLE_LINE_TEXT",
            "value": "测试"
        },
        "多行文本框": {
            "type": "MULTI_LINE_TEXT",
            "value": "测试\n测试2"
        },
        "文本编辑框": {
            "type": "RICH_TEXT",
            "value": "<span style=\"color: rgb(0,0,255);\">测试</span>"
        },
        "$id": {
            "type": "__ID__",
            "value": "1"
        },
        "$revision": {
            "type": "__REVISION__",
            "value": "7"
        },
        "日期": {
            "type": "DATE",
            "value": "2014-02-16"
        },
        "数值": {
            "type": "NUMBER",
            "value": "20"
        },
        "Table": {
            "type": "SUBTABLE",
            "value": [
                {
                    "id": "33347",
                    "value": {
                        "Lookup": {
                            "type": "SINGLE_LINE_TEXT",
                            "value": ""
                        },
                        "表格字符": {
                            "type": "SINGLE_LINE_TEXT",
                            "value": "测试"
                        },
                        "表格数值": {
                            "type": "NUMBER",
                            "value": "1000"
                        }
                    }
                },
                {
                    "id": "33354",
                    "value": {
                        "Lookup": {
                            "type": "SINGLE_LINE_TEXT",
                            "value": ""
                        },
                        "表格字符": {
                            "type": "SINGLE_LINE_TEXT",
                            "value": "测试2"
                        },
                        "表格数值": {
                            "type": "NUMBER",
                            "value": "2000"
                        }
                    }
                }
            ]
        },
        "日期与时间": {
            "type": "DATETIME",
            "value": "2014-02-16T08:57:00Z"
        },
        "选择用户": {
            "type": "USER_SELECT",
            "value": [
                {
                    "code": "zhou",
                    "name": "周世杰"
                }
            ]
        },
        "时间": {
            "type": "TIME",
            "value": "17:57"
        },
        "创建时间": {
            "type": "CREATED_TIME",
            "value": "2014-02-16T08:59:00Z"
        },
        "复选框": {
            "type": "CHECK_BOX",
            "value": [
                "sample1",
                "sample2"
            ]
        },
        "多选": {
            "type": "MULTI_SELECT",
            "value": [
                "sample1",
                "sample2"
            ]
        },
        "更新时间": {
            "type": "UPDATED_TIME",
            "value": "2014-02-17T02:35:00Z"
        },
        "创建人": {
            "type": "CREATOR",
            "value": {
                "code": "zhou",
                "name": "周世杰"
            }
        },
        "更新人": {
            "type": "MODIFIER",
            "value": {
                "code": "zhou",
                "name": "周世杰"
            }
        },
        "记录编号": {
            "type": "RECORD_NUMBER",
            "value": "1"
        },
        "下拉菜单": {
            "type": "DROP_DOWN",
            "value": "sample2"
        },
        "链接_Web": {
            "type": "LINK",
            "value": "https://www.cybozu.cn"
        },
        "附件": {
            "type": "FILE",
            "value": [
                {
                    "contentType": "image/png",
                    "fileKey": "20140216085901A05579B4196F4968AE26262EE889BD58086",
                    "name": "2014-01-30_No-0001.png",
                    "size": "30536"
                }
            ]
        }
    }
}

JavaScript范例

kintone REST API

var body = {
    "app": 1,
    "id": 1001
};

kintone.api(kintone.api.url('/k/v1/record', true), 'GET', body, function(resp) {
    // success
    console.log(resp);
}, function(error) {
    // error
    console.log(error);
});
XMLHttpRequest
var params = '?app=1&id=1001';
var url = 'https://{subdomain}.cybozu.cn/k/v1/record.json' + params;

var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
    if (xhr.status === 200) {
         // success
        console.log(JSON.parse(xhr.responseText));
    } else {
        // error
        console.log(JSON.parse(xhr.responseText));
    }
};
xhr.send();

批量获取记录(在查询中指定条件)

有权限查看记录的用户可在查询中指定条件来获取记录。

  • 一次最多可获取 500条记录。

  • 请求时在查询中可指定的 fields下标的范围为0~99。

  • 请求时在正文中最多可指定1000个fields。

  • 当查询中带有字符串检索时,为关键字检索。具体可以参考 “输入关键字时的注意事项”

  • 如果存在超过100,000个查询搜索结果,筛选会中断。在这种情况下,响应头部中会添加“x-cybozu-warning:Filter aborted because of too many search results.”这段。

HTTP 方法

GET

URI

https://(子域名).cybozu.cn/k/v1/records.json

来宾空间内的应用

https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/records.json 

请求参数

参数名称要指定的值必须说明
fields字符串的数组可省略指定应答中要包含的字段代码。省略时,将返回有查看权限的所有字段的值。
app数值或字符串必须指定应用的ID 。
query字符串可省略用于指定在应答中要包含的记录条件的查询字符串。查询字符串内可使用后文中提到的运算符和选项。省略时将返回有查看权限的所有记录。
totalCount布尔值或字符串可省略

要获取满足【query】参数中指定的条件的记录条数时,指定【true】。
不指定时,应答返回的totalCount值为null。

【query】参数中可使用的运算符和函数

运算符

运算符范例意思
=文本框_0 = "测试"筛选出运算符前的字段代码的值与运算符后的值一致的记录。
!=文本框_0 != "测试"筛选出运算符前的字段代码的值与运算符后的值不一致的记录。
>数值_0 > 10筛选出运算符前的字段代码的值比运算符后的值大的记录。
<数值_0 < 10筛选出运算符前的字段代码的值比运算符后的值小的记录。
>=数值_0 >= 10筛选出运算符前的字段代码的值大于或等于运算符后的值的记录。
<=数值_0 <= 10筛选出运算符前的字段代码的值小于或等于运算符后的值的记录。
in下拉菜单_0 in ("A", "B")筛选出运算符前的字段代码的值与运算符后的括号内列举的任意一个字符串一致的记录。筛选出下拉菜单或单选框等选择型字段中选择了所指定的选项的记录。左边的例子中,将筛选出下拉菜单中选择了【A】或【B】的记录。
not in下拉菜单_0 not in ("A", "B")筛选出运算符前的字段代码的值与运算符后的括号内列举的任意一个字符串不一致的记录。筛选出下拉菜单或单选框等选择型字段中没有选择所指定选项的记录。左边的例子中,筛选出下拉菜单中选择了【A】或【B】之外的选项的记录。
like文本框_0 like "测试"筛选出运算符前的字段代码的值中包含了运算符之后的值的记录。如要判断的字段类型为附件,文件名和文件内容都将作为判断对象。
not like文本框_0 not like "测试"筛选出运算符前的字段代码的值不包含运算符之后的值的记录。
or数值_0 < 10 or 数値_0 > 20上面是使用运算符对两个条件公式进行或运算。在左边的例子中,将筛选出字段代码【数值_0】比10小、或比20大的记录。
and数值_0 >= 10 and数值_0 <= 20上面是使用运算符对两个条件公式进行与运算。左边的例子中,将筛选出字段代码【数值_0】大于等于10、且小于等于20的记录。
  • 字段代码写在运算符前面。不可写在运算符后面。

  • 公式可以用【( )】括起来作为一个组。比如: (数值_0 >= 10 and 数值_0 <= 20) or (数值_1 >= 100 and 数值_1 <= 200)

  • 当查询中带有字符串检索时,为关键字检索。具体可以参考 “输入关键字时的注意事项”

函数

函数名范例内 容
LOGINUSER()创建人 in (LOGINUSER())切换成执行了API的用户。
PRIMARY_ORGANIZATION()组织 in (PRIMARY_ORGANIZATION())执行了API的用户的优先组织。
NOW()创建时间 = NOW()切换成执行了API的时间。
TODAY()创建时间 = TODAY()切换成执行了API的日期。
FROM_TODAY(数字,时间的单位)创建时间 < FROM_TODAY(5, DAYS)

时间的单位中可指定的字符串。

  • DAYS:天

  • WEEKS:周

  • MONTHS:月

  • YEARS:年

THIS_WEEK()创建时间为周日时
  • 创建时间 = THIS_WEEK(SUNDAY)

周几中可指定的字符串。
※如不指定,默认为周日。

  • SUNDAY:周日

  • MONDAY:周一

  • TUESDAY:周二

  • WEDNESDAY:周三

  • THURSDAY:周四

  • FRIDAY:周五

  • SATURDAY:周六

LAST_WEEK()创建时间 = LAST_WEEK()关于可指定的周几,详情请参考THIS_WEEK()。
THIS_MONTH([数值|格式字符])本月整月
  • 创建时间 = THIS_MONTH()

本月月末
  • 创建时间 = THIS_MONTH(LAST)

本月的20日
  • 创建时间 = THIS_MONTH(20)

切换成执行了API的月份。
参数中可指定以下值。
  • LAST:本月月末

  • 1-31的数值:所指定的本月日期
    ※如果没有给月指定日期,将按照【下个月1日】计算。

LAST_MONTH([数值|格式字符])上个月整月
  • 创建时间 = LAST_MONTH()

上个月月末
  • 创建时间 = LAST_MONTH(LAST)

上个月的20日
  • 创建时间 = LAST_MONTH(20)

切换成执行了API的上个月。
参数中可指定以下值。
  • LAST:上月月末

  • 1-31的数值:所指定的上个月的日期
    ※如果没有给月指定日期,将按照【下个月1日】计算。

THIS_YEAR()创建时间 = THIS_YEAR()切换成执行了API的年。

各字段、各系统标识符中可使用的运算符和函数列表

字段或系统标识符可使用的运算符可使用的函数
记录编号= != > < >= <= in not in
$id= != > < >= <= in not in
创建人

in not inLOGINUSER()
创建时间= != > < >= <=NOW() 
TODAY()
FROM_TODAY()
THIS_WEEK()
LAST_WEEK() 
THIS_MONTH() 
LAST_MONTH() 
THIS_YEAR()
更新人
in not inLOGINUSER()
更新时间= != > < >= <=NOW() 
TODAY()
FROM_TODAY()
THIS_WEEK()
LAST_WEEK() 
THIS_MONTH() 
LAST_MONTH() 
THIS_YEAR()
单行文本框、链接= != in not in like not like--
数值= != > < >= <= in not in--
多行文本框like not like--
文本编辑框like not like--
复选框in not in--
单选框in not in--
下拉菜单in not in--
多选in not in--
附件like not like--
日期= != > < >= <=

TODAY()
FROM_TODAY()
THIS_WEEK()
LAST_WEEK() 
THIS_MONTH()
LAST_MONTH()
THIS_YEAR()

时间= != > < >= <=--
日期与时间= != > < >= <=NOW() 
TODAY() 
FROM_TODAY()
THIS_WEEK()
LAST_WEEK() 
THIS_MONTH() 
LAST_MONTH() 
THIS_YEAR()
选择用户
in not inLOGINUSER()
选择组织in not in

PRIMARY_ORGANIZATION()

选择组in not in--
状态= != in not in--

Lookup

与要复制的字段类型相同与要复制的字段类型相同
关联记录列表与要参照的应用的字段类型相同与要参照的应用的字段类型相同

查询中包含表格内的字段、关联记录列表的字段时的注意事项

查询中包含表格内的字段、关联记录列表的字段时,不可使用【=】、【!=】,而是使用【in】、【not in】运算符。

包含在关联记录列表内的字段的指定方法

条件中指定关联记录列表内的字符时,按以下格式指定字段。

关联记录列表的字段代码.关联给什么字段

关联记录列表的字段代码的指定范例

  • 关联记录列表的字段代码为【企业管理】

  • 企业管理中包含的【企业名称】为【才望子】

  • 企业管理中包含的【所在地】字段包含【东京都】

【query】参数的范例
企业管理.企业名称 in ("才望子") and 企业管理.所在地 like "东京都"

指定记录编号字段

除了使用筛选条件和order by来指定记录编号的字段代码,还可以使用$id指定记录编号字段。
指定关联记录列表内的记录编号字段时,可使用【关联记录列表的字段代码.$id】来指定。

【query】参数中可使用的选项

选项范例说明
order byorder by 更新时间 asc

可通过在本选项后指定字段代码的方式来指定记录的输出顺序。在字段代码的后面指定【asc】时升序,指定【desc】时降序。

多个项目排序时,以逗号分隔“字段代码排列顺序”。

 示例:“order by 字段代码1 desc,字段代码2 asc”

省略时,将按记录ID的降序返回。

limitlimit 20在本选项后面指定数值,将输出同等数量的记录。左边的列子中,将输出前20条记录。省略时默认为100、上限为500。
offsetoffset 30本选项之后指定数字为要跳过的记录条数。只筛选出其之后的记录。在左边的列子中,跳过前面30条记录,从第31条起输出记录。无上限。

上面的运算符、选项可以组合使用。

请求的范例

使用HTTP的查询字符串发送参数时

使用【&】将【app】【query】【fields】这三个参数连起来作为HTTP的查询字符串发送。查询的每个参数名称和值都需要进行URL编码。

获取记录的条件的范例
  • 应用ID为【8】

  • 【query】参数的值为【更新时间 > "2012-02-03T09:00:00+0800" and 更新时间 < "2012-02-03T10:00:00+0800" order by 记录编号 asc limit 10 offset 1】

  • 要输出的字段为【记录编号】【创建时间】【下拉菜单】

  • 获取满足所指定条件的记录的条数

HTTP 的查询字符串的范例
app=8&query=%E6%9B%B4%E6%96%B0%E6%97%B6%E9%97%B4%20%3E%20%222012-02-03T09%3A00%3A00%2B0800%22%20and%20%E6%9B%B4%E6%96%B0%E6%97%B6%E9%97%B4%20%3C%20%222012-02-03T10%3A00%3A00%2B0800%22%20order%20by%20%E8%AE%B0%E5%BD%95%E7%BC%96%E5%8F%B7%20asc%20limit%2010%20offset%201&fields%5B0%5D%3D%E8%AE%B0%E5%BD%95%E7%BC%96%E5%8F%B7&fields%5B1%5D%3D%E5%88%9B%E5%BB%BA%E6%97%B6%E9%97%B4&fields%5B2%5D%3D%E4%B8%8B%E6%8B%89%E8%8F%9C%E5%8D%95
请求头部的范例
GET /k/v1/records.json?app=8&query=%E6%9B%B4%E6%96%B0%E6%97%B6%E9%97%B4%20%3E%20%222012-02-03T09%3A00%3A00%2B0800%22%20and%20%E6%9B%B4%E6%96%B0%E6%97%B6%E9%97%B4%20%3C%20%222012-02-03T10%3A00%3A00%2B0800%22%20order%20by%20%E8%AE%B0%E5%BD%95%E7%BC%96%E5%8F%B7%20asc%20limit%2010%20offset%201&fields%5B0%5D%3D%E8%AE%B0%E5%BD%95%E7%BC%96%E5%8F%B7&fields%5B1%5D%3D%E5%88%9B%E5%BB%BA%E6%97%B6%E9%97%B4&fields%5B2%5D%3D%E4%B8%8B%E6%8B%89%E8%8F%9C%E5%8D%95 HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
  • Content-Type头部不需要。

使用JSON格式发送参数时(JSON数据写在HTTP 请求的请求正文中)

请求的头部和正文的范例

请求头部
GET /k/v1/records.json HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json
Content-Length: 234
正文
{
    "app": 8,
    "query": "更新时间 > \"2012-02-03T09:00:00+0800\" and 更新时间 < \"2012-02-03T10:00:00+0800\" order by 记录编号 asc limit 10 offset 1",
    "fields": ["记录编号", "创建时间", "下拉菜单"]
}
  • 请在Content-Type中指定application/json。如不指定,JSON 无法识别,执行时将报错。

  • 字符串的值使用【\(反斜杆)】转义后的【"(双引号)】括起来。

应答的范例

使用JSON格式返回包含指定字段的记录。※关于各字段的格式请参考 字段格式

{
    "records": [
        {
            "记录编号": {
                "type": "RECORD_NUMBER",
                "value": "1"
            },
            "创建时间": {
                "type": "CREATED_TIME",
                "value": "2012-02-03T09:10:00Z"
            },
            "下拉菜单": {
                "type": "DROP_DOWN",
                "value": null
            }
        },
        {
            "记录编号": {
                "type": "RECORD_NUMBER",
                "value": "2"
            },
            "创建时间": {
                "type": "CREATED_TIME",
                "value": "2012-02-03T09:22:00Z"
            },
            "下拉菜单": {
                "type": "DROP_DOWN",
                "value": null
            }
        }
    ],
    "totalCount": null
}

JavaScript范例

kintone REST API

var body = {
    "app": 1,
    "query": "更新时间 > \"2012-02-03T09:00:00+0800\" and 更新时间 < \"2012-02-03T10:00:00+0800\" order by 记录编号 asc limit 10 offset 1",
    "fields": ["记录编号", "创建时间", "下拉菜单"]
};

kintone.api(kintone.api.url('/k/v1/records', true), 'GET', body, function(resp) {
    // success
    console.log(resp);
}, function(error) {
    // error
    console.log(error);
});
XMLHttpRequest
var params = '?app=1&query=' +
    encodeURIComponent('更新时间 > "2012-02-03T09:00:00+0800" and 更新时间 < "2012-02-03T10:00:00+0800" order by 记录编号 asc limit 10 offset 1') + 
    '&fields[0]=' + encodeURIComponent('记录编号') +
    '&fields[1]=' + encodeURIComponent('创建时间') +
    '&fields[2]=' + encodeURIComponent('下拉菜单');
var url = 'https://{subdomain}.cybozu.cn/k/v1/records.json' + params;

var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
    if (xhr.status === 200) {
        // success
        console.log(JSON.parse(xhr.responseText));
    } else {
         // error
        console.log(JSON.parse(xhr.responseText));
    }
};
xhr.send();

限制事项

请参考限制事项 。

关联的文章


回复(10)

  • betsy_yan

    指定搜索张三:

    https://(子域名).cybozu.cn/k/v1/records.json?app=指定APP的ID&query=Text in ("张三")

    模糊搜索带有张三字样:

    https://(子域名).cybozu.cn/k/v1/records.json?app=指定APP的ID&query=Text like "张三"

    引用 梦&蒲公英 的回复:

    query条件中需要表格中的某个字段等于某个值,比如我表格中单行文本框的字段代码为Text,我要筛选单行文本框中的内容为张三的那条记录,我应该怎么写query呢

  • 梦&蒲公英

    query条件中需要表格中的某个字段等于某个值,比如我表格中单行文本框的字段代码为Text,我要筛选单行文本框中的内容为张三的那条记录,我应该怎么写query呢

  • cybozu
    你好, 总条数的话请加这个参数:
    totalCount布尔值或字符串可省略

    要获取满足【query】参数中指定的条件的记录条数时,指定【true】。
    不指定时,应答返回的totalCount值为null。

    引用 追梦人 的回复:

    请问, 列表的总条数应该如何来获取?

  • 追梦人

    请问, 列表的总条数应该如何来获取?

  • betsy_yan

    是要下载EXCEL文件吗?之前的文章“https://developer.kintone.io/hc/en-us/articles/360012122753”写了怎么制作下载按钮了,请参考。

    引用 closer 的回复:

    请问我怎么下载文件

  • closer

    请问我怎么下载文件

  • betsy_yan

    关于导出到EXCEL的文章你可以参考:

    https://developer.kintone.io/hc/en-us/articles/360012122753

    中文网站暂时还没有这篇文章,我们会加快速度给大家带来最新的文章

    引用 closer 的回复:

    请问,有导出数据到Excel文件的帮助文档吗

  • closer

    请问,有导出数据到Excel文件的帮助文档吗

    引用 betsy_yan 的回复:

    你好,你可以看一下这篇文章“如何将汇总后的数据下载到CSV文件?”希望能帮到你

  • betsy_yan

    你好,你可以看一下这篇文章“如何将汇总后的数据下载到CSV文件?

    希望能帮到你

    引用 closer 的回复:

    想请问,我要怎么将通过接口获取到的数据导出Excel文件中。

  • closer

    想请问,我要怎么将通过接口获取到的数据导出Excel文件中。

注意:贴代码时请注意格式并使用"代码语言"
您需要登录后才可以回复