Index
プラグインに設定を保存する
キーと値を対にして、オブジェクト形式でプラグインに設定を保存できます。
最後に保存した設定だけが保持されます。
関数
kintone.plugin.app.setConfig(config,callback)
引数
| 引数 | 型 | 必須 | 説明 |
| config | オブジェクト | 必須 |
キーと値を対にしたオブジェクトの形式で、プラグインに保存する設定を指定します。 例： { "key1": "value1", "key2": "value2" } |
| callback | 関数 | 設定の保存が完了したあとに実行する関数を指定します。 callback 関数の指定を省略した場合、設定の保存が完了すると、プラグインの一覧画面に移動します。 |
返り値
ありません。
実行できる画面
プラグインごとの設定画面
サンプルコード
制限事項
プラグインの設定に保存可能な容量に関する制限は次のとおりです。
- 1アプリに設定できるプラグインは20個までです。
- 1プラグインのkintone.plugin.app.setConfigで設定できるkey-valueのvalue値の合計は256KBまでです。
プラグインの設定情報を取得する
指定したプラグインの設定情報を取得します。
関数
kintone.plugin.app.getConfig(pluginId)
引数
| 引数 | 型 | 必須 | 説明 |
| pluginId | 文字列 | 必須 | 設定情報を取得するプラグインのIDを指定します。 |
返り値
プラグインの設定情報が、キーと値を対にしたオブジェクトの形式で返ります。
この関数を実行できない画面では、関数を実行するとnull が返ります。
返り値の例
実行できる画面
次の画面で実行できます。
PC での次の画面
- レコード一覧
- レコード詳細
- レコード追加
- レコード編集
- レコード印刷
- グラフ
- プラグインごとの設定画面
スマートフォンの次の画面
- レコード一覧
- レコード詳細
- レコード追加
- レコード編集
サンプルコード
プラグインから外部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 | オブジェクト/文字列 | 必須 |
リクエストデータを指定します。 指定した値は、POST または PUT の場合のみ利用されます。 |
| callback | 関数 | 省略可 |
リクエストが完了したあとに実行する関数を指定します。関数の引数には、次の3 つの情報が渡されます。
省略した場合はkintone.Promiseオブジェクトが返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。 |
| error | 関数 | 省略可 |
リクエストが失敗した場合に実行する関数を指定します。 callbackを省略した場合はkintone.Promiseオブジェクトが返され、proxy APIのレスポンスボディ(文字列)で棄却されます。 |
返り値
引数のcallbackを省略した時、kintone.Promiseオブジェクトを返します。
参考: イベントハンドラを登録する
callbackを指定した場合返り値はありません。
実行できる画面
次の画面で利用できます。
PC での次の画面
- レコード一覧
- レコード詳細
- レコード追加
- レコード編集
- レコード印刷
- グラフ
スマートフォンの次の画面
- レコード一覧
- レコード詳細
- レコード追加
- レコード編集
- グラフ
サンプルコード
コールバックを使った記述方法
補足
外部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実行時に送信されるデータ
- 外部API実行時に指定されるデータは、HTTPメソッドがPOST/PUTの場合は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' となります。
複数の設定情報間でキーが重複する場合
- 複数の設定情報が保存した情報がリクエストに加わる条件を満たし、かつ各設定情報間でリクエストヘッダのキーが重複する場合、外部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の間でキーが重複する場合
- 設定されたリクエスト情報から採用したリクエストヘッダのキーがkintone.plugin.app.proxyで指定するリクエストヘッダにも含まれる場合、前者の値を優先します。HTTPメソッドがPOST/PUTの場合のリクエストボディ（上述の通り、型がObjectの場合のみ）も同様です。GET/DELETEの場合はキーの重複はチェックません。
例）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制限をしている環境で接続元ドメイン内の別アプリへアクセスする場合は、以下のページに記載されている IP アドレスを許可することでアクセスが可能になります。
kintone よくある質問
※ ただし、kintone.plugin.app.proxy を利用して外部から自由にアクセス可能となるため、セキュリティの観点から推奨されません。
接続元ドメインへのアクセスは kintone.api をご利用ください。
制限事項
- HTTPメソッドにPOST/PUTのいずれかを指定した場合、"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"}
- 設定 1
- 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()」で指定したデータのキーと重複する場合、ここで指定したキーの値が優先されます。 何も指定しない場合は{}。 |
| callback | Function |
外部APIのリクエスト情報の保存が完了したときに実行されるコールバック関数を指定します。 未指定またはundefinedかnullが指定された場合、リクエスト情報の保存が完了したらアプリプラグイン一覧画面に遷移して設定完了メッセージを表示します。 コールバック関数が指定された場合アプリプラグイン一覧画面には遷移しません。 |
返り値
ありません。
実行できる画面
プラグインごとの設定画面
サンプルコード
- API を実行する関数「kintone.plugin.app.proxy()」
URL：https://api.example.com/rest/operate.json
ヘッダ：{}
上記のURL とリクエストヘッダを指定する場合、API の実行時に送信されるリクエストのヘッダは、「{"Content- Type": "application/json","Authorization":"1234567890abcdefg"}」です。
外部APIの実行に必要な情報を取得する
関数「kintone.plugin.app.proxy()」で外部 API を実行する場合に、リクエストのヘッダとデータに加わる情報を取得します。
リクエストに加わる情報は、関数「kintone.plugin.app.setProxyConfig()」で指定したものです。
関数
kintone.plugin.app.getProxyConfig(url, method)
引数
| 引数 | 型 | 必須 | 説明 |
| url | 文字列 | 必須 | API のURL を指定します。 |
| method | 文字列 | 必須 | HTTP メソッドを、GET、POST、PUT、DELETE のいずれかで指定します。 |
返り値
返り値の例
実行できる画面
プラグインごとの設定画面
サンプルコード
プラグインから外部にファイルをアップロードする
プラグインから外部にファイルをアップロードすることができます。
外部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"のみ指定できます。 |
| callback | 関数 | 省略可 |
リクエストが完了したあとに実行する関数を指定します。
省略した場合はkintone.Promiseオブジェクトが返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。 |
| error | 関数 | 省略可 |
リクエストが失敗した場合に実行する関数を指定します。 |
返り値
引数のcallbackを省略した時、kintone.Promiseオブジェクトを返します。
参考: イベントハンドラを登録する
callbackを指定した場合返り値はありません。
実行できる画面
次の画面で実行できます。
PC での次の画面
- レコード一覧
- レコード詳細
- レコード追加
- レコード編集
- レコード印刷
- グラフ
スマートフォンの次の画面
- レコード一覧
- レコード詳細
- レコード追加
- レコード編集
サンプルコード
コールバックを使った記述方法
kintone.Promiseオブジェクトを使った記述方法
注意事項
- urlで存在しないサーバーを指定した場合、レスポンスはステータスコード「503」（DNS Cache Missing）のエラーとなります。
制限事項
- 対象ブラウザは、Internet Explorer11、最新のFirefox、最新のChrome、最新のSafari、最新のiOS Safari、最新のAndroid Chromeとなります。
- "Content-Length"ヘッダと"Transfer-Encoding"ヘッダは、内部的に自動で付加されるため、ユーザーからのリクエスト時に手動で設定することはできません。設定するとエラーが発生します。
大変お世話になっております。佐藤と申します。
kintone.plugin.app.proxy()の使い方についてご教授ください。
x-www-form-urlencoded形式でのリクエストはサポートされていますでしょうか？ している場合はどのように実装すれば送信できるでしょうか。
kintone.proxy()では、body部を"key1=value1&key2=...（省略）"という文字列で指定することでx-www-form-urlencoded形式のリクエストの送信ができましたが、kintone.plugin.app.proxy()で同じように文字列でbody部を指定するとsetProxyConfig()で設定した内容が追加されません。
また、body部を文字列ではなくオブジェクトの形式で指定すると、setProxyConfig()の内容は追加されますが、body部の形式が違っているようでリクエスト先のサーバから認証エラーが返却されています（headerには{'Content-Type':'application/x-www-form-urlencoded'}を指定している状態です）。
以下環境情報です。
お手数おかけしますがよろしくお願いいたします。