Plug-in Proxy File Upload

Plug-in Proxy File Upload - `kintone.plugin.app.proxy.upload()`

Upload a file to outside of Kintone from a plug-in.
If your external REST API requires sensitive information such as secret keys, use the Set Config for proxy() API and Get Config for proxy() API to save and get these data for the external REST API.

Function

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

Parameters

PARAMETER	TYPE	REQUIRED	DESCRIPTION
pluginId	String	Yes	The Plug-in ID of the Plug-in that will run the API.
url	String	Yes	The request URL.
method	String	Yes	The HTTP method. Specify one of the following: POST / PUT.
headers	Object	Yes	Specify the request header as an object. To ignore this parameter, input `{}`. Sample:`{'Content-Type': 'application/json'}`
data	Object	Yes	The data that will be sent in the request. `{ 'format': format to be uploaded to the external service. 'value': data to be uploaded }` For format, you can only specify the string "RAW". For value, specify the value of the Blob type (including File type). The maximum size is 200MB.
successCallback	Function	Optional	The callback function that will run when the request to the external service has finished. It will receive the response body (string), the status code (number) and the response header (object) as parameters from the external service. If this parameter is ignored, a kintone.Promise object will be returned that can be fulfilled with an array containing a Response body (string), Status code (number) and Response header (object).
failureCallback	Function	Optional	The callback function that will run when the API request to the external service fails. It will receive the response body (string) as the parameter from the external service. If this parameter is ignored, a kintone.Promise object will be returned that can be rejected with the response body (string) from this API.

Response

A kintone.Promise object will be returned if the successCallback or failureCallback parameters are ignored. Otherwise, there will be no response.

Available Pages

This method can be used in the following pages:

Desktop pages:

Record List
Record Details
Record Create
Record Edit
Record Print
Graph
File Import
File Export

Mobile pages:

Record List
Record Details
Record Create
Record Edit

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


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

kintone.plugin.app.proxy.upload('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'POST', {}, data, function(body, status, headers) {
  // success
  console.log(status, JSON.parse(body), headers);
}, function(error) {
  console.log(error); // Display the response body (string) from the proxy API
});

Sample Request using Promises

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


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

kintone.plugin.app.proxy.upload('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'POST', {}, data).then(function(args) {
  // success
  /*  args[0] -> body(String)
     *  args[1] -> status(Number)
     *  args[2] -> headers(Object)
     */
  console.log(args[1], JSON.parse(args[0]), args[2]);
}, function(error) {
  console.log(error); // Display the response body (string) from the proxy API
});

Limitations

Compatible browsers are: Latest versions of Mozilla Firefox, Google Chrome, Safari, iOS Safari and Android Chrome.

Notes on Saved Data used with Kintone Plug-in Proxy

The Request Header sent when using Kintone Plug-in Proxy

The request header that will be sent is the contents of the request header specified in the Kintone Plug-in Proxy plus the saved plug-in data that was saved with setProxyConfig().

Example:
If {k1: 'v1'} was specified in the request header for setProxyConfig(), and {k2: 'v2'} was specified in the request header for Kintone Plug-in Proxy, the request header will become {k1: 'v1', k2: 'v2'} .

The Data sent when using Kintone Plug-in Proxy

When the HTTP method is POST/PUT, the data sent will depend on the data format.
If the data format is an object, the data specified in the Kintone Plug-in Proxy plus the saved plug-in data that was saved with setProxyConfig() will be sent.
If the data format is a string, only the data specified in the Kintone Plug-in Proxy will be sent.

When the HTTP method is GET/DELETE, the plug-in data saved with setProxyConfig() will be added as a Query String to the end of the specified url parameter of the Kintone Plug-in Proxy.
If "?" is not included in the specified url parameter, this will also be added.

Example:
If {k1: 'v1', k2: 'v2'} was specified in the data for setProxyConfig(), and 'https://api.github.com?k=v' was specified in the url for Kintone Plug-in Proxy, the url will become 'https://api.github.com?k=v&k1=v1&k2=v2'

When two saved settings have the same keys

If setProxyConfig() is used to save two different settings that use the same named keys, the settings with the URL that most matches the URL specified in the Kintone Plug-in Proxy will take priority.

Example:
If setProxyConfig() is used to save two different settings as below,

1
2


url: 'https://api.github.com'
headers:  {k1: 'v1', k2: 'v2'}

and

1
2


url: 'https://api.github.com/'
headers: {k2: 'v2-1', k3: 'v3'}

then, if the Kintone Plug-in Proxy is used with the url as 'https://api.github.com/' , the request header will become

1

{k1: 'v1', k2: 'v2-1', k3: 'v3'}

When a saved setting and the Kintone Plug-in Proxy have the same keys

As explained in the parameter descriptions in the table for the setProxyConfig(), if the keys in the saved settings use the same named keys as the ones in the Kintone Plug-in Proxy, the saved keys will take priority.
If the HTTP method is GET/DELETE, the overlapping of keys is not checked.

Example:
If setProxyConfig() is used to save settings as below,

1

headers: {k1: 'v1', k2: 'v2'}

and Kintone Plug-in Proxy is used with

1

headers: {k2: 'v2-1', k3: 'v3'}

then in this case, both headers contain the k2 value, but the saved settings will take priority, thus the request header will become

1

{k1: 'v1', k2: 'v2', k3: 'v3'}

API Docs