kintone REST API共通规格

aki发表于:2016年08月25日 17:16:41更新于:2019年06月18日 13:25:03

Index

kintone REST API的概要

使用kintone REST API,可对kintone应用的记录进行操作,也可获取表单的设计信息以及对空间进行操作。

协议

HTTPS

格式

JSON

文字编码

UTF-8

转义字符

可使用[ \ ]。

日期与时间的格式

对日期、时间、日期与时间字段(包含创建时间、更新时间字段)的数据进行处理时,需分别使用以下指定的格式。

字段类型格式说明
日期YYYY-MM-DD不会被转换成UTC。

可接受以下格式。
 * 2015
 * 2015-07
 * 2015-7
 * 2015-7-5

省略月日时将用01补全。
 * 2015 -> 2015-01-01
 * 2015-07 -> 2015-07-01
 * 2015-7 -> 2015-07-01
 * 2015-7-5 -> 2015-07-05

时间HH:MM:SS不会被转换成UTC。
日期与时间获取时 YYYY-MM-DDTHH:MM:SSZ
  • 【YYYY-MM-DD】与【HH:MM:SS】之间的【T】为固定值。

  • 【HH:MM:SS】后面的【Z】为固定值。

  • 获取时的【Z】表示UTC。使用获取列表的API时,日期与时间用UTC输出。

  • 中国时间(CST)的2012年3月22日14点00分显示如下: 
    例)【2012-03-22T06:00:00Z】

  • 如省略【T】及之后的字符,将作为UTC处理。


添加/更新时 YYYY-MM-DDTHH:MM:SS±HH:MM 
或 YYYY-MM-DDTHH:MM:SSZ


  • 【YYYY-MM-DD】与【HH:MM:SS】之间的【T】为固定值。

  • 【HH:MM:SS】后面的【Z】为固定值。

  • 添加/更新时,通过【±HH:MM】来指定与UTC的时差。

  • 中国时间(CST)的2012年3月22日14点17分显示如下: 
    例1)【2012-03-22T14:17:00+08:00】 
    例2)【2012-03-22T06:17:00Z】

  • 如省略【T】及之后的字符,将作为UTC处理。

  • 如果您添加或更新秒信息,则忽略秒信息。

    例)如果指定“2019-02-06T12:59:59Z”,它将被添加或更新为“2019-02-06T12:59:00Z”。

用户身份验证

执行API的请求中,需要加上用于身份验证的头部。

密码验证

  • 在请求头部添加【X-Cybozu-Authorization】,并在其后指定值。值为通过BASE64编码后的【登录名:密码】。

// 假设登录名为【Administrator】、密码为【cybozu】时,则值为X-Cybozu-Authorization:QWRtaW5pc3RyYXRvcjpjeWJvenU=

API令牌验证

可使用在各应用中发行的API令牌来处理kintone REST API。关于API令牌的发行方法,请参照此处

// API令牌为【BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92】时 X-Cybozu-API-Token:BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92
  • 如果在组织之间启用访问权限设置,则只有kintone系统管理员才能发行/查看API令牌。

会话验证

会话验证是指通过将Web服务器发行的会话ID保存到Cookie里的方式对用户进行识别的验证方法。

关于验证时的优先顺序

优先顺序从高到低如下所示:

  1. 密码验证

  2. API令牌验证

  3. 会话验证

来宾用户执行API时,只能使用会话验证。无法使用密码验证。

您还可以使用OAuth客户端进行身份验证。 有关详细信息, 请参阅此处

使用SAML身份验证设置

设置SAML身份验证时,可以使用kintone REST API进行密码身份验证和API令牌身份验证。
密码验证需要使用cybozu.cn登录名和密码。

Basic身份验证

  • 如已在cybozu.cn中启用了Basic身份验证,还需在请求头部追加【Authorization】头部,并在其后指定值。值为通过BASE64编码之后的【Basic】和【登录名:密码】。

    • 【Basic】和【登录名:密码】之间需加半角空格。

    • 【Basic】无需经过 BASE64编码。

  • 来宾空间内的应用除外。

// 登录名为【Administrator】、密码为【cybozu】时 Authorization:Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

请求头部

根据不同的请求分别添加如下请求头部。

头部名称内容
Host子域名.cybozu.cn:443
Content-Type

application/json

※仅在请求头部中保存JSON字符串时才需添加。

X-HTTP-Method-Override

HTTP方法(GET, POST, PUT, DELETE)

在X-HTTP-Method-Override中指定HTTP方法并发送POST请求时,将执行与指定的HTTP方法相对应的API。

  • X-HTTP-Method-Override头部仅在POST请求时有效。

  • 使用X-HTTP-Method-Override调用API时可使用所有的kintone REST API。

  • X-HTTP-Method-Override中指定的HTTP方法名称只能以大写形式使用。

※使用此头部的目的为了回避请求URI超过8KB时发生的错误(Request URI Too Large)。

※发送的GET请求的kintone.api()URI长度超过4KB时,将自动添加X-HTTP-Method-Override头部,
 作为POST请求发送。
※使用kintone.proxy()时无法保证正常运作。

发送以下请求后,将执行批量获取API

请求头部
POST /k/v1/records.json Host: example.cybozu.cn: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\"" }

请求URI

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

来宾空间内的应用

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

  • 【命令名】根据API的种类而不同。

  • 【v1】为固定值。

应答

如HTTP的状态代码为【200】,则表示正常;如果是其他情况,则报错结束。报错时,应答返回包含如下信息的JSON数据。

KeyValue
message提示错误信息。根据用户设置的语言来显示。
id错误ID。查询时可使用。
code表示错误类型的代码。
{    
    "message":"非法的JSON字符串。",
    "id":"1505999166-897850006",
    "code":"CB_IJ01" 
}


所有kintone REST API应答头部都包含以下信息:

KeyValue
X-ConcurrencyLimit-Limit

同一时间可连接的数量上

固定为100。

X-ConcurrencyLimit-Running当前同时连接的数量
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条记录。

  • 一个表格最多可添加5,000行数据。

  • 添加、更新记录时,如指定了不存在的字段代码,该字段代码的处理将被忽视。

  • 以下字段只能通过获取记录的 API获取值。不可使用添加记录的API以及更新记录的API来添加或更新值。

  • 在记录添加、更新事件更改Lookup字段的值时,必须将Lookup字段的“要复制的字段”设置为记录编号或“值为唯一”。

  • 在Lookup字段的“要复制的字段”中,选择了设置为自动计算的“单行文本框”字段,将无法更改Lookup字段的值。

上传文件的API

  • 通过添加记录的API或更新记录的API使上传的文件不添加到记录中时,文件将在3天后被删除。保存文件所占用的空间也计算到磁盘使用量里。

应用的记录的回复API

  • 一次最多可获取10条记录的回复。

其他限制事项

  • 其他关于服务的限制事项请参考此处(仅提供日文)。

相关Tips

回复(2)

  • betsy_yan

    谢谢指出,已经修正。

    引用 coca 的回复:

    >>北京时间(JST)的2012年3月22日14点00分显示如下: >>例)【2012-03-22T05:00:00Z】此例的时区是+9,而且JST应该是日本标准时间。

  • coca

    >>北京时间(JST)的2012年3月22日14点00分显示如下: 
    >>例)【2012-03-22T05:00:00Z】

    此例的时区是+9,而且JST应该是日本标准时间。

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