rex0220 kSQL アクションプラグイン - ② 一覧編（選択したレコードをまとめて処理する）

「rex0220 kSQL アクションプラグイン」の実践編です。

一覧画面のアクションパネル、業務ごとに束ねる区分、一覧ごとの出し分け、そして選択したレコードの一括処理（1 件ずつ / まとめて 1 回 / グループごと）をまとめます。モバイルでの見え方にも触れます。

シリーズ: 概要 / ① 詳細画面 / ② 一覧（この記事） / ③ 集計 / ④ 運用 / ⑤ 事例 / ⑥ イベント / ⑦ オーサリング / ⑧ 請求データ / ⑨ 締めの画面 / ⑩ どこに出すか / ⑪ 多言語 / ⑫ オーサリング改善

一覧画面

アクションパネル

一覧のヘッダー部（ツールバーの下）に、折りたたみ式のアクションパネルを表示できます。アクションの名前と説明が並び、ここから実行します。カスタマイズビュー（ほぼ空の一覧）に出せば、アクション実行の専用画面として運用できます。

業務ごとに束ねる（区分）

アクションが増えるとパネルのボタンが並びすぎるので、アクションごとに「区分」を付けて業務ごとに束ねられます。区分は設定画面の上の［パネル・区分］で定義し（有効・名称・ボタンの色・既定で畳むか）、設定画面の「区分」の列でアクションごとに選びます。初めは無効の 3 行（区分1〜3）が入っているので、使う区分を有効にして名前と色を決めます。同じ区分のアクションがパネルの 1 つの節になり、節ごとに畳めます。節の順は区分の表の並び（行番号の ≡ を掴んで入れ替え）、区分を付けていないアクションは見出しなしで先頭に並びます。

列なので、コピー・貼り付けで何件でもまとめて振れます。色は決め打ちの 8 色（淡い地色に濃い文字）から選び、ボタンと節の見出しに付きます。ふだん使わない業務の節は「既定で畳む」にしておけます。

区分を横に並べる

区分は既定では縦に積みます。ボタンが 2 個しかない区分でも幅いっぱいを占めるので、右半分が空いて縦に長くなります。

［パネル・区分］にある 「1 行に並べる区分」 を増やすと、区分が横に並びます（1〜6。既定は 1 = 縦積み）。

区分が 3 つなら 1 行に収まります。ボタンが 4 個の「請求」は、狭くなった分だけ 2 行に折り返します。

指定するのは最大の列数です。画面が狭くてボタンの幅が入らなくなると、自動で列が減ります（6 → 5 → 4 …）。モバイルは常に 1 列です。

区分が狭くなるとボタンは折り返すので、4 個の区分は 2 行になります。ボタンの幅も同じ「一覧パネル」で変えられます（120〜400px。既定 200）。

区分を横に	ボタンの幅
2〜3 個	既定の 200 のままで足ります
4 個以上	下げないとボタンの名前が切れます（1360px の画面で 6 列にすると、区分 1 つは 200px ほどしかありません）

列がボタンの幅より広ければ、ボタンは列いっぱいに伸びます（モバイルは常に幅いっぱいで、この設定は効きません）。

区分の表の「原色」にチェックを入れると、淡い地色ではなく色そのものを塗ったボタン（白い文字）になります。区分ごとに選べるので、よく押す区分だけ目立たせる、といった使い方もできます。

ボタンからログ一覧を開く

ログアプリを指定して、パネルの設定で「ボタンにログへのリンクを出す」を入れると、ボタンの右上に時計のアイコンが出ます（既定では出しません。帯と区分の見出しのリンクは、入れなくても出ます）。押すと、そのアクションの記録だけに絞り込んだログアプリの一覧が新しいタブで開きます（profile と script_name の完全一致で絞るので、ログアプリを複数のアプリで分け合っていても混ざりません）。ログアプリ側に「開始日時・種別・ステータス・スクリプト名・件数」だけを並べた一覧を作っておき、共通設定の「ログ一覧」でその一覧を選んでおくと読みやすくなります。

「最近の実行」を浮かせて出す

「最近の実行」を帯のアイコンから浮かせて出せます（共通設定のログアプリのタブで「一覧パネルに「最近の実行」を出す」をチェック）。浮かせているので、出し入れしてもアクションのボタンの大きさや位置は変わりません。出し入れはパネルの帯のアイコン 1 つ（Esc でも閉じます）で、押した状態は次に開いたときも覚えています。

