kintone REST API 请求

cybozu发表于:2016年09月19日 16:09:49更新于:2022年11月07日 17:58:53

 Index

发送kintone REST API请求

可使用kintone REST API以及User API。

  • PC端和移动端都可以使用。

  • 本API是异步请求。想处理同步的时候,请参照这里的Tips。

  • 不可以使用kintone REST API的上传文件API下载文件API
    使用这些API的时候,请取得CSRF令牌,通过HTTP来执行请求。

  • 不可以使用User API中的上传文件API(日文)、URI末尾非.json的API(导出用户API(CSV))(日文)。

  • 使用 kintone.api() 时,无需指定请求头部

函数

kintone.api(pathOrUrl, method, params, opt_callback, opt_errback)

参数

参数名称要指定的值必须说明
pathOrUrl字符串必须kintone REST API的路径,或者用kintone.api.url 里指定的URL。 例) API 的URL为  https://(子域名).cybozu.cn/k/v1/xxx.json 的时候,请指定 "/k/v1/xxx" 。  如要在来宾空间里的应用中运行,请指定 kintone.api.url("/k/v1/xxx", true)。
method字符串必须HTTP方法。 可指定 GET,POST,PUT,DELETE。
params对象必须通过对象指定要传给 API 的参数。
opt_callback函数可省略

调用 API成功时的回调函数。参数类型是对象。
参数省略的情况下,默认返回 kintone.Promise 对象,通过传递给 callback 的参数来解决。

opt_errback函数可省略

调用 API失败时的回调函数。参数是response返回的JSON。 当response无法作为JSON返回时,则返回字符串。
callback省略的情况下,默认返回kintone.Promise对象,通过传递给 errback的参数来抛出错误。

返回值

省略参数callback时,返回 kintone.Promise 对象。

※ 通过return此kintone.Promise对象,可等待kintone.api()执行完之后再进行以下处理。

关于可支持kintone.Promise的事件请参考此处。 

指定callback的时候,没有返回值。

可使用的页面

  • 所有页面(包括应用、空间)

范例

使用回调函数的编码方式

// 使用回调函数的编码方式
const params = {    
  app: 1,    
  id: 1    
};

kintone.api(kintone.api.url('/k/v1/record.json', true), 'GET', params, (resp) => {    
  // success:显示记录编号    
  window.alert(resp.record.record_no.value);    
}, (resp) => {    
  // error:出错的场合显示错误信息    
  let errmsg = '获取记录时出错。';    
  // 当response里包含错误信息时,显示错误信息    
  if (resp.message !== undefined) {    
  errmsg += '\n' + resp.message;    
  }    
  window.alert(errmsg);    
});


使用kintone.Promise 对象的编码方式

// 使用kintone.Promise 对象的编码方式    
const params = {    
  app: 1,    
  id: 2    
};

kintone.api(kintone.api.url('/k/v1/record.json', true), 'GET', params).then((resp) => {    
  // success:显示记录编号   
  window.alert(resp.record.record_no.value);    
}).catch((error) => {    
  // error:出错的场合显示错误信息    
  let errmsg = '获取记录时出错。';    
  // 当response里包含错误信息时,显示错误信息   
  if (error.message !== undefined) {    
    errmsg += '\n' + error.message;    
  }
  window.alert(errmsg);    
});

获取URL(没有查询字符串)

根据省略形式的API路径生成URL。

函数

kintone.api.url(path,opt_detectGuestSpace)

参数

参数名称要指定的值必须说明
path字符串必须kintone REST API的路径是以 / 开头的字符串。 例)API 的URL为 https://(子域名).cybozu.cn/k/v1/xxx.json的情况下,指定"/k/v1/xxx"。
opt_detectGuestSpace布尔值可省略来宾空间指定true的时候,返回执行REST API时所必须的来宾空间用URI。默认是false。

返回值

URL 字符串。

可使用的页面

  • 所有页面(包含应用、空间)

范例

const url = kintone.api.url('/k/v1/records.json', true);    
console.log(url);

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

// 来宾空间   
// https://(子域名).cybozu.cn/k/guest/16/v1/records.json

获取URL(附有查询字符串)

获取 API的路径和参数,生成带有查询字符串的URL。

函数

kintone.api.urlForGet(path, params,opt_detectGuestSpace)

参数

参数名称可指定的值必须说明
path字符串必须kintone REST API的路径是以 / 开头的字符串。 例) API 的URL为 https://(子域名.cybozu.cn/k/v1/xxx.json的情况下,指定"/k/v1/xxx" 。
params对象必须指定参数对象。
opt_detectGuestSpace布尔值可省略来宾空间指定true的时候,返回执行REST API时所需的来宾空间用的URI。默认是false。

返回值

带有查询字符串,参数是URL编码后的URL字符串。

// 当参数被以对象或数组的形式传递时,查询字符串将以以下的形式展开。
// params = {app: 4, fields: ['record_no']}
https://{subdomain}.cybozu.cn/k/v1/records.json?app=4&fields[0]=record_no

可使用的页面

  • 所有页面(包含应用、空间)

范例

const urlForGet = kintone.api.urlForGet('/k/v1/records.json', {app: 4, fields: ['record_no']});
console.log(decodeURIComponent(urlForGet));

// https://(子域名).cybozu.cn/k/v1/records.json?app=4&fields[0]=record_no

获取CSRF令牌

所有HTTP方法为POST,PUT,DELETE的API都可以使用。

  • PC端和移动端都可以使用。

  • HTTP方法为 GET 的API 不需要 CSRF 令牌。

函数

kintone.getRequestToken()

参数

返回值

字符串

可使用的页面

  • 所有页面(包括应用、空间)

有效期限

最后一次登录时间开始 86400秒(1天)

范例

const token = kintone.getRequestToken();
console.log(token);

// 获取值的例子
// "72A0C9714B6E1C086D24BBC11A5C3508"

API 通过query来接收参数的例子

https://(子域名).cybozu.cn/k/v1/records.json?__REQUEST_TOKEN__=72A0C9714B6E1C086D24BBC11A5C3508

API 通过request body来接收参数的例子

{
    "__REQUEST_TOKEN__": "72A0C9714B6E1C086D24BBC11A5C3508"
}

API实行时指定以下的request header。

header名内容
X-Requested-WithXMLHttpRequest
Content-Typeapplication/json