カテゴリー内の他の記事

kintone プラグインJavaScript API

作成日2014年11月21日 08:36
更新日2022年11月17日 04:55

Index

プラグインに設定を保存する
プラグインの設定情報を取得する
プラグインから外部APIを実行する
外部 API の実行に必要な情報をプラグインに保存する
外部 API の実行に必要な情報を取得する
プラグインから外部にファイルをアップロードする

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

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

関数

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

引数

型

必須

説明

config

オブジェクト

必須

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

例： { "key1": "value1", "key2": "value2" }

successCallback

関数

設定の保存が完了したあとに実行する関数を指定します。
引数はありません。
未指定または undefined か null が指定された場合、プラグイン設定情報の保存が完了したらアプリ設定のプラグインの一覧画面に遷移して設定完了メッセージを表示します。
successCallback 関数が指定された場合、アプリ設定のプラグインの一覧画面には遷移しません。

返り値

ありません。

実行できる画面

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

サンプルコード

制限事項

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

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

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

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

関数

kintone.plugin.app.getConfig(pluginId)

引数

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

返り値

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

返り値の例

実行できる画面

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

PC での次の画面

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

モバイルの次の画面

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

サンプルコード

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

kintone プラグインで、外部 API を実行するための API です。
この API を利用すると、クロスドメイン制約を回避して、外部 API にリクエストを送信できます。

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

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

関数

kintone.plugin.app.proxy(pluginId, url, method, headers, data, successCallback, failureCallback)

引数

引数	型	必須	説明
pluginId	文字列	必須	API を実行するプラグインの ID を指定します。
url	文字列	必須	実行する API の URL を指定します。
method	文字列	必須	API の実行に使用する HTTP メソッドを GET, POST, PUT, DELETE のいずれかで指定します。
headers	オブジェクト	必須	リクエストヘッダを指定します。ここで指定したパラメータに加えて、関数「kintone.plugin.app.setProxyConfig()」を使用してプラグインに保存したパラメータも送信されます。
data	オブジェクト/文字列	必須	リクエストデータを指定します。ここで指定したデータに加えて、関数「kintone.plugin.app.setProxyConfig()」を使用してプラグインに保存したデータも送信されます。指定した値は、POST または PUT の場合のみ利用されます。 GET または DELETE の場合、URL の QueryString としてパラメータを指定してください。
successCallback	関数	省略可	リクエストが完了したあとに実行する関数を指定します。関数の引数には、次の 3 つの情報が渡されます。第一引数：レスポンスボディ（文字列）第二引数：ステータスコード（数値）第三引数：レスポンスヘッダ（オブジェクト）省略した場合は kintone.Promise オブジェクトが返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。
failureCallback	関数	省略可	リクエストが失敗した場合に実行する関数を指定します。関数の引数には、proxy API のレスポンスボディ(文字列)が渡されます。省略した場合は kintone.Promise オブジェクトが返され、proxy API のレスポンスボディ(文字列)で棄却されます。

返り値

引数の 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 アドレスを許可することでアクセスが可能になります。
cybozu.comが使用するドメインとIPアドレス
※ ただし、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"}
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, successCallback)

引数

引数	型	必須	説明
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()」で指定したデータのキーと重複する場合、ここで指定したキーの値が優先されます。何も指定しない場合は{}。
successCallback	関数		外部 API のリクエスト情報の保存が完了したときに実行されるコールバック関数を指定します。引数はありません。未指定または undefined か null が指定された場合、リクエスト情報の保存が完了したらアプリプラグイン一覧画面に遷移して設定完了メッセージを表示します。 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)

引数

引数	型	必須	説明
url	文字列	必須	API のURL を指定します。
method	文字列	必須	HTTP メソッドを GET, POST, PUT, DELETE のいずれかで指定します。

返り値

返り値の例

実行できる画面

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

サンプルコード

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

kintone プラグインで、外部のシステムにファイルをアップロードするための API です。
この API を利用すると、クロスドメイン制約を回避して、リクエストを送信できます。

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

関数

kintone.plugin.app.proxy.upload(pluginId, url, method, headers, data, successCallback, failureCallback)

引数

引数	型	必須	説明
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 までです。
successCallback	関数	省略可	リクエストが完了したあとに実行する関数を指定します。関数の引数には、次の 3 つの情報が渡されます。第一引数：レスポンスボディ（文字列）第二引数：ステータスコード（数値）第三引数：レスポンスヘッダ（オブジェクト）省略した場合は kintone.Promise オブジェクトが返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。
failureCallback	関数	省略可	リクエストが失敗した場合に実行する関数を指定します。関数の引数には、proxy API のレスポンスボディ(文字列)が渡されます。省略した場合は kintone.Promise オブジェクトが返され、proxy API のレスポンスボディ(文字列)で棄却されます。

返り値

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

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

実行できる画面

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

PC での次の画面

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

モバイルの次の画面

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

サンプルコード

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

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

注意事項

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

制限事項

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

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

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

sato.m 2020年11月30日 06:14

