kintone 插件JavaScript API

cybozu • 发表于：2016年11月25日 14:18:31 • 更新于：2024年01月26日 15:26:26

Index

保存插件的设置

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

函数

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

参数

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

指定以键名和键值配对的对象方式，指定要保存到插件的设置信息。
键为64位以内ASCII字符，值为65535位以内字符串。

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

successCallback函数
指定设置保存完了后运行的函数。

callback 函数省略的情形，一旦设置保存完了后，就转到插件列表页面。
没有参数。
如未指定或 undefined 或 null 时，保存插件设置信息后，画面转到应用设置的插件列表页面，并显示设置完成消息。
如指定 successCallback 函数时，画面则不会转到应用设置的插件列表页面。

返回值

无。

可运行页面

各个插件的设置页面

范例代码

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

限制事项

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

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

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

获取插件的设置信息

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

函数

kintone.plugin.app.getConfig(pluginId)

参数

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

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

返回值

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

返回值的范例

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

可运行页面

可在以下页面运行。

PC端

  • 记录列表

  • 记录详情

  • 记录添加

  • 记录编辑

  • 记录打印 

  • 图表

  • 各个插件的设置页面

智能手机端

  • 记录列表

  • 记录详情

  • 记录添加

  • 记录编辑

范例代码

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

在插件里执行外部API

此API用于在插件中执行外部API。
使用此API给外部API发送请求时，可以规避跨域限制。
执行外部API时，如使用了认证信息等需要加密的信息时，在执行API之前，需要预先在插件里保存好所需信息。
信息保存到插件的方法，请参考以下项目。

函数

kintone.plugin.app.proxy(pluginId, url, method, headers, data, successCallback, failureCallback)

参数

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

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

仅可用于POST/PUT，GET/DELETE时即使指定了也将被忽视。
在GET/DELETE的情况下、需要往URL的QueryString里传递参数。

successCallback函数
可省略

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

  • 第一参数：应答主体（字符串）

  • 第二参数：状态代码（数值）

  • 第三参数：应答头（对象）

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

failureCallback函数
可省略

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

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

返回值

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

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

 

可运行页面

可在以下页面运行。

PC端

  • 记录列表

  • 记录详情

  • 记录添加

  • 记录编辑

  • 记录打印

  • 图表

智能手机端

  • 记录列表

  • 记录详情

  • 记录添加

  • 记录编辑

  • 图表

范例代码

使用callback的写法

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

使用kintone.Promise对象的写法

// 使用 kintone.Promise 对象的写法
kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 
'https://api.example.cn', 'GET', {}, {}).then(function(args) {
  /*  args[0] -> body(字符串)
   *  args[1] -> status(数值)
   *  args[2] -> headers(对象)
   */
  console.log(args[1], JSON.parse(args[0]), args[2]);
}, function(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）的错误

  • 如您的环境设置了 IP 地址限制，那么使用此 JavaScript API 对同一域名的其他应用执行 kintone REST API 时，需要许可 kintone 的 IP 地址。
    关于 IP 地址，请参考cybozu.cn使用的域和IP地址。
    但是，这样的话就可以通过执行外部 API 的API来自由访问  kintone 环境，因此从安全角度来说，不推荐这样的做法。
    如要访问同一域名的其他应用，请使用 kintone REST API 请求。

  • 使用此 API 执行外部 API 时，外部的 API 不会自动发行原本会发行的 Cookie 。

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

限制事项

  • 关于要执行的外部 API 的应答限制如下。

    • 应答头部的上限是：最多 100行，1 行最大8192 bytes。

    • 应答正文的上限是10MB。超过上限会报错。

    • 应答正文仅可使用字符串。不可获取图片等二进制数据。

  • 无法与使用自签名证书的服务器通信。

将执行外部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.cn/

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

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

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

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

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

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

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

函数

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

参数

参数类型必须说明
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()” 指定的键名重复的情形，以这里指定的键名的值为优先。
什么也不指定的情形为{}。
successCallback函数

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

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

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

返回值

无

可运行的页面

各个插件的设置页面

范例代码

var headers = {
    "Content-Type": "application/json",
    "Authorization": "1234567890abcdefg"
};
var data = {
    "key1": "secretValue"
};
kintone.plugin.app.setProxyConfig('https://api.example.cn', "GET", headers, data);

在上面的示例代码中将运行外部 API 所需的信息保存到插件后，然后运行kintone.plugin.app.proxy()

  • URL：https://api.example.cn/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.cn", "GET");
console.log(config);

在插件中上传文件到外部

此API用于在插件中向外部系统上传文件。
使用此API给外部API发送请求时，可以规避跨域限制。
外部API执行的时候，如果使用了认证信息等需加密的信息时，在执行API之前，需要预先在插件里保存好所需信息。
信息保存到插件的方法，请参考以下项目。

函数

kintone.plugin.app.proxy.upload(pluginId, url, method, headers, data, successCallback, failureCallback)

参数

参数类型必须
说明
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。

successCallback函数
可省略

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

  • 第一参数：应答主体（字符串）

  • 第二参数：状态代码（数值）

  • 第三参数：应答头（对象）

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

failureCallback函数
可省略

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

返回值

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

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

可运行页面

可在以下页面运行。

PC 端

  • 记录列表

  • 记录详情

  • 记录追加

  • 记录编辑

  • 记录打印

  • 图表

智能手机端

  • 记录列表

  • 记录详情

  • 记录追加

  • 记录编辑

范例代码

使用callback的写法

var data = {
    'format': 'RAW',
    'value': <some blob object>
}

kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 
'https://api.example.cn', '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': <some blob object>
}

kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 
'https://api.example.cn', '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）的错误。

  • 如您的环境设置了 IP 地址限制，那么使用此 JavaScript API 对同一域名的其他应用执行 kintone REST API 时，需要许可 kintone 的 IP 地址。
    关于 IP 地址，请参考cybozu.cn使用的域和IP地址。
    但是，这样的话就可以通过执行外部 API 的API来自由访问  kintone 环境，因此从安全角度来说，不推荐这样的做法。

  • 使用此 API 执行外部 API 时，外部的 API 不会自动发行原本会发行的 Cookie 。

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

限制事项

  • 关于要执行的外部 API 的应答限制如下。

    • 应答头部的上限是：最多 100行，1 行最大8192 bytes。

    • 应答正文的上限是10MB。超过上限会报错。

    • 应答正文仅可使用字符串。不可获取图片等二进制数据。

  • 无法与使用自签名证书的服务器通信。

  • 对象浏览器与操作环境中的 Web 浏览器（日文）相同。

    最多浏览的文档