kintone REST API共通规格

aki发表于:2016年08月25日 17:16:41更新于:2024年03月04日 10:02:12

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不会被转换成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令牌的发行方法,请参照此处

会话验证

要从应用于kintone的JavaScript文件中运行kintone REST API时,可使用会话验证。

使用OAuth进行验证

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

验证方式的优先顺序

优先顺序如下:

  1. 密码验证

  2. API令牌验证

  3. 使用OAuth进行验证

  4. 会话验证

来宾用户执行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必须条件

只有发送请求正文的时候才需要指定。
如下,根据请求正文格式的不同,指定的值不一样。

  • JSON 字符串时: application/json

  • multipart时: multipart/form-data

X-Cybozu-Authorization必须条件

如验证时使用的密码是“登录名:密码”通过 Base64 编码之后值,则需要指定该项。
详情请参考密码验证

X-Cybozu-API-Token必须条件

kintone 的 API 令牌

使用API令牌进行验证时需要指定该项。
详情请参考API令牌验证

Authorization必须条件

值是: 【Basic】+【通过Base64对“Basic身份验证的用户名:Basic身份验证的密码”进行编码之后的值】。
如果设置了Basic身份验证,需要指定该项。
详情情参考设置了Basic身份验证

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.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数据。

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


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

KeyValue
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表格的行数与记录列表、详细页面的渲染速度的关系(日语)

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

  • 以下字段只能通过获取记录的 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应该是日本标准时间。