kintone 插件JavaScript API

cybozu发表于:2016年11月25日 14:18:31更新于:2019年08月07日 17:08:48

Index

获取插件的设置信息

获取指定插件的设置信息。

函数

kintone.plugin.app.getConfig(pluginId)

参数

参数类型必须说明
pluginId字符串必须

指定获取设置信息的插件ID。

返回值

插件的设置信息,以键名和键值配对的对象形式返回。
在无法执行此函数的页面里执行此函数的话,将返回null。

返回值的范例

{
    "key1": "value1",
    "key2": "value2"
}

可运行页面

可在以下这些页面运行。

PC端

  • 记录列表

  • 记录详情

  • 记录添加

  • 记录编辑

  • 记录打印 

  • 图表

  • 各个插件的设置页面

智能手机端

  • 记录列表

  • 记录详情

  • 记录添加

  • 记录编辑

范例代码

var config = kintone.plugin.app.getConfig('mjjfipoklghomcgafnajfibfgllhpocm');
console.log(config);

保存插件的设置

以键名和键值配对的对象方式,保存插件的设置信息。
默认仅保存最后保存的设置。

函数

kintone.plugin.app.setConfig(config,callback)

参数

参数类型必须说明
config对象必须

指定以键名和键值配对的对象方式,指定要保存到插件的设置信息。键值用ASCII转换文字指定,值为字符串。

例: { "key1": "value1", "key2": "value2" }

callback函数
指定设置保存完了后运行的函数。
callback 函数省略的情形,一旦设置保存完了后,就转到插件列表页面。

返回值

无。

可运行页面

各个插件的设置页面

范例代码

var config = {
    "key1": "value1",
    "key2": "value2"
};
kintone.plugin.app.setConfig(config);

制限事項

插件设置里可保存的容量限制如下:

  • 1个应用里最多可设置的20个插件。

  • 每个插件的kintone.plugin.app.setConfig里可设置的key-value的value值的合计最多为256KB。

在插件里执行外部的API

接下来说明的是在插件里执行外部的API的方法。

执行外部API时,如使用了认证信息等需要加密的信息时,在执行API之前,需要预先在插件里保存好所需信息。
信息保存到插件的方法,请参考以下项目。

函数

kintone.plugin.app.proxy(pluginId, url, method, headers, data, callback, error)

参数

参数类型必须说明
pluginId对象必须指定执行API的插件ID。
url字符串必须指定执行API的URL。
method字符串必须指定执行API时使用的HTTP 方法,可指定GET, POST, PUT, DELETE中任一个。
headers对象必须指定请求头。
除了这里指定的参数,使用函数 “kintone.plugin.app.setProxyConfig()” 保存在插件里的参数也一并发送。
data对象/字符串必须

指定请求数据。
除了这里指定的数据,使用函数 “kintone.plugin.app.setProxyConfig()” 保存在插件里的数据也一并发送。

callback函数
可省略

指定请求完了后要执行的函数。函数的参数为以下3种信息。

  • 第一参数:应答主体(字符串)

  • 第二参数:状态代码(数值)

  • 第三参数:应答头(对象)

省略的情况下,默认返回kintone.Promise对象,里面是含有应答主体 (字符串)、状态代码(数值)、应答头(对象)信息的数组。

error函数
可省略

指定请求失败时执行的函数。
函数的参数传递的是 proxy API的应答主体(字符串)。

callback省略的情况下,默认返回kintone.Promise对象,在proxy API的应答主体 (字符串)里含有出错信息。

返回值

省略参数的callback时,返回 kintone.Promise对象。
参考: 添加事件句柄

指定callback的时候则无返回值。

 

可运行页面

可在以下这些页面运行。

PC端

  • 记录列表

  • 记录详情

  • 记录添加

  • 记录编辑

  • 记录打印

  • 图表

智能手机端

  • 记录列表

  • 记录详情

  • 记录添加

  • 记录编辑

  • 图表

范例代码

使用callback的写法

