◇はじめに

本記事は 「すごくない」kintone　その４ Advent Calendar 2024 25日目の記事になります。

12月のアドカレ内でいくつかの記事を書かせていただきました。
今回は、それらの記事で使った、kintoneとGrafanaを連携してみました。

◇背景

先日、RPA Advent Calendarにて、kintoneタイムカード打刻に関する記事を書きました。

このデータを基に、社員の在室・不在状況を可視化するひと目でわかるようなダッシュボードを作ろうと考えたのですが、kintoneの基本機能のみだと自分が作りたい感じにできませんでした（プラグインを探せばあるかも）。

そこで、Linux Advent Calendarで書いた記事で使用した、Grafana＋Infinityプラグインの組み合わせを使ってkintoneのデータを取得し、ダッシュボードを作成できないかと考え、試すことにしました。

なお、上記記事ではDockerを使ってローカル上にGrafanaを構築していますが、今回はGrafana Cloudを使用しています（詳細は後述します）。

◇最終的にできたもの

最終的なGrafanaダッシュボード画面はこんな感じです。

上側のステータスカード表示では、各社員の最終出退勤ステータスを取得し、

出勤⇒在室
退勤⇒不在

という形で表示しています。

また、下のステータスタイムラインでは、出勤と退勤の状態を色分けて表示し、灰色が退勤、赤色が出勤を示しています。

◇開発環境等

使用ツール・サービス
- Edge
- kintone（PCブラウザ経由）
  - ライセンス：kintone開発者ライセンス
- Grafana Cloud
  - ライセンス：Cloud Free

◇実装手順

Grafana Cloudの環境構築
kintone側APIトークン発行
Postmanを使った動作確認
Grafana Cloudでのkintoneデータ取得
ダッシュボード作成

の順で記載していきます。

Grafana Cloudの環境構築

Grafana Cloudはクラウド上でGrafanaのダッシュボードを構築できるサービスです。

ライセンスがFree、Pro、Advancedの3つが用意されており、制限はありますが、Freeプランも存在します。

今回は、このFreeプランを使用して、ダッシュボードの作成を行っていきます。

アカウントを持っていない場合、まずはアカウントの作成を行います。

上記ページから「Create an account」を選択し、必要事項を入力していきます。

アカウント登録が完了すると、登録メールアドレス宛てに、Grafana CloudのURLが届くので、そのURLにアクセスします。

ログインしたら、画面左側のメニューからAdd new connectionを選択します。
次に検索ボックス上にInfinityと入力し、表示されるInfinityアイコンを選択します。

Infinityの画面を開いたら、右側にあるInstallを実行します。

ここまでできたら、kintoneのAPIトークンを発行します。

kintone側APIトークン発行

次に、kintone側の設定を行います。
アプリ自体は前回の記事で作成したものをそのまま使います。

今回は、Grafanaからkintoneのデータを取得するためのAPIトークンの発行だけ行います。

タイムカードアプリの設定画面から、「APIトークン」を選択します。

生成するボタンをクリックし、APIトークンを発行します。アクセス権については、今回はデータの取得だけで問題ないため、「レコード閲覧」のチェックのみ有効にしておきます。
このトークンは後で使うので、メモ帳等に保存しておきます。

Postmanを使った動作確認

APIトークンを使って動作確認をするにあたり、まずはPostmanを使ってデータ取得を試してみます。
なお、こちらも別記事で詳細を書いているため、今回はコレクション作成などの部分は省略します。

今回はタイムカードのデータを複数取得したいので、複数のレコードを取得するためのREST APIを呼出します。
kintoneの公式ドキュメントを参考にして、URLやパラメータを設定していきます。

公式ドキュメントを参考にしつつ、今回は以下のようなリクエストAPIを作成します。

なお、事前に以下3つの変数を設定しておきます。

baseUrl：kintone REST API用のベースURL
appId：最初に登録したアプリのIDを入力
apiToken：先ほど発行したトークンを入力

URL部分の?以降のクエリパラメータは、下の「クエリパラメーター」に項目を追加していけば自動的にURLのほうにも反映されます。

今回設定したクエリパラメータでは、
2024/12/17以降でレコード番号が大きい上位10件のデータを取得する
といった形になります。

ヘッダー側にはAPIトークンを以下のように設定します。

「送信」ボタンを選択して、200 OKのレスポンスが表示されれば成功です。
レスポンスデータの一部を記載します。
この応答結果を参考にして、次にGrafanaからkintoneデータの取得を試します。

{
    "records": [
        {
            "レコード番号": {
                "type": "RECORD_NUMBER",
                "value": "56"
            },
            "時刻": {
                "type": "TIME",
                "value": "14:00"
            },
            "出退勤ステータス": {
                "type": "DROP_DOWN",
                "value": "出勤"
            },
            "従業員名": {
                "type": "SINGLE_LINE_TEXT",
                "value": "佐藤 幸子"
            },
            "日付": {
                "type": "DATE",
                "value": "2024-12-22"
            }
        },
        ・・・
        {
            "レコード番号": {
                "type": "RECORD_NUMBER",
                "value": "47"
            },
            "時刻": {
                "type": "TIME",
                "value": "13:00"
            },
            "出退勤ステータス": {
                "type": "DROP_DOWN",
                "value": "出勤"
            },
            "従業員名": {
                "type": "SINGLE_LINE_TEXT",
                "value": "鈴木 達夫"
            },
            "日付": {
                "type": "DATE",
                "value": "2024-12-21"
            }
        }
    ],
    "totalCount": null
}

