第 10 回 kintone REST API を利用したレコード取得
初めて kintone をカスタマイズする人が kintone API の基礎知識を学べるよう、チュートリアルの内容を充実させてリニューアルしました。
リニューアル後のチュートリアルは次のページを参照してください。
はじめよう kintone API
はじめに
前回、kintone REST API を初めて利用しましたが、実はレコードの取得についても kintone REST API を利用できます。
今回は、レコードの一括取得や、検索条件(クエリ)を使ったレコード取得の方法も合わせて紹介します!
レコードの取得(1 件)
それでは、1 件のレコードの取得から試してみましょう。
レコードを取得するには、kintone REST API の
レコードの取得(GET) を利用します。
kintone REST API を kintone JavaScript API から利用する方法 は、前回紹介しましたね。
ではさっそく、これらを利用してレコードを取得する処理を書いてみましょう!
|
|
いかがでしょう?
ここでは、前回説明を省略した callback について少し補足しておきます。
成功時の callback に指定した無名関数を見てみてください。
|
|
成功時の callback はリクエストが成功した場合に実行され、API からの戻り値(レスポンス)は引数として渡されます。
今回の場合、API のレスポンスは resp
という変数に格納されており、取得したレコードの情報は JSON 形式で格納されています。
下記部分のコードでは、resp
から「レコード ID」の値を指定して、アラートに表示させる処理をしています。
|
|
なお、失敗時の callback については、省略可のため今回は記述していません。
それでは、この JavaScript を前回作成した参照ログアプリにアップロードして実行してみましょう。
内容が「recordId: <レコード ID>」になっているアラートが表示されれば成功です!
レコードを条件で絞り込む(クエリ)
kintone REST API でレコード情報を一括取得する API は、 複数のレコードを取得する ですが、この API を使うにあたって「クエリ」について押さえておきましょう。
レコード一覧のクエリ文字列を取得する を見てみてください。
この JavaScript API で、現在の検索条件にあたるクエリ文字列を取得できます。
さっそく確かめてみましょう。
|
|
クエリの書き方の例については、
kintone API のクエリの書き方の基本 を紹介する記事もあります。
クエリに対する理解を深めるため、他の検索条件もいろいろ試して、検索条件とクエリ文字列の関係を確かめてみましょう。
アプリの準備
第 7 回 カスタマイズビューを利用してみよう で、信号機のアプリを作りました。
今回は、このアプリを使って kintone REST API を利用したレコードの一括取得にチャレンジしてみましょう。
それでは、信号機のアプリのカスタマイズビューの設定を変えるところからはじめます。
下図のように、「ページネーションを表示する」のチェックを外した状態で更新し、一覧画面を表示してみてください。
第 7 回で追加した JavaScript により、以下のような表示になりましたね。
これは、「ページネーションを表示する」のチェックを外したため、event.records
にデータが格納されていないからです。
レコードの一括取得
今のままだとレコード情報がないため、kintone REST API を使ってレコードの一括取得を行いましょう。
それでは、
複数のレコードを取得する を確認してみましょう。
HTTP メソッド
GET
URL
https://(サブドメイン名).cybozu.com/k/v1/records.json
ゲストスペース内のアプリの場合は次のとおりです。
https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/records.json
必要なアクセス権
- アプリのレコード閲覧権限
- 値を取得するレコードの閲覧権限
- 値を取得するフィールドの閲覧権限
リクエストパラメーター
パラメーターの内容は、
複数のレコードを取得する のパラメーターを確認してください。
一括取得の場合、URL の records
が「複数形」なことに注意しましょう。
ここまで来ればリクエストは簡単に作れそうです。
fields
パラメーターは省略してよいので、それ以外の 2 つを指定してレコードを一括取得してみましょう。
|
|
できました。
ちなみにここまであえて触れませんでしたが、 複数のレコードを取得する で一度に取得できるレコード数は 100 件まで(オプションで 500 件まで)です。
レコードを一括取得する方法には、実は大きく 3 つの選択肢があり、利用ケースに応じて適切な方法を選択する必要があります。
それぞれの方法の特徴や使い分けについては、
offset の制限値を考慮した kintone のレコード一括取得について で紹介しています。
最後に
kintone JavaScript API も、kintone REST API を利用した方法もだいぶできるようになりましたね。
kintone API ドキュメント の中にはまだ紹介していない API もありますが、ここまで理解された皆さんはきっとドキュメントを読み進めながらより高度なカスタマイズができると思います。
この Tips は、2022 年 7 月版 kintone で動作を確認しています。
デモ環境
デモ環境で実際に動作を確認できます。
https://dev-demo.cybozu.com/k/16/
ログイン情報は cybozu developer network デモ環境 で確認してください。