// 使用callback的写法
kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'GET', {}, {}, function(body, status, headers) {
    //success
    console.log(status, JSON.parse(body), headers);
}, function(error) {
    //error
    console.log(error);  // 显示proxy API的应答主题(字符串)
});

补充

运行外部API时使用的设置信息

运行外部API时发送的请求头

  • 执行外部API时所指定的请求头,是在使用kintone.plugin.app.proxy指定的请求头的基础上,再加上满足保存后的信息加到请求里的条件的设置信息的请求头。

    例:使用kintone.plugin.app.setProxyConfig,在请求头指定{k1: 'v1'} ,使用kintone.plugin.app.proxy在请求头指定{k2: 'v2'} 的情形。
    →外部API执行时的请求头为 {k1: 'v1', k2: 'v2'} 。

运行外部API时发送的数据

  •  HTTP方法为POST/PUT时,执行外部API时要指定的数据为:【使用kintone.plugin.app.proxy指定的数据(请求本体)】+【 满足保存后的信息加到请求里的条件的设置信息数据】。(和请求头一样)但是、使用kintone.plugin.app.proxy指定的数据类型只能为Object的情形下,才会添加设置信息的数据,在字符串的情形下,不会添加。

  • HTTP方法为GET/DELETE时,使用kintone.plugin.app.proxy指定的外部API的URL的QueryString末尾上,以QueryString形式(&key=urlencode(value)的形式)加上满足保存后的信息加到请求里的条件的设置信息数据。

    使用kintone.plugin.app.proxy指定的外部API的URL里,如果不包含表示QueryString开始的 '?' 时,就一起添加。

    例)使用kintone.plugin.app.setProxyConfig,在数据里指定 {k1: 'v1', k2: 'v2'} ,使用kintone.plugin.app.proxy,在外部API的URL里指定 'https://api.github.com?k=v' 的情形。   
    →外部API执行时的URL为 'https://api.github.com?k=v&k1=v1&k2=v2' 。

多个设置信息里有重复KEY的情形

  • 多个设置信息满足保存后的信息加到请求里的条件,且各个设置信息之间的请求头部的KEY重复的时候,以外部API的URL一致的、且长度较长的为优先。HTTP方法为POST/PUT时的请求本体(就像上面所说的,类型只能为Object)、GET/DELETE时的QueryString也一样。

    例)使用kintone.plugin.app.setProxyConfig,在外部API的URL里指定https://api.github.com/ 在请求头里指定 {k1: 'v1', k2: 'v2'} 。另外,在外部API的URL里指定 'https://api.github.com/',在请求头里指定 {k2: 'v2-1', k3: 'v3'} 的情形
    →外部API的URL里指定的 'https://api.github.com/' 在执行外部API的时候请求头为 {k1: 'v1', k2: 'v2-1', k3: 'v3'} 。

设置信息和kintone.plugin.app.proxy之间有重复KEY的情形

  • 从设置的请求信息里拿到的请求头的KEY,包含在使用kintone.plugin.app.proxy指定的请求头里的时候,以前者为优先。HTTP方法为POST/PUT时的请求本体(就像上面所说的,类型只能为Object)也同样。GET/DELETE的情形不校验KEY是否重复。

    例)使用kintone.plugin.app.setProxyConfig,在请求头里指定 {k1: 'v1', k2: 'v2'} ,使用kintone.plugin.app.proxy,在请求头里指定 {k2: 'v2-1', k3: 'v3'} 的情形。
    →外部API执行时的请求头为 {k1: 'v1', k2: 'v2', k3: 'v3'} 。

注意事项

  • 使用url指定不存在的服务器时、应答返回状态码为「503」(DNS Cache Missing)的错误。

限制事项

  • 当你发送的HTTP请求为POST / PUT时,由于header里“Content-Length”和“Transfer-Encoding”会在内部自动添加,因此用户在发起请求时无需手动设置它们,否则将导致出错。

将执行外部API所需信息保存到插件