日付の見出しの下に 1 行ずつ、時刻・ボタン名・件数・状態（SUCCESS / FAILED / RUNNING …）が新しい順に並び、行を押すとそのログのレコードが新しいタブで開きます。実行中の行は件数の代わりに経過の分が出るので、「まだ動いている」のか「残ってしまったロック」なのかが分かります。失敗の行はうっすら赤く、日付と実行者は行の吹き出しで見えます。

表示件数（既定 20 件）と自動更新の間隔（既定 10 分。0 で自動更新なし）は設定で決められます。出している間だけログアプリに問い合わせるので、隠しておけば余計な通信はしません（ログアプリの閲覧権限が無い人には枠が出ません）。

メニューのボタン

一覧のヘッダーメニューにもボタンを置けます。パネルを使わない単純な操作向けです。

一覧ごとに、出す区分を決める

どの一覧に何をどう出すかは、画面 × 区分の表で決めます（設定画面の上の［パネル・区分］）。一覧ごとに、区分を「パネル」「メニュー」「出さない」から選ぶだけです。メニューは区分ごとに 1 つ作られ、名前は区分名になります（区分なしはボタンを直接並べます）。アクションを足したときは区分を選べば、その区分を出している一覧すべてに自動で並びます。行の無い一覧は「ほかの一覧すべて」の行に従うので、一覧を新しく作っても設定し直す必要はありません。カレンダーやカスタマイズビューも行にできるので、「アクション専用の一覧」を 1 つ作ってそこだけに出す運用もできます。

区分を足して名前を入れると、この表にその区分の列がすぐ出ます。有効にした一覧では「パネル」から始まります。どこにも出したくなければ、その列を「出さない」に変えてください（モバイルの詳細メニューの区分としてだけ使えます）。列の見出しの小さな選択で、その区分を一覧ぜんぶ同じ出し方にそろえられます。

どれを選べばいいか

出し方は 3 つあります。同じアクションでも、一覧ごとに変えられます。

出し方	場所	出るもの
ボタン	ツールバー	名前だけ（区分なしのアクションが直接並びます）
メニュー	ツールバー	名前だけ（区分ごとに 1 つ。名前は区分名）
パネル	表の上の折りたたみ	名前 ＋ 説明 2 行 ＋ 区分の色 ＋ ログへのリンク

• レコードを選んで処理するもの（一括更新・まとめて集計）は ボタンかメニューが向いています。ツールバーに出るので表を押し下げません。選ぶには行が見えている必要があるからです。
• 月ごとの集計や締めの処理は パネルが向いています。たまにしか押さないので「これは何をするボタンか」の説明が要りますし、レコードを選ばないので表が隠れても困りません。
• 詳細画面から 1 件ずつのものは、そもそも一覧に出さない（「一覧でも使う」を外す）で足ります。

レコードを選ぶ処理はボタン・メニューを先に考えて、それ以外で迷ったらパネルにしてください。説明が出るぶん、押す人が困りません。

なお、出す場所の設定は「押せる人」の設定ではありません。一覧から外しても、詳細画面のボタンやほかの一覧には出たままです。押せる人を絞るなら「実行を許す人」や実行条件を使います（④ 運用編）。

選択したレコードの一括処理

「選択したレコードのみ一括処理」をオンにすると、一覧にチェックボックスの列が出ます。レコードを選んでアクションを押すと、アクションに設定した選択の渡し方で実行します。既定は「1 件ずつ」で、このときは開始前に 1 回確認してから、選んだレコードを順に処理します。

• 進捗は「n / m 件」で表示し、中止はレコードの区切りで効きます

• 失敗したレコードがあったときに続行するか停止するかは、アクションごとに設定します

• 結果は「対象 / 成功 / 失敗 / 条件外 / 未処理」の内訳で表示します

• 1 回の上限は既定 300 件です（設定で変更できます）

• 時間と API の目安: 読み取り 1 回 + 書き込み 1 回の簡単な SQL を PC の Chrome で測ったとき、1 件あたり約 0.7 秒・API 4 回でした（300 件なら約 3 分 30 秒・約 1,200 回）。SQL の内容と kintone の応答時間で変わります

• 実行は利用者のブラウザーで行うため、タブを閉じると途中で止まります（処理済みの分は残ります）

• 大量・定型の処理は、条件を SQL の WHERE に書く「アプリ」アクションにするか、kSQL Flow を検討してください

選んだレコードをまとめて 1 回で処理する

アクションの「選択の渡し方」をまとめて 1 回にすると、1 件ずつではなく、選んだレコードの ID をまとめて 1 回だけ SQL に渡します。ID は @_selected に配列で入ります。

