kintone REST API 请求

cybozu发表于:2016年09月19日 16:09:49更新于:2019年09月19日 17:59:04

 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(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 对象。
指定callback的时候,没有返回值。

可使用的页面

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

范例

使用回调函数的编码方式


// 使用回调函数的编码方式
var params = {
    app: 1,
    id: 1
};
kintone.api(kintone.api.url('/k/v1/record', true), 'GET', params, function(resp) {
    // success:显示记录番号
    alert(resp['record']['record_no']['value']);
}, function(resp) {
    //error:出错的场合显示错误信息
    var errmsg = '取得记录时出错。';
    // 当response里包含错误信息的时候,显示错误信息
    if (resp.message !== undefined) {
        errmsg += '\n' + resp.message;
    }
    alert(errmsg);
});

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


// 使用kintone.Promise 对象的编码方式
var params = {
    app: 1,
    id: 2
};
kintone.api(kintone.api.url('/k/v1/record', true), 'GET', params).then(function(resp) {
    // success:显示记录番号
    alert(resp['record']['record_no']['value']);
}, function(error) {
    //error:出错的场合显示错误信息
    var errmsg = '取得记录时出错。';
    // 当response里包含错误信息的时候,显示错误信息
    if (error.message !== undefined) {
        errmsg += '\n' + error.message;
    }
    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 字符串。

可使用的页面

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

范例

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

//来宾空间    
//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 = {foo: 'bar', record: {key: ['val1', 'val2']}}
foo=bar&record.key[0]=val1&record.key[1]=val2

可使用的页面

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

范例

var urlForGet = kintone.api.urlForGet('/k/v1/records', {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天)

范例

var 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

    注意:贴代码时请注意格式并使用"代码语言",与本文无关的问题请至“讨论社区”提问。
    您需要登录后才可以回复