目指せ！JavaScriptカスタマイズ中級者（４） 〜kintone REST API Client編〜

はじめに

目指せ！JavaScriptカスタマイズ中級者（１） 〜webpack編〜では複数のアプリカスタマイズを扱うためのWebpackの導入をしていました。
今回は同じWebpackの環境で、kintone REST APIを扱うのに便利なkintone REST API Clientをインストールして利用できるようにし、簡単に使い方をお伝えします。

シリーズの記事一覧はこちら。

kintone REST API Clientとは

レコード全件取得や、アップサート（既存のデータがあればアップデート、なければインサート）など、
レコードやアプリの操作を簡単にできるようにする、kintone REST APIを使うための便利なツールです。

※もともと、同じ用途のライブラリーとしてkintone JS SDKというものもありますが、そちらは利用非推奨となっております。
今までkintone JS SDKを使っていた方も今回紹介するkintone REST API Clientを是非利用いただければと思います。

使うための準備

目指せ！JavaScriptカスタマイズ中級者（１） 〜webpack編〜で説明したようにJavaScriptファイルをbuildできるようになっているのが前提です。

下記をコマンドラインから入力し実行します。

npm install @kintone/rest-api-client

使い方

GitHubのkintone-rest-api-clientのページに利用方法などが書かれていますが、英語ですのでリファレンスのどこを参照すればよいかを説明します。

リファレンス

• Record操作に関するリファレンス
  • ここではレコードの取得や作成などレコードの操作に関することが記載されています。通常、このリファレンスが基本になると思います。
• App操作に関するリファレンス
  • アプリの設定変更操作に関することが記載されています。アプリの設定を自動で変更したいなどがあれば使いますが、見る頻度は基本的に低いはずです。
• File操作に関するリファレンス
  • ファイルのアップロード、ダウンロードに関することが記載されています。レコードにファイルを添付したい場合などもこちらを利用することになります。
• BulkRequestに関するリファレンス
  • 複数アプリへのレコード一括処理に関することが記載されています。

リファレンスの読み方

リファレンスの各項目には、その関数の説明と、Parameters（関数の引数）とReturns（関数の返り値）があります。英語で読み取れないところはGoogle翻訳などを利用すれば理解の一助になるかと思います。

1. 関数名
2. 関数の説明
3. 関数の返り値
4. 関数の引数

使用例

リファレンスに記載されているものから一部、使用例を下記にしめします。async/await形式で記述します。参考にしてください。

レコードを取得

アプリIDが1, レコード番号が10のレコードを取得したい場合

レコードを一括取得

2020年7月定期メンテナンスで、それ以降に作られるアプリはoffset上限が1万件となってしまったため、レコードを全件取得する場合はカーソル APIを使う必要があります。

ですが、kintone REST API Clientではカーソル APIを意識せずとも下記のように全件取得できます。

アプリIDが1, フィールドコードがprice, priceが1000以上のものを取得したい場合

レコード作成

アプリIDが1, フィールドコードがfield_code_1に"サンプルテキスト"と入力されたレコードを作成したい場合

レコードをアップデート

アプリIDが1, レコードIDが10, フィールドコードがfield_code_1に"サンプルテキスト2"と入力された状態にレコードを更新したい場合

レコードを一括アップデート

下記のように3レコードを一括で更新したい場合

アプリIDが1, レコードIDが11, フィールドコードがfield_code_1に"サンプルテキスト1"
アプリIDが1, レコードIDが12, フィールドコードがfield_code_2に"サンプルテキスト2"
アプリIDが1, レコードIDが13, フィールドコードがfield_code_3に"サンプルテキスト3"

レコードをアップサート

アップサートとは、該当するレコードがなければインサート（挿入・新規作成）、該当するレコードがあればアップデート（更新）をするための機能です。

アプリIDが1, 更新のキーに利用するフィールドコードが"field_key", field_keyの値が"apple", 更新するフィールドコードがfield_code_1で更新内容が"サンプルテキスト1"の場合

サンプル

アプリ間のデータのやり取りでkintone REST API Clientを中心に使ったサンプルを示します。

シナリオ

kintoneアプリストアに、見積書アプリと商品リストアプリの2つのアプリがパックになっている「商品見積書パック」というものがあります。見積書アプリで見積作成時に、ルックアップフィールドを用いて商品リストアプリにある商品を選べるものです。

それを利用して、下記の仕様を満たすようアプリのカスタマイズとJavaScriptカスタマイズを行います。

1. 見積作成時（見積アプリでレコード保存時）に、選択されている商品の在庫数を減らす。
2. 見積作成時（見積アプリでレコード保存時）に、選択されている商品の在庫がない場合はエラーを表示する

保存時のイメージ

保存時に、数量分の、在庫数がなければ保存させない。在庫がある場合は、在庫引当処理を行う（商品リストアプリの在庫数をへらす）
※「在庫数」フィールドは今回のサンプルで追加します。

アプリの用意と設定

1.  アプリの用意
   kintoneアプリストアにある「商品見積書パック」を選び「このアプリパックを追加」を押して追加してください。
2. アプリの設定
   商品リストアプリに、フィールド名とフィールドコードが「在庫数」のフィールドを追加してください。また、見積書アプリからルックアップするためのレコードを1つ以上登録してください。

JavaScriptカスタマイズ

コードを書き、ビルドしたものを見積書アプリにアップロードしてください。
コードは、以下のリポジトリにも公開しています。
https://github.com/cybozudevnet/sample-kintone-webpack-for-intermediate/tree/master/src/apps/quote

4行目のアプリIDについては、環境に合わせて書き換えてください。

アップロードしたら、シナリオが実現できるか動作確認してください。

おわりに

kintoneのJavaScript APIをそのまま使いつづけてももちろん問題ないですが、kintone REST API Clientを使うとより簡単にRESTでデータを扱えるようになるので、ぜひ利用してみてください。

シリーズの記事一覧はこちら。

このTipsは、2020年10月版 kintone、@kintone/rest-api-client@1.7.0 で確認したものになります。