-- @ksql dialect: 1
DECLARE @cust = '';
DECLARE @_selected = [];     -- 選んだレコードの ID（配列）

UPDATE LAPP_取込 SET 取込日時 = @NOW()
 WHERE 顧客コード = @cust
  APPLY 明細 (
    REMOVE ALL ROWS;
    APPEND (受注番号, 担当者, 金額)
    SELECT $id, 担当者, 金額 FROM LAPP_受注
     WHERE $id IN @_selected ORDER BY $id
  );

選んだ複数レコードを 1 つのテーブルにまとめて入れるときは、この「まとめて 1 回」を使います。「1 件ずつ」ではテーブルの全置換が選んだ件数だけ繰り返されて、最後の 1 件しか残りません。

• レコードごとの値（@_record や、レコードの項目を使う計算式）は使えません。入力項目は使えます
• 選べる件数は、一括の最大件数と 200 の小さいほうまでです
• 「選択が 0 件なら何もしない」は IN @_selected 側で書いてください。実行条件で全部が外れると @_selected は空の配列になり、そのとき IN は 1 件にも当たりませんが、NOT IN は全件が対象になります

顧客ごとなど、グループに分けて処理する

「選択の渡し方」をグループごとにすると、選んだレコードを分ける式の値でまとめ、グループの数だけ同じ SQL を実行します。式の値は @_group に入ります。

-- @ksql dialect: 1
DECLARE @_group = '';        -- 分ける式の値（この実行のグループ。例: 顧客コード）
DECLARE @_selected = [];     -- そのグループで選ばれたレコードの ID

UPSERT INTO LAPP_取込 (顧客コード, 件数, 取込日時)
SELECT @_group AS 顧客コード, COUNT(*) AS 件数, @NOW() AS 取込日時
  FROM LAPP_受注 WHERE $id IN @_selected
ON DUPLICATE (顧客コード);

UPDATE LAPP_取込 SET 取込日時 = @NOW()
 WHERE 顧客コード = @_group
  APPLY 明細 (
    REMOVE ALL ROWS;
    APPEND (受注番号, 担当者, 金額)
    SELECT $id, 担当者, 金額 FROM LAPP_受注
     WHERE $id IN @_selected ORDER BY $id
  );

分ける式は「条件とメッセージ」で設定します（顧客コード と書けばそのまま、LEFT(顧客コード, 3) や YEAR(受注日) のようにまとめ方を作ることもできます）。

• 複数の顧客にまたがる選択をそれぞれの顧客のテーブルへ書き戻すときは、この「グループごと」を使います（テーブルへの書き戻しは 1 回の実行で 1 つのレコードにしか書けないため）

• グループは一度に 20 個まで、式の値が空のレコードは対象外になります

• 確認と書き込み上限はグループをまたいだ通算です。結果には「成功 / 失敗 / 対象外」が出ます

• グループごとの処理もトランザクションではありません。途中で失敗したり取りやめたりしても、先に終わったグループの書き込みは残ります（2 つ目以降の確認にもその注意が出ます）

モバイルでの見え方

モバイルでは、パネルは畳んだ状態で始まり、中は 1 列・ボタンは幅いっぱいになります。説明はボタンの横の i を押すと吹き出しで出ます。表のない画面（カレンダーなど）や 0 件の一覧では、一括のボタンを出しません。

パネルと区分の開閉は一覧ごとに覚えます（その人のブラウザーに保存します。PC も同じです）。［パネル・区分］の「開いて出す」「畳む」は、覚えていないときの初めの状態です。

詳しくは本記事の「モバイル」をご覧ください。

関連記事

• rex0220 kSQL アクションプラグイン
• ① 詳細画面編（ボタンとイベント）
• ② 一覧編（選択したレコードをまとめて処理する）（この記事）
• ③ 集計編（顧客別集計とテーブルへの書き戻し）
• ④ 運用編（ログアプリ・二重実行の防止・権限）
• ⑤ 事例編（10 万件を集計して Dashboard Pro で見る）
• ⑥ イベント編（保存・ステータス変更・削除で自動実行する）
• ⑦ オーサリング編（設定を AI に作ってもらう）
• ⑧ 請求データ編（全体再計算で整合性を保つ）
• ⑨ 締めの画面編（押し忘れに気づくダッシュボード）
• ⑩ 画面のどこに出すか（ボタン・メニュー・パネルの使い分け）
• ⑪ 日本語・英語・中国語で使う（共通の文と多言語）
• ⑫ オーサリング改善編（AI に使わせて見つけた穴）
• 事例集（やりたいことから探す）