カスタマインを使ってkintoneのレコード内を探検しに行こう！ - アールスリーインスティテュート

公開日：2025-02-20

注意

本記事は情報提供を目的としており、本記事の内容は無保証、サポートの対象外です。
サポート窓口、問合せ窓口にご質問をいただいても対応いたしかねますのでご了承ください。

こんにちは！システム開発グループ所属のすずきです！

今回はkintoneのレコードがどんなデータ構造になっているかを、プログラミングの経験がない方へ、できるだけわかりやすくご紹介したいと思います。

kintoneのデータ構造への理解が深まり、シンプルかつ効率的なkintoneアプリのカスタマイズが可能になるはずです！

kintoneアプリをJavaScriptや弊社のgusuku Customine（以下カスタマインと呼称）を使ってカスタマイズする際に、レコードを取得して参照・加工することがありますよね。

カスタマインでは、データ構造をそこまで意識しなくてもある程度は機能を作れるようになっているので、気にされたことが無い方も多いのではないかと思います。

データ構造については cybozu developer networkのフィールド形式のページにフィールド毎に詳しく書いているのですが、ここではカスタマインでレコードのデータを扱う場合、という視点を軸に、どういう構造になっているかをご紹介したいと思います。

出発準備

では早速、実際のkintoneのレコードのデータを見てみましょう。カスタマインがあれば簡単に見る方法があります！それは「コンソールにアクションの結果を出力する」を使う方法です。

通常、レコードを表示するとしたら、「レコードの一覧をポップアップで表示する」や「レコードの一覧をスペースに表示する」を使うと思います。

ユーザーはコンソールなんて見ませんから、これを使って機能を実現する、ということは無いと思いますが、アクションの結果をデータ構造込みで表示してくれるので、デバッグ時には強い味方になってくれます！

ということでカスタマイズはこちら。

一覧画面でレコードを取得し、それの結果をコンソールに表示するというシンプルなものです。

いざ出発！

設定が終わったらアプリの一覧画面を開き、コンソールを確認してみましょう。

（コンソールの表示の仕方はこちら）

赤枠で表示した部分がレコードのデータです。これだけだとなんのこっちゃ？って感じですね。これはレコードのデータが階層構造になっていて、まだ中を開けていないからです。

さて、この画像を見た時点で、「あ…帰ろう。」と思われる方、ちょっと待ってください！マイルドになるように、ダンジョン風の見た目を用意しております。

ダンジョン内部へ・・・

こちらがアクション36ダンジョンです！中に入ると、アクション36で取得した各レコードの扉が、取得した順に並んでいます。カウントは0番目から始まり、1、2、3となります。

レコードを取得するタイプのアクションの結果は、常に複数のレコードのかたまりの形式になっています。もし結果的に取得されたレコードが1つしかなくても、アクションの結果→0番目のレコード、と順番にアクセスする必要があり、いきなりフィールドと対面できるわけではありません。

レコードの扉を開けると、フィールドの扉が並んでいます。

この扉を入れば、いよいよその先にフィールドの「値」が待っています！

（本当は扉の先に「type」と「value」の扉が並んでいて、値が入っているのは「value」の方なのですが、カスタマイン上では勝手に「value」の扉に入ってくれるようになっています。助かる！

「type」の方にはフィールド形式の情報が入っているのですが、特に用は無いですね）

ついに最深部に到着！

では、ここまでの道のりを振り返ってみましょう。アクション36の結果→0番目のレコード→フィールドと来たわけですね。これをカスタマイン上で表現すると、

=式なら「= $36[0].フィールドコード」、${式}なら「$($36[0].フィールドコード)」となり、例えば「情報ダイアログを表示する」のメッセージでこの式を設定すれば、0番目のレコードのフィールドの値が出力できます。

また、Excel/PDF出力のExcelテンプレート内でも同様に、「$(0)(フィールドコード)」のように指定すれば、0番目のレコードのフィールドの値が出力できます。

値が複数あるフィールド

文字列（1行）や数値、ドロップダウンなど、値が一つしかないフィールドはここでゴールですが、チェックボックスや複数選択など、複数の値が存在するフィールドもあります。

チェックボックス・複数選択の値は、チェック状態になっている選択肢が並ぶ形式になっています。