下面说明将执行外部API时所需的信息保存到插件的方法。
外部API执行的时候,使用认证信息等需加密的信息时,在执行API之前,需要预先在插件里保存好所需信息。保存到插件的信息,在该插件里执行函数 “kintone.plugin.app.proxy()” 的话,这个插件保存的信息就会加到请求的头和数据里。
在插件里保存信息的处理,在只有应用管理者可查看的页面(各插件的设置页面)里实行。这样,可以防止应用的使用者接触到插件里保存的信息。

保存形式

在插件里,使用以下的组合来保存信息。

  • URL

  • HTTP 方法
    GET、POST、PUT、DELETE 的任一个。

  • 要保存的信息
    以键名和键值配对的对象形式保存下面的信息。

    • 请求头

    • 请求数据

如果已经保存过指定URL 加HTTP 方法的组合信息,则覆盖保存。

保存后的信息加到请求里的条件

插件中保存的信息,将加到使用了函数 “kintone.plugin.app.proxy()” 并满足以下所有条件的请求里。

  • 同一个应用

  • 同一个插件

  • 同一个HTTP方法

  • 执行的API URL的前端匹配*1

*1 关于执行的API URL的前端匹配
比如,使用各个函数,指定下面的URL的时候,因为URL为前端匹配,所以会将插件里保存的信息加到请求里。

  • 保存信息到插件里的函数 “kintone.plugin.app.setProxyConfig()”
    https://api.example.com/

  • 执行API 的函数 “kintone.plugin.app.proxy()”
    https://api.example.com/operate.json

URL 区分大小写。
在插件里保存多个设置的场合,将优先与API执行时指定的URL匹配文字最多的URL。
比如,使用各个函数,指定下面的URL和请求头。

  • 保存信息到插件里的函数「kintone.plugin.app.setProxyConfig()」

    • 设置 1
      URL:https://api.example.com/
      头部:{"Content-Type": "application/x-www-form-urlencoded"}

    • 设置 2
      URL:https://api.example.com/rest/
      头部:{"Content-Type": "application/json"}

  • 执行API的函数「kintone.plugin.app.proxy()」
    URL:https://api.example.com/rest/operate.json
    头部:{}

当指定上面的URL和请求头的时候,API执行时发送的请求头为 {"Content-Type": "application/json"}。

函数

kintone.plugin.app.setProxyConfig(url, method, headers, data, callback)

参数

参数类型必须说明
url字符串必须

指定执行API的URL的一部分,或者全部。

关于将插件里保存的信息加到API请求里的条件,之前已讲过,具体可请参考下面的链接。
保存后的信息加到请求里的条件

method字符串必须
执行API 使用的HTTP方法,可以指定GET、POST、PUT、DELETE 的任何一个。
headers对象
必须
指定加到API 的请求头里的参数。
这里指定的参数,如果和用API 的执行函数 “kintone.plugin.app.proxy()” 指定的参数重复的情形,以这里指定的参数为优先。
※什么也不指定的情形为{}。
data对象
必须
以键名和键值匹配的对象形式,指定加到API请求数据里的数据。
当指定数据为对象型时,需要键名和键值匹配。
这里指定的键名,如果和用API 的执行函数 “kintone.plugin.app.proxy()” 指定的键名重复的情形,以这里指定的键名的值为优先。
什么也不指定的情形为{}。
callbackFunction

指定当外部API的请求信息保存完后,执行的callback函数。
没有参数。

未指定或者指定undefined为null的情形,请求信息保存完了后转到应用插件的列表页面,并显示设置完了的消息。

当指定了callback函数的情形,则不转到应用插件列表页面。

返回值

可运行的页面

各个插件的设置页面

范例代码

var headers = {
    "Content-Type": "application/json",
    "Authorization": "1234567890abcdefg"
};
var data = {
    "key1": "secretValue"
};
kintone.plugin.app.setProxyConfig('https://api.example.com', "GET", headers, data);
  • 执行API的函数「kintone.plugin.app.proxy()」

URL:https://api.example.com/rest/operate.json
头部:{}

指定上面的URL和请求头的情形,执行API时发送的请求的头部为{"Content- Type": "application/json","Authorization":"1234567890abcdefg"}。

获取保存到插件的信息

