外部API的执行

cybozu发表于:2016年09月13日 13:45:36更新于:2022年12月07日 10:12:44

Index

执行外部的API

在kintone自定义时,通过此API来执行外部的API。
使用此API给外部API发送请求时,可以规避跨域限制。
当把文件上传到外部时,请参照 “将文件上传到外部” 。

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

  • 即使通过proxy,也不能自动发行需在proxy端的网站发行的cookie。

  • 可用的Content-Type没有限制。

函数

kintone.proxy(url, method, headers, data, successCallback, failureCallback);

参数

参数名称要指定的值必须说明
url字符串
必须请求URL
method字符串
必须HTTP方法。 GET,POST,PUT,DELETE 中任一个。
headers对象必须指定请求头对象。
未指定的时候,默认{}。
(例) {'Content-Type': 'application/json'}
data对象或字符串必须请求里包含的数据。未指定的时候,默认{}。

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

successCallback函数
可省略

向Proxy处发送的请求,结束时执行的回调函数。
参数里赋值的是来自proxy的response body (字符串)、status code(数值)、response header(对象)。
省略的情况下,默认返回kintone.Promise对象,里面是含有response body (字符串)、status code(数字)、response header(对象)信息的数组。

failureCallback函数
可省略

发往proxy API 的请求,失败时执行的回调函数。
接受来自proxy的参数:response body (字符串)。
failureCallback省略的情况下,默认返回kintone.Promise对象,丢弃proxy API的response body (字符串)。

返回值

省略参数successCallback时,返回 kintone.Promise 对象。
参考: 事件处理的写法

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

 

例子

使用call back的记述方法
kintone.proxy('https://*****.***.net', 'GET', {}, {}, function(body, status, headers) {
    //success
    console.log(status, JSON.parse(body), headers);
}, function(error) {
    //error
    console.log(error);  //显示proxy API的response body(字符串)
});
使用kintone.Promise对象的记述方法
kintone.proxy('https://*****.***.net', 'GET', {}, {}).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的response body(字符串)
});

注意事项

  • 用url指定不存在的服务器时,应答为包含状态代码 “503”(DNS Cache Missing)的错误。

  • 测试环境等对IP有限制的环境里,访问链接源域名里的其他应用时,可以访问以下页面里许可的IP地址。
    cybozu.com使用的IP地址
    ※ 但是如果使用kintone.proxy的话,可自由访问外部的链接,从安全性上来说并不推荐。请大家使用kintone.api来访问链接源的域名。

限制事项

  • 目标 proxy 应答正文仅支持字符串。无法获取如图像等二进制数据。

  • 从 proxy 返回的 response header 的上限为 100行,每一行最大长度为 8192bytes。

  • 从 proxy 返回的 response body 的上限为 10MB。

  • 超过上限会产生错误。

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

  • 当您发送的HTTP请求为 POST / PUT 时,由于 Header 里的 “Content-Length” 和 “Transfer-Encoding” 是通过内部自动添加的,所以请不要手动设置它们,否则将导致出错。

将文件上传到外部

在kintone自定义时,可以通过此API将文件上传至外部系统。
使用此API给外部API发送请求时,可以规避跨域限制。

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

  • 即使通过proxy,也不能自动发行需在proxy端的网站发行的cookie。

  • 可用的Content-Type没有限制。

函数

kintone.proxy.upload(url, method, headers, data, successCallback, failureCallback);

参数

参数名称要指定的值必须
说明
url字符串必须请求URL
method字符串必须HTTP方法。 POST,PUT中任一个。
headers对象
必须指定请求头对象。
未指定的时候,默认{}。
(例) {'Content-Type': 'application/json'}
data对象必须请求里包含的数据。
{
    'format': 向 proxy 上传数据时使用的格式,
    'value': 上传的数据
}
format 是字符串、只能指定 "RAW"。
value 是Blob型 (包括 File型) 的值。value的大小最多为 200MB。
successCallback函数
可省略

向Proxy处发送的请求,结束时执行的回调函数。
参数里赋值的是来自proxy的response body (字符串)、status code(数字)、response header(对象)。
省略的情况下,默认返回kintone.Promise对象,里面是含有response body (字符串)、status code(数字)、response header(对象)信息的数组。

failureCallback函数
可省略

发往proxy API 的请求,失败时执行的回调函数。
接受来自proxy的参数:response body (字符串)。
failureCallback省略的情况下,默认返回kintone.Promise对象,丢弃proxy API的response body (字符串)。

返回值

省略参数 successCallback 时,返回 kintone.Promise 对象。
参考: 事件处理的写法

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

例子

使用回调函数的记述方法
var data = {
    'format': 'RAW',
    'value': <some blob object>
}

kintone.proxy.upload('https://*****.***.net', 'POST', {}, data, function(body, status, headers) {
    //success
    console.log(status, JSON.parse(body), headers);
}, function(error) {
    //error
    console.log(error);  //显示proxy API的response body(字符串)
});
使用kintone.Promise对象的记述方法
var data = {
    'format': 'RAW',
    'value': <some blob object>
}

kintone.proxy.upload('https://*****.***.net', '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的response body(字符串)
});

注意事項

  • 用url指定不存在的服务器时,应答为包含状态代码 “503”(DNS Cache Missing)的错误。

限制事项

  • 目标 proxy 应答正文仅支持字符串。无法获取如图像等二进制数据。

  • 从 proxy 返回的 response header 的上限为 100行,每一行最大长度为 8192bytes。

  • 从 proxy 返回的 response body 的上限为 10MB。

  • 超过上限会产生错误。

  • 目标浏览器为 Internet Explorer11、最新的 Firefox、最新的 Chrome、最新的 Safari、最新的 iOS Safari、最新的 Android Chrome。

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

  • “Content-Length”和“Transfer-Encoding”是通过内部自动添加的,所以请不要手动设置它们,否则将导致出错。

相关技巧(Tips)