これは「リスト」と呼ばれる形式で、一つの部屋の中にデータが順序付きで並んでいるデータです。カスタマイン上では、「= $36[0].フィールドコード[0]」のように開ける扉を指定することで、その中の一つだけを指定して取り出すことができます。

ところで、さっき似たような景色を見ましたよね。そう、ダンジョンに入ってすぐの廊下と同じです。実は最初のアクションの結果自体もリスト形式になっているので、似たような表現にしています。リストの中に入っている各データの複雑さに差があるので、全然異なるように感じますが、扉に入る前は同じ形をしています。

さらに複雑なフィールド

ユーザー選択や添付ファイルもリストなのですが、もう一段階奥があります。

ユーザー選択フィールドは複数のユーザーを選択できるうえ、1ユーザー分のデータはcode（ログイン名）とname（表示名）で構成されています。

どちらのデータが欲しいかによって、「= $36[0].ユーザー選択[0].code」のように指定します。

添付ファイルフィールドも、複数のファイルを添付できるうえ、1ファイル分のデータの中には、ファイル自体にアクセスするのに必要なfilekeyの他に、name（ファイル名）やsize（ファイルサイズ）のデータも入っています。

そして、なんといっても一番複雑なのは言わずもがな、テーブルですね。このダンジョンのラスボスと言ってもいいでしょう。

テーブルもリストになっていて、中にさらに各行のフィールドの情報が入っているので、最初に取得したレコードのリストに似ています。ラスボスそのものが新たなダンジョンだった、ということですね。エンディングが近そうな展開です。

一旦引き返して今度はカスタマインに行かせよう

これでダンジョンのマップが把握できましたね。これでカスタマインで中のデータを参照する方法もわかると思います。

あえて一番ややこしい例を出すと、「アクション36で取得したうちの、一つ目のレコードの、テーブルの2行目の、ユーザー選択フィールドで選択されているユーザーのうち3人目の表示名」をカスタマインの式で参照する場合は、「=$36[0].テーブル[1].ユーザー選択[2].name」となります。

リストの活用法

ここまでいろいろなリストが登場しましたが、リストの扱い方を知っていれば、複雑な処理を組むことができます。

活用法①

「リストから要素を取り出す」とループ処理を組み合わせてリスト内の要素の数だけ処理を繰り返す、といったことができます。レコードやテーブル行の数だけ繰り返すのによく用いられますが、チェックボックスやユーザー選択の数だけ処理を繰り返すことも可能です。

ループ処理については、詳しくは「リストから要素を取り出す」の活用方法の記事をご覧ください。

活用法②

Excel/PDF出力のExcelテンプレート内でgusukuコマンドの$FOREACH(フィールドコード)および $ENDを使えば、リストの要素の数だけ行を増やすことができます。こちらもテーブル行や関連レコード一覧のレコードの数だけ行を増やすのによく使われますが、例えば添付ファイルの数だけ行を増やして、全添付ファイルを表示する、といったことにも使えます。

特殊なフィールドのデータ

余談ですが、一つのレコードのデータの中に、フィールドではない見慣れないデータがありましたね。こちらについても軽く紹介します。

$id

ほとんどの場合、レコード番号と同じ値になっています。レコード番号の方はアプリに「アプリコード」を設定していると「アプリコード-1」のようにアプリコードがくっつきますが、$idの方はレコード番号の番号部分のみが入っています。

$revision

このレコードが今までに何回更新されたかを示す数字です。変更履歴にも表示されています。

ただ、変更履歴の一番上に書いている数字と、現在のリビジョン番号が合わない場合があります。というのは、レコードの更新で何も値が変わらなかった場合は、リビジョン番号は進みますが、変更履歴には記録されないからです。ですので、例えば動作を確認するときに「レコードの更新に失敗した」のか「レコードの更新には成功したが何も値が変わらなかった」のかを見分けるのに使うことができます。

まとめ

今回の探検はこれでおしまいです！

今回はご紹介しきれませんでしたが、kintoneには他にもいろいろなフィールドがあります。今アプリを作っていらっしゃる方、特にデバッグで悩まれている方は一度、アプリのレコードのデータの中を探検してみてはいかがでしょうか？

きっと新たな発見がありますよ！

投稿者プロフィール

すずき: kintoneがメインのエンジニアです。空き時間の半分を合気道に使います。