大変お世話になっております。佐藤と申します。
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'}を指定している状態です）。

以下環境情報です。

権限設定：アプリ管理者
デバイス（PC or モバイル）：PC
OS・ブラウザ：macOS、Chrome, Safari
IP制限など：特になし

お手数おかけしますがよろしくお願いいたします。

cybozu Development team 2020年12月03日 05:38

sato.m 様

お世話になっております。cybozu developer network 運営局です。

kintone.plugin.app.proxy() で Content-Type に application/x-www-form-urlencoded を指定することは可能です。

プラグインから外部APIを実行するの「補足 > 外部API実行時に送信されるデータ」の記載にある制限を再度ご確認ください。

> 「外部API実行時に指定されるデータは、HTTPメソッドがPOST/PUTの場合はkintone.plugin.app.proxyで指定されたデータ（リクエストボディ）に、保存した情報がリクエストに加わる条件を満たした設定情報のデータを付加したものとなります。（リクエストヘッダと同様の挙動）ただし、kintone.plugin.app.proxyで指定されたデータの型がObjectの場合のみ設定情報のデータを付加し、文字列の場合は付加しません。」

補足の記載について不明な場合はご返信にてお知らせください。
個別のトラブルシューティングや技術的なご質問はcybozu developer コミュニティをぜひご活用ください。

ishikawayuito 2022年02月01日 08:12

お世話になっております。

プラグインで一覧画面でkintone.app.getHeaderMenuSpaceElement()に

kintone ui compornentでドロップダウンを設置したいのですが

jsで設置した場合はきれいにでますが、プラグインのjsだと表示が一覧画面にかぶっていたりとずれてしまいます。APIの関係やほかのところに設置しなければいけないとかなにか制約はありますか？

cybozu Development team 2022年02月04日 01:02

ishikawayuito 様

お世話になっております。cybozu developer network 運営でございます

プラグインであっても、実際には通常のJavaScriptカスタマイズと同様のコード実行・API実行になるため、基本的には同一の動作になります。

意図した見た目にならない場合は、プラグインで設置したCSSが影響を与えていたりなどの要因が考えられます。

まずはChromeのDeveloper toolsなどを使い、意図したCSSが適用されているかデバッグを試みてください。

恐れ入りますが、上記から派生した技術的なご質問はcybozu developer コミュニティをご活用ください。

よろしくお願い致します。

Kento 2022年02月25日 08:00

お世話になっております。

kintone.plugin.app.proxy.uploadを利用してfreee会計に証憑ファイルをアップロードしたいと考えています。

全体の流れとしては、

添付ファイルフィールドのfileKeyを利用してファイルをダウンロード
freeeAPIのファイルボックス証憑ファイルのアップロードを使ってfreeeにアップロード

で考えています。

ソースコード

// ダウンロード
const file = await new KintoneRestAPIClient().file.downloadFile({
　　　　'fileKey': event.record.添付ファイル.value[0].fileKey,
});

const header = {
  'Authorization': 'Bearer ' + act, // actはアクセストークン
};
const blob = new Blob([file.buffer], {type: 'application/octet-binary'});
const data = {
  'format': 'RAW',
  'value': blob,
 };
const requestUrl = 'https://api.freee.co.jp/api/1/receipts/';
return kintone.plugin.app.proxy.upload(PLUGIN_ID, requestUrl, 'POST', header, data).then((resp)=> {
  result.status = resp[1]; // 1番目はstatusが格納
  return result;
});

【現象】

400エラーで終了する。内容を見ると「リクエストの形式が不正です。」とあります。

【質問】

freeeAPIリファレンスを見るとリクエストbodyにはcompany_idとreceiptが必要と書かれていますが、kintone.plugin.app.proxy.uploadを使う場合はどうやって付与すればよいのでしょうか？

cybozu Development team 2022年02月28日 00:56

Kento 様

お世話になっております。cybozu developer network 運営チームです。

こちらは記事に関するフィードバック欄です。
個別のトラブルシューティングや技術的なご質問はcybozu developer コミュニティをぜひご活用ください。

Nguyen Hang 2022年08月08日 23:40

お世話になっております。ハンと申します。

kintone.plugin.app.setConfig(config, successCallback)　を利用してAPIトークンの情報を保存しようと思いますが、実装方法のイメージがつかなくて教えていただきたいです。
実行できる画面は「プラグインごとの設定画面」と書いてありますが、具体的にどの手順でデータをプラグインに保管すればいいかご教示していただきたいと思います。

以上よろしくお願いいたします。

cybozu Development team 2022年08月10日 02:07

Nguyen Hang 様

お世話になっております。cybozu developer network 運営でございます。

プラグイン開発の手順などについてはプラグイン開発のTipsをご確認ください。
コードについての具体的な例については、Githubにサンプルプラグインを公開しているので、ぜひそちらもご活用ください。

また、恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
試してみてわからないなど記事から派生した技術的なご質問はcybozu developer コミュニティをご活用ください。

よろしくお願い致します。

サインインしてコメントを残してください。