第 10 回 kintone REST API を利用したレコード取得

固定リンクがコピーされました

著者名：落合雄一

はじめに

固定リンクがコピーされました

前回、kintone REST APIを初めて利用しましたが、実はレコードの取得についてもkintone REST APIを利用できます。
今回は、レコードの一括取得や、検索条件（クエリ）を使ったレコード取得の方法も合わせて紹介します！

レコードの取得（1 件）

固定リンクがコピーされました

それでは、1件のレコードの取得から試してみましょう。
レコードを取得するには、kintone REST APIのレコードの取得（GET）を利用します。

kintone REST API を kintone JavaScript API から利用する方法は、前回紹介しましたね。
ではさっそく、これらを利用してレコードを取得する処理を書いてみましょう！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/*
 * Tutorial sample
 * Copyright (c) 2014 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

(() => {
  'use strict';
  kintone.events.on('app.record.detail.show', (event) => {

    // リクエストパラメータ
    const body = {
      app: kintone.app.getId(),
      id: 1
    };

    kintone.api(
      kintone.api.url('/k/v1/record', true), // pathOrUrl
      'GET', // method
      body, // params
      (resp) => { // 成功時のcallback
        alert('recordId:' + resp.record.$id.value);
      }
    );
  });
})();

いかがでしょう？
ここでは、前回説明を省略したcallbackについて少し補足しておきます。
成功時のcallbackに指定した無名関数を見てみてください。

23
24
25


(resp) => { // 成功時のcallback
  alert('recordId:' + resp.record.$id.value);
}

成功時のcallbackはリクエストが成功した場合に実行され、APIからの戻り値（レスポンス）は引数として渡されます。
今回の場合、APIのレスポンスはrespという変数に格納されており、取得したレコードの情報はJSON形式で格納されています。

下記部分のコードでは、respから「レコードID」の値を指定して、アラートに表示させる処理をしています。

24

alert('recordId:' + resp.record.$id.value);

なお、失敗時のcallbackについては、省略可のため今回は記述していません。

それでは、このJavaScriptを前回作成した参照ログアプリにアップロードして実行してみましょう。
内容が「recordId: <レコードID>」になっているアラートが表示されれば成功です！

レコードを条件で絞り込む（クエリ）

固定リンクがコピーされました

kintone REST APIでレコード情報を一括取得するAPIは、複数のレコードを取得するですが、このAPIを使うにあたって「クエリ」について押さえておきましょう。

レコード一覧のクエリ文字列を取得するを見てみてください。
このJavaScript APIで、現在の検索条件にあたるクエリ文字列を取得できます。
さっそく確かめてみましょう。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/*
 * Tutorial sample
 * Copyright (c) 2014 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

(() => {
  'use strict';
  kintone.events.on('app.record.index.show', (event) => {
    // レコード一覧のクエリ文字列を取得する（order by, limit, offset付き）
    const currentQuery = kintone.app.getQuery();
    alert(currentQuery);
  });
})();

クエリの書き方の例については、 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つを指定してレコードを一括取得してみましょう。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


/*
 * Tutorial sample
 * Copyright (c) 2014 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

(() => {
  'use strict';
  kintone.events.on('app.record.index.show', (event) => {
    if (event.viewName !== 'カスタマイズビュー') {
      return;
    }

    // リクエストパラメータ
    const requestParam = {
      app: kintone.app.getId(),
      query: kintone.app.getQuery()
    };

    // カスタマイズビューにレコード表示
    const myDisplayCustomizedView = records => {
      if (records.length === 0) {
        document.getElementById('my-customized-view').innerText = '表示するレコードがありません';
        return;
      }

      const recUrl = location.protocol + '//' + location.hostname + '/k/' + kintone.app.getId() + '/show#record=';
      const myRecordSpace = document.getElementById('my-tbody');
      myRecordSpace.innerText = '';

      for (let i = 0; i < records.length; i++) {
        const record = records[i];
        const row = myRecordSpace.insertRow(myRecordSpace.rows.length);
        const cell1 = row.insertCell(0);
        const cell2 = row.insertCell(1);
        const cell3 = row.insertCell(2);

        const tmpA = document.createElement('a');
        tmpA.href = recUrl + record.レコード番号.value;
        tmpA.innerText = record.レコード番号.value;
        cell1.appendChild(tmpA);

        cell2.innerText = record.信号の色.value;
        const createdAt = new Date(record.作成日時.value);

        cell3.innerText = createdAt.toLocaleString();
      }
    };

    kintone.api(kintone.api.url('/k/v1/records', true), 'GET', requestParam, (resp) => {
      // 取得レコード: resp.records
      myDisplayCustomizedView(resp.records);
    });
  });
})();

できました。

ちなみにここまであえて触れませんでしたが、複数のレコードを取得するで一度に取得できるレコード数は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 デモ環境で確認してください。

旧：はじめよう kintone JavaScript API