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

著者名: 落合 雄一 (External link)

目次

information

初めて kintone をカスタマイズする人が kintone API の基礎知識を学べるよう、チュートリアルの内容を充実させてリニューアルしました。
リニューアル後のチュートリアルは次のページを参照してください。
はじめよう kintone 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 もありますが、ここまで理解された皆さんはきっとドキュメントを読み進めながらより高度なカスタマイズができると思います。

information

この Tips は、2022 年 7 月版 kintone で動作を確認しています。

デモ環境

デモ環境で実際に動作を確認できます。
https://dev-demo.cybozu.com/k/16/ (External link)

ログイン情報は cybozu developer network デモ環境 で確認してください。