REST API共通规格

aki发表于:2016年08月25日 17:16:41更新于:2017年11月10日 14:40:54

Index

REST API的概要

使用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输出。

  • 北京时间(JST)的2012年3月22日14点00分显示如下: 
    例)【2012-03-22T05: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的时差。

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

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

用户身份验证

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

密码验证

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

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

API令牌验证

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

  • 在请求头部添加【X-Cybozu-API-Token】,并在其后指定值。值为在各应用中发行的API令牌。

  • 一个应用最多可发行20个令牌。

  • 使用API令牌进行的操作将视为Administrator的操作进行记录。

  • 如在请求头部添加【X-Cybozu-Authorization】,将优先此验证方式。

  • 以下的REST API可使用API令牌来对应用进行操作。

    • 记录的操作(添加/更新/获取/删除)
      ※不可添加 及 更新Lookup的值。

    • 获取表单的设计信息

    • 文件的上传 / 下载

    • 获取应用

    • 更新状态

    • 批量更新状态

  • 如设置了SecureAccess,使用API令牌验证时将报错。

// API令牌为【BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92】时 X-Cybozu-API-Token:BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92

会话验证

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

关于验证时的优先顺序

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

  1. 密码验证

  2. API令牌验证

  3. 会话验证

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

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时可使用所有的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表示错误类型的代码。


KeyValue
X-ConcurrencyLimit-Limit

同一时间可连接的数量上

固定为100。

X-ConcurrencyLimit-Running当前同时连接的数量

注意事项

  • 关于请求数据以及应答数据的JSON格式,今后可能会追加新的字段或Key。

  • 关于应用、记录、回复、空间等的操作监控日志可在【监控日志列表】中查看。

  • 以下API不会被合计到请求数中。

    • 下载文件

    • 上传文件

    • 获取空间信息

    • 创建空间

    • 更新空间的正文

    • 更新空间的主题

    • 在空间的主题中发布评论 ※此功能在2016/8/14的定期维护之后可用。

    • 获取空间的成员

    • 更新空间的成员

    • 更新来宾空间的来宾成员

    • 批量添加来宾用户

    • 批量删除来宾用户

    • 删除空间

    • 获取API列表

    • 获取API 模式信息

限制事项

同时访问域

  • 每个域可使用API进行同时连接的上限为100个。

操作应用的记录的API

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

  • 一次最多可添加、更新或删除100条记录。

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

  • 如果一个请求中既包含了应用中存在的字段,也包含可了不存在的字段,则忽视不存在的字段,登记/更新存在的字段。

上传文件的API

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

应用的记录的回复API

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

其他限制事项

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

相关Tips

    您需要登录后才可以回复