Index
プラグインに設定を保存する
キーと値を対にして、オブジェクト形式でプラグインに設定を保存できます。
最後に保存した設定だけが保持されます。
関数
kintone.plugin.app.setConfig(config, successCallback)
引数
引数 | 型 | 必須 | 説明 |
---|---|---|---|
config | オブジェクト | 必須 |
キーと値を対にしたオブジェクトの形式で、プラグインに保存する設定を指定します。 例: { "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 を実行する
プラグインから外部 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 | オブジェクト/文字列 | 必須 |
リクエストデータを指定します。 指定した値は、POST または PUT の場合のみ利用されます。 |
successCallback | 関数 | 省略可 |
リクエストが完了したあとに実行する関数を指定します。関数の引数には、次の 3 つの情報が渡されます。
省略した場合は kintone.Promise オブジェクトが返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。 |
failureCallback | 関数 | 省略可 |
リクエストが失敗した場合に実行する関数を指定します。 省略した場合は 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"}
- 設定 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, 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 のいずれかで指定します。 |
返り値
返り値の例
実行できる画面
プラグインごとの設定画面
サンプルコード
プラグインから外部にファイルをアップロードする
プラグインから外部にファイルをアップロードすることができます。
外部 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" のみ指定できます。 |
successCallback | 関数 | 省略可 |
リクエストが完了したあとに実行する関数を指定します。
省略した場合は kintone.Promise オブジェクトが返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。 |
failureCallback | 関数 | 省略可 |
リクエストが失敗した場合に実行する関数を指定します。 |
返り値
引数の successCallback を省略した時、kintone.Promise オブジェクトを返します。
参考: イベントハンドラを登録する
successCallback を指定した場合返り値はありません。
実行できる画面
次の画面で実行できます。
PC での次の画面
- レコード一覧
- レコード詳細
- レコード追加
- レコード編集
- レコード印刷
- グラフ
モバイルの次の画面
- レコード一覧
- レコード詳細
- レコード追加
- レコード編集
サンプルコード
コールバックを使った記述方法
kintone.Promise オブジェクトを使った記述方法
注意事項
- url で存在しないサーバーを指定した場合、レスポンスはステータスコード「503」(DNS Cache Missing)のエラーとなります。
制限事項
- 対象のブラウザは、動作環境の Web ブラウザー に準じます。
- "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'}を指定している状態です)。
以下環境情報です。
お手数おかけしますがよろしくお願いいたします。
sato.m 様
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 コミュニティをぜひご活用ください。
お世話になっております。
プラグインで一覧画面でkintone.app.getHeaderMenuSpaceElement()に
kintone ui compornentでドロップダウンを設置したいのですが
jsで設置した場合はきれいにでますが、プラグインのjsだと表示が一覧画面にかぶっていたりとずれてしまいます。APIの関係やほかのところに設置しなければいけないとかなにか制約はありますか?
ishikawayuito 様
お世話になっております。cybozu developer network 運営でございます
プラグインであっても、実際には通常のJavaScriptカスタマイズと同様のコード実行・API実行になるため、基本的には同一の動作になります。
意図した見た目にならない場合は、プラグインで設置したCSSが影響を与えていたりなどの要因が考えられます。
まずはChromeのDeveloper toolsなどを使い、意図したCSSが適用されているかデバッグを試みてください。
恐れ入りますが、上記から派生した技術的なご質問はcybozu developer コミュニティをご活用ください。
よろしくお願い致します。
お世話になっております。
kintone.plugin.app.proxy.uploadを利用してfreee会計に証憑ファイルをアップロードしたいと考えています。
全体の流れとしては、
で考えています。
ソースコード
【現象】
400エラーで終了する。内容を見ると「リクエストの形式が不正です。」とあります。
【質問】
freeeAPIリファレンスを見るとリクエストbodyにはcompany_idとreceiptが必要と書かれていますが、kintone.plugin.app.proxy.uploadを使う場合はどうやって付与すればよいのでしょうか?
Kento 様
お世話になっております。cybozu developer network 運営チームです。
こちらは記事に関するフィードバック欄です。
個別のトラブルシューティングや技術的なご質問はcybozu developer コミュニティをぜひご活用ください。
お世話になっております。ハンと申します。
kintone.plugin.app.setConfig(config, successCallback) を利用してAPIトークンの情報を保存しようと思いますが、実装方法のイメージがつかなくて教えていただきたいです。
実行できる画面は「プラグインごとの設定画面」と書いてありますが、具体的にどの手順でデータをプラグインに保管すればいいかご教示していただきたいと思います。
以上よろしくお願いいたします。
Nguyen Hang 様
お世話になっております。cybozu developer network 運営でございます。
プラグイン開発の手順などについてはプラグイン開発のTipsをご確認ください。
コードについての具体的な例については、Githubにサンプルプラグインを公開しているので、ぜひそちらもご活用ください。
また、恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
試してみてわからないなど記事から派生した技術的なご質問はcybozu developer コミュニティをご活用ください。
よろしくお願い致します。