Grafana Cloudでのkintoneデータ取得

あたらめてGrafanaを開いて、今度はメニューからData sourceを選択し、先ほどと同様にInfinityを検索して表示されるアイコンを選択します。

Settingsの項目でkintoneデータと接続するための各種設定を行います。

Authenticationの項目では、認証用の設定を行います。
先ほどPostmanでやったように、X-Cybozu-API-TokenキーのバリューにAPIトークンを設定します。
追加先はAdd to Headerを選択します。

もう一つ、画面下部にある、Allowed hostsに接続するkintoneのURLを入力します。
たとえば、https://xxxxxxx.cybozu.comという感じです。

URL, Headers & ParamsにはkintoneのBase URLを入力しておきます。

ここまでで、データソースの設定ができたので、実際にデータの取得を試します。

ビジュアライズの追加を選択し、各項目を入力していきます。
Postmanで設定した入力項目を参考にしつつ、URL Query Paramsの各項目を入力します。

設定画面をそのまま下にスクロールし、Rows/Root、Columnsの項目を以下のように設定します。
これは、Postmanで試した結果を基に、"type"を取り除いて"value"の値だけを取り出すための処理になります。

最後に、画面情報のTable viewを有効にして、データが表形式で表示されていればデータが正しく取得できています。

ダッシュボード作成

最後に、Grafana上でダッシュボードを作成します。

まずは、下側のステータスタイムラインのほうから試します。

ビジュアルはState timelineを選択します。
Transformationタブを開いて、

日付データと時刻データを結合して日時データを作成
表示するフィールドを「従業員」と「ステータス」、「日時」に限定
従業員ごとに分割

といった処理を順に行っています。

1.日時データの作成では、Add field from calculationとConvert field typeを実行します。
Add field from calculationでは、既存フィールドを結合するなどして、新規のフィールドを作成できます。
今回は、日付フィールドと時刻フィールドを文字列結合して、日時フィールドを作成しています。

処理後のテーブルビューを確認すると、右側に日時フィールドが作成できていることがわかります。

作成した日時フィールドはこのままだと文字列型になってしまうので、Convert field type処理で型をにt時形式の型に変換します。

日時フィールドを指定して、型をTimeに変更します。

処理後、日時フィールドの型が変わっていることを確認します。

2.表示するフィールドの限定では、Organize fields by nameを使用します。

現在、表示されているフィールド一覧から非表示にするフィールドの👁️アイコンをオフにします。
なお、今回は変更していませんが、フィールド名をリネームすることもできます。

処理後に表示されるフィールドが酸くなっていることが確認できます。

3.従業員ごとに分割では、Partition by valuesを使います。

今回は、従業員ごとにステータスバーを分けたいので、従業員フィールドを指定します。
なお、右上にもあるように、この処理はAlpha版になるので、動作が不安定な可能性があります。

テーブルビューで確認すると、従業員ごとにデータが表示されていることが確認できます。
従業員の項目を選択すると、別の従業員のデータに切り替えられます。

ここまでで、データの変換処理は終わったので、ビジュアルの設定を行います。

表示はState timelineを選択し、Value mappingの設定を行います。
現状、出退勤ステータスは出勤と退勤という文字列情報のため、これを扱いやすくするために、

出勤は1
退勤は0

となるようなマッピング処理を行います。

あとはバーの太さや透明度などを好みの設定にしてあげれば最初に示した画像と同じような表示が可能です。

次に、上側のステータスカードについても表示を行っていきます。
ビジュアルはStatを選択します。
Transformationタブを開いて、

日付データと時刻データを結合して日時データを作成
「日時」フィールドでソート
従業員ごとグループ化してそれぞれの最新のステータスを取得

といった流れでデータ変換処理を行っていきます。

1.日時データの作成は先ほどと同じ処理のため省略します。

2.「日時」フィールドでソートでは、Sort byを使います。
テーブルビューをONにし、最新日時のデータが上側に来ることを確認します。
逆に古いデータが上に来た場合は、右側のRecerseをONにしてみてください。

3.従業員ごとグループ化して最新のステータスを取得には、Group byを使用します。
Group byでグループ化するフィールドは従業員フィールドを使用し、ステータスフィールドでは、最初の値1個を抽出するように設定しています。
こうすることで、事前にソートしていたデータの最初の値（最も新しい日時のデータ）を取得する形になります。

テーブルビューで確認すると、従業員名とステータスのみのデータ構造になっていることがわかります。

最後にこちらも、ビジュアルの設定を行います。

表示はStatを選択し、先ほどと同様Value mappingの設定を行います。
今回は以下のように設定しています。

出勤⇒在室
退勤⇒不在

各社員の最終出退勤ステータスを取得しているため、出勤＝在室という前提にしています。

また、FieldsやText modeの設定は以下の画像のように設定します。

ここまでで、ダッシュボードの設定ができたので、保存します。

動作確認の方法については、実際にkintoneアプリ上から出勤or退勤データを追加し、その追加データがダッシュボード上に表示されているかをか確認すればOKです。（今回は画像キャプチャなどは省略します）

◇おわりに

今年のアドベントカレンダー内で主に使用した、Grafanaとkintoneを組み合わせた記事を最後に書くことができました。

kintoneデータの可視化の手段の一つとして、参考になれば幸いです。

🔚END