kintone REST API Clientを使って、kintone REST APIを実行してみよう
はじめに
商品の在庫を管理するカスタマイズを通して、
kintone REST API Client
の使い方を紹介します。
この記事ではwebpackを使ったプロジェクトを使って、kintoneをカスタマイズします。
webpackを知らない方は、次の記事を参照してください。
kintoneカスタマイズにwebpackを導入するメリット
を参照してください。
kintone REST API Clientとは
kintone REST API Clientは、kintone REST APIを利用するためのライブラリです。
たとえば次のようなレコードやアプリの操作が簡単にできます。
- レコード全件取得
- アップサート(既存のデータがあったらアップデートし、なかったらインサートする)
もともと、同じ用途のライブラリーとして
kintone JS SDK
というものもありますが、そちらは利用非推奨となっています。
今までkintone JS SDKを使っていた方も今回紹介するkintone REST API Clientをぜひ利用いただければと思います。
使うための準備
kintoneカスタマイズに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/kintone-samples/sample-kintone-webpack-for-intermediate/tree/master/src/apps/quote
ビルドやアップロード方法については customize-uploaderを使って、複数のkintoneアプリにkintoneカスタマイズファイルを自動でアップロードしよう の記事を参照ください。
4行目のアプリIDについては、環境に合わせて書き換えてください。
|
|
アップロードしたら、シナリオが実現できるか動作確認してください。
おわりに
kintoneのJavaScript APIをそのまま使い続けてももちろん問題ないですが、kintone REST API Clientを使うとより簡単にRESTでデータを扱えるようになるので、ぜひ利用してみてください。
このTipsは、2020年10月版kintoneと @kintone/rest-api-client@1.7.0で動作を確認しています。