目指せ!JavaScript カスタマイズ中級者(4)〜kintone REST API Client 編〜
はじめに
目指せ!JavaScriptカスタマイズ中級者(1)〜webpack 編〜 では複数のアプリカスタマイズを扱うための webpack の導入をしていました。
今回は同じ webpack の環境で、kintone REST API を扱うのに便利な kintone REST API Client をインストールして利用できるようにし、簡単に使い方をお伝えします。
目指せ中級者シリーズの記事一覧は以下を参照してください。
目指せ中級者シリーズ
kintone REST API Client とは
kintone REST API Client は、kintone REST API を利用するためのライブラリです。
たとえば次のようなレコードやアプリの操作が簡単にできます。
- レコード全件取得
- アップサート(既存のデータがあったらアップデートし、なかったらインサートする)
もともと、同じ用途のライブラリーとして
kintone JS SDK
というものもありますが、そちらは利用非推奨となっています。
今まで kintone JS SDK を使っていた方も今回紹介する kintone REST API Client をぜひ利用いただければと思います。
使うための準備
目指せ!JavaScriptカスタマイズ中級者(1) 〜webpack編〜 で説明したように JavaScript ファイルを build できるようになっているのが前提です。
下記をコマンドラインから入力し実行します。
|
|
これでインストールが始まり、kintone REST API Client を利用できます。
初めて利用する方は以下の記事の QuickStart をやってみるとよいでしょう。
kintone JavaScript Client (@kintone/rest-api-client)
使い方
GitHubのkintone-rest-api-client のページに利用方法などが書かれていますが、英語ですのでリファレンスのどこを参照すればよいかを説明します。
リファレンス
Record
レコードの取得や作成などレコードの操作に関することが記載されています。
通常、このリファレンスが基本になると思います。
App
アプリの設定変更の操作に関することが記載されています。
アプリの設定を自動で変更したいなどがあれば使いますが、見る頻度は基本的に低いはずです。
File
ファイルのアップロード、ダウンロードに関することが記載されています。
レコードにファイルを添付したい場合などもこちらを利用することになります。
BulkRequest
複数アプリへのレコード一括処理に関することが記載されています。
リファレンスの読み方
リファレンスの各項目には、その関数の説明と、Parameters(関数の引数)と Returns(関数の戻り値)があります。
英語で読み取れないところは Google 翻訳などを利用すれば理解の一助になるかと思います。
- 関数名
- 関数の説明
- 関数の戻り値
- 関数の引数
使用例
リファレンスに記載されているものから一部、使用例を次に示します。
async/await 形式で記述します。
参考にしてください。
レコードを取得
アプリ ID が「1」でレコード番号が「10」のレコードを取得したい場合の例です。
|
|
レコードを一括取得
2020 年 7 月定期メンテナンスで、それ以降に作られるアプリは offset 上限が 1 万件となってしまったため、レコードを全件取得する場合は カーソル API を使う必要があります。
ですが、kintone REST API Client ではカーソル API を意識せずとも次のように全件取得できます。
アプリ ID が「1」でフィールドコードが「price」、「price が 1000 以上のもの」を取得したい場合の例です。
|
|
レコードの作成
アプリ ID が「1」でフィールドコードが「fiel-cod-1」のフィールドに「サンプルテキスト」と入力されたレコードを作成したい場合の例です。
|
|
レコードの更新
アプリ ID が「1」でレコード ID が「10」、フィールドコードが「fiel-cod-1」のフィールドに「サンプルテキスト 2」と入力された状態にレコードを更新したい場合の例です。
|
|
レコードの複数更新
次のように、アプリ ID が「1」のアプリに対し、次のレコードを一括で更新したい場合の例です。
- レコード ID が「11」、フィールドコードが「fiel-cod-1」のフィールドに「サンプルテキスト 1」と入力
- レコード ID が「12」、フィールドコードが「fiel-cod-2」のフィールドに「サンプルテキスト 2」と入力
- レコード ID が「13」、フィールドコードが「fiel-cod-3」のフィールドに「サンプルテキスト 3」と入力
|
|
レコードのアップサート
アップサートとは、該当するレコードがなければインサート(挿入・新規作成)、該当するレコードがあればアップデート(更新)をするための機能です。
次の内容でアップサートする例です。
- アプリ ID が「1」
- 更新対象のレコード:更新のキーに利用するフィールドのフィールドコードが「fiel-key」で値が「apple」のレコード
- 更新内容:フィールドコードが「fiel-cod-1」のフィールドに「サンプルテキスト 1」と入力
|
|
サンプル
アプリ間のデータのやりとりで kintone REST API Client を中心に使ったサンプルを示します。
シナリオ
kintone アプリストアに、見積書アプリと商品リストアプリの 2 つのアプリがパックになっている「商品見積書パック」というものがあります。
見積書アプリで見積作成時に、ルックアップフィールドを用いて商品リストアプリにある商品を選べるものです。
それを利用して、次の仕様を満たすようアプリのカスタマイズと JavaScript カスタマイズを行います。
- 見積作成時(見積アプリでレコード保存時)に、選択されている商品の在庫数を減らす。
- 見積作成時(見積アプリでレコード保存時)に、選択されている商品の在庫がない場合はエラーを表示する。
保存時のイメージ
レコードを保存したときの動作イメージは次のとおりです。
- 保存時に、数量分の、在庫数がなければ保存させない。
- 在庫がある場合は、在庫引当処理を行う(商品リストアプリの在庫数をへらす)
なお「在庫数」フィールドは今回のサンプルで追加します。
アプリの用意と設定
アプリの用意
kintone アプリストアにある
商品見積書パック
を選び「このアプリパックを追加」を押して追加してください。
アプリの設定
商品リストアプリに、フィールド名とフィールドコードが「在庫数」のフィールドを追加してください。
また、見積書アプリからルックアップするためのレコードを 1 つ以上登録してください。
JavaScript カスタマイズ
コードを書き、ビルドしたものを見積書アプリにアップロードしてください。
コードは、以下のリポジトリにも公開しています。
https://github.com/cybozudevnet/sample-kintone-webpack-for-intermediate/tree/master/src/apps/quote
ビルドやアップロード方法については 目指せ!JavaScript カスタマイズ中級者(2)〜自動で一括ファイルアップロード編〜 などの記事を参照ください。
4 行目のアプリ ID については、環境に合わせて書き換えてください。
|
|
アップロードしたら、シナリオが実現できるか動作確認してください。
おわりに
kintone の JavaScript API をそのまま使い続けてももちろん問題ないですが、kintone REST API Client を使うとより簡単に REST でデータを扱えるようになるので、ぜひ利用してみてください。
この Tips は、2020 年 10 月版 kintone と @kintone/rest-api-client@1.7.0 で動作を確認しています。