kintone プラグインJavaScript API

更新日時
サイト更新情報をフォロー
API更新情報をフォロー
フォローする

Index

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

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

関数

kintone.plugin.app.getConfig(pluginId)

引数

引数 型 必須 説明
pluginId 文字列 必須 設定情報を取得するプラグインのIDを指定します。

返り値

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

返り値の例

実行できる画面

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

PC での次の画面

  • レコード一覧
  • レコード詳細
  • レコード追加
  • レコード編集
  • レコード印刷 ※2016/8/14の定期メンテナンス後に利用できる機能です。
  • グラフ
  • ファイルの読み込み
  • ファイルの書き出し
  • プラグインごとの設定画面

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

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

サンプルコード

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

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

関数

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

引数

引数 型 必須 説明
config オブジェクト 必須

キーと値を対にしたオブジェクトの形式で、プラグインに保存する設定を指定します。値は文字列で指定します。

例： { "key1": "value1", "key2": "value2" }
callback 関数   設定の保存が完了したあとに実行する関数を指定します。
callback 関数の指定を省略した場合、設定の保存が完了すると、プラグインの一覧画面に移動します。

返り値

ありません。

実行できる画面

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

サンプルコード

制限事項

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

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

プラグインから外部の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 オブジェクト/文字列 必須

リクエストデータを指定します。
ここで指定したデータに加えて、関数「kintone.plugin.app.setProxyConfig()」を使用してプラグインに保存したデータも送信されます。
callback 関数 省略可

リクエストが完了したあとに実行する関数を指定します。関数の引数には、次の3 つの情報が渡されます。

  • 第一引数：レスポンスボディ（文字列）
  • 第二引数：ステータスコード（数値）
  • 第三引数：レスポンスヘッダ（オブジェクト）

省略した場合はkintone.Promiseオブジェクトが返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。
error 関数 省略可

リクエストが失敗した場合に実行する関数を指定します。
関数の引数には、proxy APIのレスポンスボディ(文字列)が渡されます。

callbackを省略した場合はkintone.Promiseオブジェクトが返され、proxy APIのレスポンスボディ(文字列)で棄却されます。

返り値

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

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

 

実行できる画面

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

PC での次の画面

  • レコード一覧
  • レコード詳細
  • レコード追加
  • レコード編集
  • レコード印刷 ※2016/8/14の定期メンテナンス後に利用できる機能です。
  • グラフ
  • ファイルの読み込み
  • ファイルの書き出し

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

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

サンプルコード

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

補足

外部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）のエラーとなります。

外部の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"}
  • 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"}」です。

プラグインに保存した情報を取得する

関数「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"のみ指定できます。
valueはBlob型 (File型を含む) の値。valueのサイズは200MBまでです。
callback 関数 省略可

リクエストが完了したあとに実行する関数を指定します。
関数の引数には、次の3 つの情報が渡されます。

  • 第一引数：レスポンスボディ（文字列）
  • 第二引数：ステータスコード（数値）
  • 第三引数：レスポンスヘッダ（オブジェクト）

省略した場合はkintone.Promiseオブジェクトが返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。
error 関数 省略可

リクエストが失敗した場合に実行する関数を指定します。
関数の引数には、proxy APIのレスポンスボディ(文字列)が渡されます。
callbackを省略した場合はkintone.Promiseオブジェクトが返され、proxy APIのレスポンスボディ(文字列)で棄却されます。

返り値

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

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

実行できる画面

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

PC での次の画面

  • レコード一覧
  • レコード詳細
  • レコード追加
  • レコード編集
  • レコード印刷 ※2016/8/14の定期メンテナンス後に利用できる機能です。
  • グラフ
  • ファイルの読み込み
  • ファイルの書き出し

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

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

サンプルコード

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

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

注意事項

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

制限事項

  • 対象ブラウザは、Internet Explorer11、最新のFirefox、最新のChrome、最新のSafari、最新のiOS Safari、最新のAndroid Chromeとなります。

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

ログインしてコメントを残してください。
Powered by Zendesk