Index
kintone REST API的概要
使用kintone REST API，可对kintone应用的记录进行操作，也可获取表单的设计信息以及对空间进行操作。
协议
HTTPS
格式
JSON
文字编码
UTF-8
转义字符
可使用[ \ ]。
日期与时间的格式
对日期、时间、日期与时间字段（包含创建时间、更新时间字段）的数据进行处理时，需分别使用以下指定的格式。
| 字段类型 | 格式 | 说明 |
|---|---|---|
| 日期 | YYYY-MM-DD | 不会被转换成UTC。 可接受以下格式。 省略月日时将用01补全。 |
| 时间 | HH:MM | 不会被转换成UTC。 |
| 日期与时间 | 获取时 YYYY-MM-DDTHH:MM:SSZ |
|
或 YYYY-MM-DDTHH:MM:SSZ |
|
验证
验证方式
执行API的请求中，需要加上用于身份验证的头部。
密码验证
在请求头部添加【X-Cybozu-Authorization】，并在其后指定值。值为通过BASE64编码后的【登录名:密码】。
// 假设登录名为【Administrator】、密码为【cybozu】时 X-Cybozu-Authorization:QWRtaW5pc3RyYXRvcjpjeWJvenU=
API令牌验证
可使用在各应用中发行的API令牌来处理kintone REST API。关于API令牌的发行方法，请参照此处。
在请求头部添加【X-Cybozu-API-Token】，并在其后指定值。值为在各应用中发行的API令牌。
// API令牌为[BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92]时 X-Cybozu-API-Token:BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92
可指定多个API令牌。可一次性输入多个令牌，用逗号隔开；也可以在其他头部中指定。
请参考《使用多个 API令牌可以做什么》// 指定多个API令牌（用逗号隔开） // API令牌为“BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92”、“YuLjjdiOECJjV5ZDbFwh5BZoJJGDx3LtdCE1Dl7E”时 X-Cybozu-API-Token:BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92, YuLjjdiOECJjV5ZDbFwh5BZoJJGDx3LtdCE1Dl7E
一次请求最多只能指定9个API令牌，指定10个及以上将报错。
一个应用最多可发行20个令牌。
使用API令牌进行的操作将视为Administrator的操作进行记录。
如在请求头部添加【X-Cybozu-Authorization】，该验证方式优先。
以下的kintone REST API可使用API令牌来对应用进行操作。
记录
○ 获取记录（GET）/ 添加记录（POST）/ 更新记录（PUT）/ 删除记录（DELETE）
如要更新或添加lookup字段的值，请参考这篇文档。
○ 批量获取记录
○ 添加记录的回复 / 删除记录的回复
○ 更新记录的执行者
○ 更新记录的状态
○ 对多个应用的记录进行批量处理应用
○ 获取字段的列表 / 获取表单的布局
○ 添加字段 / 更改字段的设置 / 删除字段 / 更改表单的布局
○ 获取列表的设置 / 更改列表的设置（仅限列表中不含显示形式为“自定义形式”的应用）
○ 获取应用的信息
○ 获取应用的常规设置 / 更改应用的常规设置
○ 获取应用的流程管理的设置 / 更改应用的流程管理的设置
○ 获取通知条件（应用）/ 更改通知条件（应用）
○ 获取通知条件（记录）/ 更改通知条件（记录）
○ 获取通知条件（提醒）/ 更改通知条件（提醒）
○ 获取应用的访问权限 / 更改应用的访问权限
○ 获取记录的访问权限 / 更改记录的访问权限
○ 获取字段的访问权限 / 更改字段的访问权限
○ 获取应用的图表设置 / 更改应用的图表设置
○ 获取应用的分享设置 / 更改应用的分享设置
○ 将应用的设置反映到正式环境中
○ 确认应用的设置反映到正式环境中的处理进度
○ 获取表单设置信息（日语）
如果在组织之间启用访问权限设置，则只有kintone系统管理员才能发行/查看API令牌。
会话验证
要从应用于kintone的JavaScript文件中运行kintone REST API时，可使用会话验证。
在XMLHttpRequest或Fetch API上，运行POST/POT/DELETE方法的API时，请添加CSRF令牌。
使用OAuth进行验证
还可使用OAuth客户端进行身份验证。
有关详细信息，请参阅使用OAuth客户端。
验证方式的优先顺序
优先顺序如下：
密码验证
API令牌验证
使用OAuth进行验证
会话验证
来宾用户执行API时，只能使用会话验证。无法使用密码验证。
在安全设置的环境中使用API
设置IP地址限制时
若设置了IP地址限制，请使用以下任一方法执行kintone REST API。
允许运行kintone REST API的服务器的IP地址
有关允许的信息，请咨询Cybozu或经销商合作伙伴。若设置了Basic身份验证，则添加【Authorization】请求头部
有关详细信息，请参阅以下Basic身份验证。颁发未过期的客户端证书
有关详细信息，请参阅以下客户端证书。
Basic身份验证
除了IP地址限制外，若设置了Basic身份验证，请在请求头部中添加【Authorization】头部。
将【Basic】和【登录名:密码】通过BASE64编码后得到的值指定为【Authorization】头部的值。
⚬【Basic】和【登录名:密码】之间需加半角空格。
⚬【Basic】无需经过 BASE64编码。对来宾空间和来宾空间内的应用执行API时，无需添加【Authorization】头部。
// 登录名为【Administrator】、密码为【cybozu】时 Authorization:Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
客户端证书
客户端证书可以通过允许用户使用“安全访问”来颁发。
有关如何允许使用安全访问和颁发客户端证书的详细信息，请参阅设置SecureAccess。
请求的 URL 必须添加 .s。
例如：若 URL 为 https://sample.cybozu.cn ，则为 https://sample.s.cybozu.cn。若要使用其他用户的客户端证书对用户进行身份验证，请在“.cn共通管理”的“登录的安全设置”中启用“使用 API 时的身份验证”。
有关详细信息，请参阅与登录相关的安全性的概要。
设置SAML身份验证时
设置SAML验证时，可以在密码验证、API令牌验证、会话验证、使用OAuth客户端验证中使用kintone REST API。
密码验证需要使用cybozu.cn登录名和密码。
如设置了限制登录cybozu.cn时只能使用SAML身份验证，通过密码验证的方式仅cybozu.cn管理员可执行 kintone REST API。对于使用API令牌验证、会话验证和OAuth客户端验证，不受此限制。
设置双重身份验证时
启用了双重身份验证的cybozu.cn用户帐号不能使用密码验证。
请以密码身份验证以外的身份验证方法执行，或提供禁用双重身份验证的协作用户。
请求头部
根据不同的请求分别添加如下请求头部。
※使用 kintone.api() 时，无需指定请求头部 。
| 头部名称 | 必须 | 内容 |
|---|---|---|
| Host | 必须条件 | 子域名.cybozu.cn:443 |
| Content-Type | 必须条件 | 只有发送请求正文的时候才需要指定。
|
| X-Cybozu-Authorization | 必须条件 | 如验证时使用的密码是“登录名：密码”通过 Base64 编码之后值，则需要指定该项。 |
| X-Cybozu-API-Token | 必须条件 | kintone 的 API 令牌 使用API令牌进行验证时需要指定该项。 |
| Authorization | 必须条件 | 值是： 【Basic】+【通过Base64对“Basic身份验证的用户名：Basic身份验证的密码”进行编码之后的值】。 |
X-HTTP-Method-Override | 可省略 | HTTP方法(GET, POST, PUT, DELETE) 在X-HTTP-Method-Override中指定HTTP方法并发送POST请求时，将执行与指定的HTTP方法相对应的API。
※使用此头部的目的为了回避请求URI超过8KB时发生的错误(Request URI Too Large)。 ※发送的GET请求的kintone.api()URI长度超过4KB时，将自动添加X-HTTP-Method-Override头部，作为POST请求发送。 发送以下请求后，将执行批量获取API。 请求头部POST /k/v1/records.json Host: example.cybozu.com:443 X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU= Content-Type: application/json X-HTTP-Method-Override: GET请求正文 {
"app":"8",
"query":"更新时间 > \"2012-02-03T09:00:00Z\" and 更新时间 < \"2012-02-03T10:00:00Z\""
} |
| Accept-Language | 可省略 | 语言代码 如果显示语言设置为“浏览器的设置一样”。指定的语言会反映到应答正文中。 |
请求URI
https://(子域名).cybozu.cn/k/v1/(命令名).json
来宾空间内的应用
https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/(命令名).json
【命令名】根据API的种类而不同。
【v1】为固定值。
应答
如HTTP的状态代码为【200】，则表示正常；如果是其他情况，则报错结束。报错时，应答返回包含如下信息的JSON数据。
| Key | Value |
|---|---|
| message | 提示错误信息。根据用户设置的语言来显示。 |
| id | 错误ID。查询时可使用。 |
| code | 表示错误类型的代码。 |
{
"message":"非法的JSON字符串。",
"id":"1505999166-897850006",
"code":"CB_IJ01"
}所有kintone REST API应答头部都包含以下信息：
| Key | Value |
|---|---|
| X-ConcurrencyLimit-Limit | 同一时间可连接的数量上限 固定为100。 |
| X-ConcurrencyLimit-Running | 当前同时连接的数量 |
| Accept-Language | 当前同时连接的数量 |
X - ConcurrencyLimit - Limit: 100 X - ConcurrencyLimit - Running: 2
关于kintone.api()请求时的应答
当您使用kintone.api()请求kintone REST API时，传递的回调信息只是应答正文。
因此，在使用应答正文以外的信息时，需要进行kintone.api()以外的请求。
注意事项
关于请求数据以及应答数据的JSON格式，今后可能会追加字段和Key。
关于应用、记录、回复、空间等的操作监控日志可在【监控日志列表】中查看。
以下API不会被合计到请求数中。
下载文件
上传文件
获取空间信息
创建空间
更新空间的正文
更新空间的主题
在空间的主题中发布评论
获取空间的成员
更新空间的成员
更新来宾空间的来宾成员
批量添加来宾用户
批量删除来宾用户
删除空间
获取API列表
获取API schema信息
对于具有IP地址限制的环境，可以访问以下API请求以获取REST API请求。
允许访问的IP地址为访问源的API请求
使用具有访问权限的客户端证书的API请求
限制事项
同时访问域
每个域可使用API进行同时连接的上限为100个。
操作应用的记录的API
一次最多可以获取500条记录。
一次最多可添加、更新或删除100条记录。
请不要在同一个表格添加大量行。
根据应用的设计，添加大量行有可能导致负载过大，影响处理速度，比如影响在打开记录或执行REST API等操作时的速度。
关于表格的行数量对记录页面渲染速度的影响的验证结果，请参考kintone表格的行数与记录列表、详细页面的渲染速度的关系（日语）
关于表格的行数量对记录页面渲染速度的影响的验证结果，请参考kintone表格的行数与记录列表、详细页面的渲染速度的关系（日语）
添加、更新记录时，如指定了不存在的字段代码，该字段代码的处理将被忽视。
在记录添加、更新事件更改Lookup字段的值时，必须将Lookup字段的“要复制的字段”设置为记录编号或“值为唯一”。
在Lookup字段的“要复制的字段”中，选择了设置为自动计算的“单行文本框”字段，将无法更改Lookup字段的值。
上传文件的API
通过添加记录的API或更新记录的API使上传的文件不添加到记录中时，文件将在3天后被删除。保存文件所占用的空间也计算到磁盘使用量里。
应用的记录的回复API
一次最多可获取10条记录的回复。
其他限制事项
其他关于服务的限制事项请参考此处（仅提供日文）。
回复(2)
谢谢指出，已经修正。
>>北京时间（JST）的2012年3月22日14点00分显示如下：
>>例）【2012-03-22T05:00:00Z】
此例的时区是+9，而且JST应该是日本标准时间。