kintone プラグインJavaScript API

プラグインに設定を保存する

キーと値を対にして、オブジェクト形式でプラグインに設定を保存できます。
最後に保存した設定だけが保持されます。

関数

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

引数

返り値

ありません。

実行できる画面

プラグインごとの設定画面

サンプルコード

制限事項

プラグインの設定に保存可能な容量に関する制限は次のとおりです。

• 1アプリに設定できるプラグインは20個までです。
• 1プラグインのkintone.plugin.app.setConfigで設定できるkey-valueのvalue値の合計は256KBまでです。

プラグインの設定情報を取得する

指定したプラグインの設定情報を取得します。

関数

kintone.plugin.app.getConfig(pluginId)

引数

返り値

プラグインの設定情報が、キーと値を対にしたオブジェクトの形式で返ります。
この関数を実行できない画面では、関数を実行するとnull が返ります。

返り値の例

実行できる画面

次の画面で実行できます。

PC での次の画面

• レコード一覧
• レコード詳細
• レコード追加
• レコード編集
• レコード印刷
• グラフ
• プラグインごとの設定画面

スマートフォンの次の画面

• レコード一覧
• レコード詳細
• レコード追加
• レコード編集

サンプルコード

プラグインから外部APIを実行する

プラグインから外部 API を実行する方法を説明します。

外部API の実行に、認証情報など秘密にする情報を使用する場合は、API を実行する前に、あらかじめ必要な情報をプラグインに保存しておきます。
情報をプラグインに保存する方法などは、次の項目を参照してください。

• 外部APIの実行に必要な情報をプラグインに保存する
• 外部APIの実行に必要な情報を取得する

関数

kintone.plugin.app.proxy(pluginId, url, method, headers, data, callback, error)

引数

返り値

引数の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

関数

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

引数

返り値

ありません。

実行できる画面

プラグインごとの設定画面

サンプルコード

• 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)

引数

返り値

返り値の例

実行できる画面

プラグインごとの設定画面

サンプルコード

プラグインから外部にファイルをアップロードする

プラグインから外部にファイルをアップロードすることができます。

外部API の実行に、認証情報など秘密にする情報を使用する場合は、API を実行する前に、あらかじめ必要な情報をプラグインに保存しておきます。
情報をプラグインに保存する方法などは、次の項目を参照してください。

• 外部APIの実行に必要な情報をプラグインに保存する
• 外部APIの実行に必要な情報を取得する

関数

kintone.plugin.app.proxy.upload(pluginId, url, method, headers, data, callback, error)

引数

{
        'format': proxy先へデータをアップロードするときのフォーマット,
        'value': アップロードするデータ
    }

返り値

引数の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"ヘッダは、内部的に自動で付加されるため、ユーザーからのリクエスト時に手動で設定することはできません。設定するとエラーが発生します。