使用函数 “kintone.plugin.app.proxy()” 执行外部API的情形,获取加在请求头部和数据里的信息。
加在请求里的信息,是指用函数 “kintone.plugin.app.setProxyConfig()” 指定的信息。

函数

kintone.plugin.app.getProxyConfig(url, method)

参数

参数类型必须说明
url字符串
必须
指定API的URL。
method字符串
指定HTTP 方法,GET、POST、PUT、DELETE 的任意一个。

返回值

返回值的范例

{
    "headers": {
        "Content-Type": "application/json",
        "Authorization": "1234567890abcdefg"
    },
    "data": {
    }
}

可运行的页面

各个插件的设置页面

范例代码

var config = kintone.plugin.app.getProxyConfig("https://api.example.com", "GET");
console.log(config);

在插件中上传文件到外部

从插件里可以向外部上传文件。

外部API执行的时候,如果使用了认证信息等需加密的信息时,在执行API之前,需要预先在插件里保存好所需信息。
信息保存到插件的方法,请参考以下项目。

函数

kintone.plugin.app.proxy.upload(pluginId, url, method, headers, data, callback, error)

参数

参数类型必须
说明
pluginId对象
必须
指定执行API的插件ID。
url文字列必须
请求URL。
method文字列必须
HTTP方法。 POST,PUT中的任意一个。
headers对象
必须
以对象的形式指定请求头。
什么也不指定的情形,默认{}。
(例) {'Content-Type': 'application/json'}
data对象
必须

请求里的数据。

{
    'format': 上传到proxy的数据格式,
    'value': 待上传的数据
}

format为字符串,只可指定"RAW"。
value为Blob型 (包含File型) 的值。value的大小最大为200MB。

callback函数
可省略

请求完了后执行的函数。
函数的参数为以下3种信息。

  • 第一参数:应答主体(字符串)

  • 第二参数:状态代码(数值)

  • 第三参数:应答头(对象)

省略的情况下,默认返回kintone.Promise对象,里面是含有应答主体 (字符串)、状态代码(数值)、应答头(对象)信息的数组。

error函数
可省略

指定请求失败时执行的函数。
函数的参数传递的是 proxy API的应答主体(字符串)。
callback省略的情况下,默认返回kintone.Promise对象,在proxy API的应答主体 (字符串)里含有出错信息。

返回值

省略参数callback的时候,返回kintone.Promise对象。
参考: 添加事件句柄

指定callback的情形没有返回值。

可运行页面

可在以下这些页面运行。

PC 端

  • 记录列表列表

  • 记录列表详情

  • 记录列表追加

  • 记录列表编辑

  • 记录列表打印

  • 图表

智能手机端

  • 记录列表

  • 记录列表详情

  • 记录列表追加

  • 记录列表编辑

范例代码

使用callback的写法

var data = {
    'format': 'RAW',
    'value':
}

kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'POST', {}, data, function(body, status, headers) {
    //success
    console.log(status, JSON.parse(body), headers);
}, function(error) {
    //error
    console.log(error);  // 显示proxy API的应答本体(字符串)
});

使用kintone.Promise对象的写法

// 使用kintone.Promise对象的写法
var data = {
    'format': 'RAW',
    'value':
}

kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'POST', {}, data).then(function(args) {
    //success
    /*  args[0] -> body(字符串)
     *  args[1] -> status(数值)
     *  args[2] -> headers(对象)
     */
    console.log(args[1], JSON.parse(args[0]), args[2]);
}, function(error) {
    //error
    console.log(error);  // 显示proxy API的应答本体(字符串)
});

注意事项

  • 使用url指定不存在的服务器时、应答返回状态码为「503」(DNS Cache Missing)的错误。

限制事项

  • 对象浏览器:Internet Explorer11、最新的Firefox、最新的Chrome、最新的Safari、最新的iOS Safari、最新的Android Chrome。

  • 当你发送的HTTP请求为POST / PUT时,由于header里“Content-Length”和“Transfer-Encoding”会在内部自动添加,因此用户在发起请求时无需手动设置它们,否则将导致出错。


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