kintone プラグインJavaScript API

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

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

関数

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

引数

返り値

ありません。

実行できる画面

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

サンプルコード

制限事項

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

• 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, successCallback, failureCallback)

引数

返り値

引数の successCallback を省略した時、kintone.Promise オブジェクトを返します。
参考: イベントハンドラを登録する

successCallback を指定した場合返り値はありません。

実行できる画面

次の画面で利用できます。

PC での次の画面

• レコード一覧
• レコード詳細
• レコード追加
• レコード編集
• レコード印刷
• グラフ

モバイルの次の画面

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

サンプルコード

コールバックを使った記述方法

kintone.Promise オブジェクトを使った記述方法

補足

外部 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, successCallback)

引数

返り値

ありません。

実行できる画面

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

サンプルコード

上記のサンプルコードで外部 API の実行に必要な情報をプラグインに保存したあと、kintone.plugin.app.proxy() に

• URL：https://api.example.com/rest/operate.json
• リクエストヘッダ： {}

を指定して実行すると、以下のリクエストヘッダが送信されます。

{"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, successCallback, failureCallback)

引数

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

返り値

引数の successCallback を省略した時、kintone.Promise オブジェクトを返します。
参考: イベントハンドラを登録する

successCallback を指定した場合返り値はありません。

実行できる画面

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

PC での次の画面

• レコード一覧
• レコード詳細
• レコード追加
• レコード編集
• レコード印刷
• グラフ

モバイルの次の画面

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

サンプルコード

コールバックを使った記述方法

kintone.Promise オブジェクトを使った記述方法

注意事項

• url で存在しないサーバーを指定した場合、レスポンスはステータスコード「503」（DNS Cache Missing）のエラーとなります。

制限事項

• 対象のブラウザは、動作環境の Web ブラウザー に準じます。
• "Content-Length"ヘッダと"Transfer-Encoding"ヘッダは、内部的に自動で付加されるため、ユーザーからのリクエスト時に手動で設定することはできません。設定するとエラーが発生します。