Plug-in Proxy Request
Plug-in Proxy Request - kintone.plugin.app.proxy()
Runs an external Web API from a plug-in.
It makes an HTTP request to a specified endpoint. This API enables sending requests to external Web APIs while avoiding cross-domain restrictions.
If the external Web API requires confidential information such as secret keys, use the Proxy Set Config API and Proxy Get Config API to save and retrieve these data for the external Web API.
For information on how to save and retrieve data in plug-ins, refer to the following article:
Function
kintone.plugin.app.proxy(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 URL of the API to be run. |
method | String | Yes | The HTTP method. Specify one of the following: GET / POST / PUT / DELETE . |
headers | Object | Yes | The request header. The parameters specified here will be sent with the parameters that were saved in the plug-in by the kintone.plugin.app.setProxyConfig() function. For more information, refer to the following article: Proxy Set Config To ignore this parameter, input {} . |
data | Object or String | Yes | The request body. The data specified here will be sent with the data that was saved in the plug-in by the kintone.plugin.app.setProxyConfig() function.For more information, refer to the following article: Proxy Set Config Applied only for POST / PUT requests. Ignored for GET / DELETE requests.For GET / DELETE requests, set the parameter on the QueryString of the URL instead. |
successCallback | Function | Optional | The function that will run after the request has finished. The following three data will be passed as the parameters:
kintone.Promise object will be returned that can be fulfilled with an array containing the Response body (string), Status code (number) and Response header (Object) mentioned above. |
failureCallback | Function | Optional | The function that will run when the request fails. The response body will be passed to the function parameter as a string. If the callback is ignored, a kintone.Promise object will be returned that can be fulfilled with the Response body (string) from the Kintone plug-in proxy API. |
Returns
A kintone.Promise
object will be returned if the successCallback
or failureCallback
parameters are ignored. Otherwise, nothing will be returned.
Available Pages
This method can be used in the following pages:
Desktop pages:
- Record List
- Record Details
- Record Create
- Record Edit
- Graph
Mobile pages:
- Record List
- Record Details
- Record Create
- Record Edit
- Graph
Sample Request
|
|
Sample Request Using Promises
|
|
Conditions for Saved Data to be Added to the Request
When using kintone.plugin.app.proxy
, information saved in the plug-in's configuration can be added to the request automatically when all of the following conditions are met:
- The app is the same.
- The plug-in is the same.
- The HTTP method is the same.
- The URL of the API called matches (forward match, case-sensitive).
For example, the following API and URL are used to save settings to the plug-in, the information saved in the plug-in will be added to the request because the URL matches the beginning of the URL.
- Specified URL using Proxy Get Config API:
https://api.example.com/
Then the following API and URL are called to run an external Web API.
- Specified URL using Plug-in Proxy Request API:
https://api.example.com/operate.json
The URLs will forward match, and the data saved in the plug-in will be added to the request.
Priority for Multiple Configuration Settings
If multiple settings are saved to the plug-in, the URL in the settings that matches the most characters with the URL called by kintone.plugin.app.proxy()
will be prioritized.
For example, the Proxy Set Config API is used to save the following two settings to the plug-in:
- Setting 1
- URL:
https://api.example.com/
- Header:
{ "Content-Type": "application/x-www-form-urlencoded" }
- URL:
- Setting 2
- URL:
https://api.example.com/foo/
- Header:
{ "Content-Type": "application/json" }
- URL:
Then kintone.plugin.app.proxy()
is called to run an external Web API with the following information:
- URL:
https://api.example.com/foo/operate.json
- Header:
{}
The request header sent when the API is executed is { “Content-Type”: “application/json” }
.
Request Header Sent When Executing External APIs
The request header specified by this API is appended with the configuration settings' request header that meets the following conditions:
Conditions for Automatically Adding Configuration Information to a Request
For example, when specifying the request header for each API as follows:
- Proxy Set Config API
|
|
- Plug-in Proxy Request API (this API)
|
|
In this case, the request header below is sent.
|
|
To put it simply, a plug-in automatically retrieves the saved data from the App configuration on which it is installed. A plug-in then retrieves its own configuration data and appends the data to the request when the HTTP method matches and the URL forward-match that of the external API being called from kintone.plugin.app.proxy()
.
Request Body Sent When Executing External APIs
POST
/ PUT
HTTP method
The request body specified by this API is appended with configuration settings that meets the following conditions:
Conditions for Automatically Adding Configuration Information to a Request
This is the same as the case with the request header. However, configuration settings are appended only when the request body type specified by this API is an object, not when it is a string.
GET
/ DELETE
HTTP method
The configuration settings that meet the following conditions are appended as a query string at the end of the query string of the URL of the external API specified by this API:
Conditions for Automatically Adding Configuration Information to a Request
If the query string does not contain ?
to indicate the start of the query string, it is automatically appended.
For example, when the request body and request parameters for each API are specified as follows:
- Proxy Set Config API
|
|
- Plug-in Proxy Request API (this API)
url
:https://api.example.com?k=v
In this case, the request is sent to the following URL.
https://api.example.com?k=v&k1=v1&k2=v2
Duplicate Keys in Multiple Configuration Settings
The URL in the settings that matches the most characters with the URL called by kintone.plugin.app.proxy()
will be prioritized if it satisfies both of the following conditions:
- Conditions for Automatically Adding Configuration Information to a Request
- There is a duplicate value in the request header key
If the HTTP method is POST
/ PUT
, the value type specified in the request header is an object. If the HTTP method is GET
/ DELETE
, it is applied to a query string.
For example, when specifying the request header for each API as follows:
- Proxy Set Config API
|
|
- Plug-in Proxy Request API (this API)
|
|
In this case, the request header below is sent.
|
|
When the Configuration Settings and the Request Header or Request Body Key Specified by the API Overlaps
If the keys of the request headers adopted from the configured request data overlap with the request header specified by this API, the former value will take precedence.
The same rule applies to the request body when the HTTP method is POST
/ PUT
, but only if the type is an object.
Duplicate keys are not checked for GET
/ DELETE
requests.
For example, when specifying the request header for each API as follows:
- Proxy Set Config API
|
|
- Plug-in Proxy Request API (this API)
|
|
In this case, the request header below is sent.
|
|
Notes
- Specifying a non-existent
url
will return an error status code of503 (DNS Cache Missing)
. - If the request origin subdomain has IP restrictions and attempts to access another App in the same subdomain, the kintone.com IP Addresses must be allowed access. A list of IP Addresses used by Kintone can be found in the following article on the help site:
Domains and IP Addresses Used by Kintone - Note that this allows any kintone.com domain to access the API. Therefore, it is not recommended from a security standpoint.
- When using Kintone REST API on a personal Kintone domain, use the Kintone REST API Request instead of the
kintone.proxy()
API. For more information on Kintone REST API Request, refer to the following article:
Kintone REST API Request - When using this API to execute external APIs, cookies that should be generated at the API destination are not automatically generated.
- The
Content-Length
header andTransfer-Encoding
headers are automatically added if the HTTP Method is set toPOST
orPUT
. Explicitly setting when making requests will cause an error.
Limitations
- The following are the limitations on external API responses to be executed:
- The maximum lines of the response header from the other end of the proxy is 100 lines, and the maximum size for each line is 8,180 bytes.
- The maximum size of the response body from the other end of the proxy is 10MB. Errors will occur if lines or sizes go over the maximum.
- This API can only handle a response body of characters. Images, or other binary data are not supported.
- Communication with servers using self-signed certificates is not possible.