kintone一括更新の設計方法｜CSV・API・プラグインで誤更新を防ぐ構成

kintoneの一括更新は、便利ですが危険な作業です。

取引先名をまとめて修正する。

担当者を一括で付け替える。

商品マスタの単価を更新する。

ステータスをまとめて変更する。

外部システムから届いたCSVで受注データを更新する。

ルックアップで取得した値を最新のマスタ値へ合わせる。

完了案件をアーカイブ対象にする。

このような作業は、1件ずつ直すより早く終わります。

しかし、一括更新は影響範囲が広いです。

対象を間違えると、本来変えてはいけないレコードまで変わります。

更新キーを間違えると、別のレコードが上書きされたり、新規レコードが増えたりします。

承認済み、請求済み、締結済みのデータを更新すると、過去の証跡が変わります。

CSVの列ずれや文字コードの問題で、値が空欄になったり、先頭ゼロが消えたりします。

APIで大量更新すると、制限や途中失敗への対応が必要になります。

kintone一括更新は、更新手段の選択ではなく、対象範囲、更新キー、除外条件、バックアップ、検証、戻し方を決める業務操作です。

この記事では、kintone一括更新を安全に行うために、CSV、API、cli-kintone、プラグインの違い、更新キーと対象レコードの決め方、更新前バックアップ、テスト更新、承認済み・請求済みデータの除外、失敗レコードと再実行、定期更新の判断を整理します。

kintoneバックアップの設計方法はこちら
kintone API制限の回避設計はこちら

一括更新は便利だが誤更新リスクが高い

一括更新で最初に決めることは、どの機能を使うかではありません。

何を更新してよいか、何を更新してはいけないかです。

更新したいこと	更新してよいことが多い	注意が必要なこと
担当者変更	未完了案件の担当者	完了済み案件の履歴
顧客情報修正	現在の住所や連絡先	過去見積に残す当時住所
商品単価変更	今後の見積用マスタ	提出済み見積、請求済み明細
ステータス変更	対象条件が明確な未処理レコード	承認済み、締結済み、請求済み
外部データ反映	未確定データの補正	監査や証跡に使う確定データ

一括更新で危険なのは、「いまの値にそろえる」ことが常に正しいとは限らない点です。

過去の見積は、当時の単価や住所を残す必要があります。

請求済みデータは、後から金額や取引先名を変えると会計証跡が崩れます。

承認済み申請は、承認時点の内容を残すべきです。

一括更新の前に、対象を分けます。

分類	扱い
更新対象	最新値へ合わせる
除外対象	過去時点の値として固定する
確認対象	人が確認してから更新する
テスト対象	少数件で先に試す
戻し対象	更新前CSVから戻せるようにする

一括更新では、最新化するデータと、当時値として固定するデータを分けます。全件更新を前提にすると、証跡として残すべき値まで変わります。

CSV・API・cli-kintone・プラグインの違い

kintoneの一括更新には、複数の手段があります。

手段	向いているケース	注意点
画面からCSV読み込み	年数回のメンテナンス、作業者が確認しながら実行	列ずれ、更新キー、バックアップ漏れ
cli-kintone	定型CSVをコマンドで取り込みたい	実行環境、認証、ログ保管が必要
REST API	外部システムやバッチから更新したい	権限、制限、再実行、失敗ログが必要
プラグイン	一覧画面から現場担当が定型更新したい	更新対象と権限を設計する
個別カスタマイズ	特定業務のボタン操作にしたい	画面操作だけで済ませずログを残す

kintoneヘルプでは、ファイルを読み込んでレコードを登録または上書きするときの記載形式が説明されています。

標準CSVは、単発のメンテナンスや、作業前後のファイルを残したい場面に向きます。

kintoneヘルプ：レコード登録・上書き用のファイルの記載形式

cli-kintoneのrecord importでは、CSVファイルを指定アプリへインポートできます。

--update-keyを指定すると、更新キーに一致するレコードを更新し、存在しない場合は新規登録する動きになります。

cli-kintone：record import

REST APIで更新する場合は、複数のレコードを更新するAPIを使います。

cybozu developer networkでは、idで更新する方法と、updateKeyで更新する方法が説明されています。

upsertをtrueにすると、指定したレコードが存在する場合は更新し、存在しない場合は新規登録されます。

cybozu developer network：複数のレコードを更新する

手段ごとの判断は、更新頻度と業務リスクで決めます。

判断軸	CSV向き	API/cli/プラグイン向き
頻度	年数回、単発	毎日、毎週、毎月
対象件数	少量から中量	大量、定期処理
作業者	管理者が手動で確認	定型処理として実行
ログ	CSVファイルと作業記録で残す	実行ログアプリや外部ログで残す
失敗対応	人が確認してやり直す	失敗レコードだけ再実行する
権限	管理者作業	実行者、APIトークン、対象フィールドを制御

更新キーと対象レコードの決め方

一括更新で最も重要なのは、更新キーです。

更新キーが曖昧だと、どのレコードを更新するのかが安定しません。

更新キー候補	向いているケース	注意点
レコード番号	kintone内で完結する更新	外部CSVには通常入っていない
顧客番号	顧客マスタ更新	重複禁止にする
案件番号	案件情報の更新	採番ルールを固定する
請求番号	請求データ更新	請求済み除外を設ける
外部システムID	外部連携	連携元のID変更に注意する

REST APIの複数レコード更新では、updateKeyに指定できるフィールドは、重複禁止を設定した文字列1行または数値フィールドと説明されています。

cybozu developer network：複数のレコードを更新する

この制約は、業務設計でも重要です。

更新キーは、人が見て分かりやすいだけでは足りません。

重複しないこと。

途中で変わらないこと。

外部データと照合できること。

空欄にならないこと。

更新前に一覧で確認できること。

対象レコードも、更新直前に一覧で固定します。

一覧	条件例
更新対象一覧	ステータスが未確定、対象フラグがON
除外一覧	承認済み、請求済み、締結済み、完了済み
確認待ち一覧	キー重複、キー空欄、金額差が大きい
更新後確認一覧	更新日時が本日、更新者が作業者
差戻し一覧	更新エラー、検証NG、手動確認が必要

一括更新の前に、更新キーの重複、空欄、変更不可項目、除外条件を一覧で確認します。ここを飛ばすと、手順が正しくても結果が崩れます。

更新前バックアップとテスト更新

一括更新の前には、更新対象だけを書き出します。

全アプリのバックアップではなく、今回変える範囲のバックアップを取ります。

保存するもの	理由
更新前CSV	元の値に戻すため
更新対象一覧の条件	どの範囲を更新したか説明するため
更新予定CSV	実際に読み込む内容を残すため
差分確認表	変更前後を確認するため
作業者と実行日時	監査や問い合わせ対応に使うため

本番更新前には、少数レコードでテストします。

テスト観点	確認すること
更新キー	想定した1件だけ更新されるか
文字コード	文字化けしないか
先頭ゼロ	顧客番号や郵便番号が壊れないか
日付	形式が意図通りか
数値	カンマ、通貨記号、小数が崩れないか
空欄	空欄で上書きしてよい項目か
ルックアップ	コピー項目が想定通りか
テーブル	行の追加、更新、削除が想定通りか

更新前バックアップは、作業者を守るためにも必要です。

一括更新は、失敗すると影響が大きい作業です。

戻せる状態を作らずに実行すると、更新後に人力で修復するしかなくなります。

kintoneバックアップの設計方法はこちら

承認済み・請求済みデータの除外

一括更新では、更新してはいけないレコードを先に決めます。

代表的なのは、承認済み、請求済み、締結済み、会計連携済み、完了済みのデータです。

状態	原則
下書き	更新対象にしやすい
確認中	確認者に通知してから更新する
承認済み	原則除外。必要なら再承認
請求済み	原則除外。修正伝票や再発行で扱う
締結済み	原則除外。変更契約や覚書で扱う
会計連携済み	連携先との整合を確認してから更新
完了済み	原則除外。履歴として固定する

よくある失敗は、マスタ修正を過去レコードへ無条件に反映することです。

取引先住所を変えたら、過去請求書の住所まで変わった。

商品名を変えたら、提出済み見積の品名まで変わった。

担当者を変えたら、過去の承認履歴の意味が変わった。

このような更新は、業務上の証跡を壊します。

一括更新の条件には、状態を必ず入れます。

更新内容	除外条件例
顧客情報更新	請求済み、契約終了済みを除外
単価更新	提出済み見積、請求済み明細を除外
担当者更新	完了案件、承認済み申請を除外
ステータス更新	手動確認中、差戻し中を除外
外部ID補正	連携済み、照合済みを除外

一括更新の安全性は、更新対象よりも除外対象の設計で決まります。承認済み、請求済み、締結済みは先に守ります。

API更新で見る権限・リビジョン・制限

APIで一括更新する場合は、CSVよりも細かい制御ができます。

ただし、設計する項目も増えます。

cybozu developer networkの複数レコード更新APIでは、必要なアクセス権として、アプリのレコード編集権限、更新するレコードの編集権限、更新するフィールドの編集権限が挙げられています。

また、UPSERTモードではアプリのレコード追加権限も必要です。

cybozu developer network：複数のレコードを更新する

API更新では、リビジョン番号も重要です。

同じAPIでは、期待しているリビジョン番号を指定でき、実際のリビジョン番号と一致しない場合はエラーになり、レコードは更新されないと説明されています。

これは、更新対象を取得した後に、別の人や処理がレコードを変えていないかを確認する仕組みとして使えます。

API設計	見ること
APIトークン	どのアプリ、どの操作、どのフィールドを許可するか
updateKey	重複禁止のキーになっているか
revision	取得後に別更新が入っていないか
upsert	新規登録を許すか、更新だけにするか
権限	実行者やAPIトークンが過剰権限でないか
処理単位	何件ずつ更新するか
ログ	成功、失敗、再実行対象を残すか

テーブルや添付ファイルを更新する場合は、さらに注意が必要です。

複数レコード更新APIでは、テーブルの一部を更新したい場合でも、既存のすべての行をリクエストに含める必要があり、指定しない行は削除されると説明されています。

添付ファイルフィールドでは、新しくファイルを追加する場合、添付済みファイルのfileKeyもフィールド値に指定する必要があると説明されています。

cybozu developer network：複数のレコードを更新する

つまり、APIで一括更新できるからといって、テーブルや添付ファイルを軽く扱ってはいけません。

失敗レコードと再実行の管理

一括更新は、失敗する前提で設計します。

エラーが出たら最初から全件やり直す、という運用は危険です。

同じレコードを二重更新する可能性があります。

すでに成功したレコードまで巻き戻すことがあります。

失敗原因が分からないまま再実行して、同じエラーを繰り返します。

必要なのは、失敗レコードを分けることです。

ログ項目	用途
実行ID	一括更新の単位を追跡する
対象一覧	どの条件で抽出したか残す
更新キー	どのレコードを更新したか確認する
更新前値	戻すときに使う
更新後値	更新結果を確認する
成功/失敗	再実行対象を分ける
エラー内容	キー重複、権限、入力形式を切り分ける
実行者	誰が実行したか確認する
実行日時	いつ更新したか確認する

失敗レコードは、次のように扱います。

失敗理由	対応
更新キーなし	元データを修正して再取込
キー重複	マスタ側の重複を解消
権限不足	実行権限や対象フィールドを見直す
入力形式エラー	CSV形式や日付、数値を修正
リビジョン不一致	最新レコードを再取得して判断
API制限	分割、待機、再実行に回す

複数アプリのレコード操作を一括処理するBulk Request APIでは、最大20件のリクエストを指定でき、いずれかのAPIで処理が失敗すると失敗したAPIに対応する要素にエラー結果が入ると説明されています。

cybozu developer network：複数アプリのレコード操作を一括処理する

Bulk Requestは便利ですが、失敗時のログ設計が必要です。

APIが返したエラーを、実行ログや再実行対象へ変換しないと、業務担当者はどこを直せばよいか分かりません。

定期更新を自動化する判断

一括更新が毎月、毎週、毎日発生するなら、手動CSV運用を続けるより、定型化を考えます。

ただし、自動化すれば安全になるわけではありません。

むしろ、誤った条件のまま自動実行されると、気づかないうちにデータが壊れます。

定期更新では、次を決めます。

設計項目	内容
実行タイミング	いつ、どの頻度で実行するか
入力データ	どこからCSVやAPIデータを受け取るか
更新キー	外部ID、顧客番号、案件番号など
差分条件	全件ではなく変更分だけにできるか
除外条件	承認済み、請求済み、締結済みを守るか
実行前検証	件数、金額差、空欄、重複を確認するか
実行後検証	更新件数、失敗件数、差分を確認するか
通知	成功時、失敗時、確認待ちを誰に出すか
停止条件	異常件数やエラー率で止めるか

定期更新では、全件更新を避けます。

更新日時、外部側の差分フラグ、状態、対象期間などで絞り込みます。

大量更新を行う場合は、API制限や同時実行数も見ます。

kintone API制限の回避設計はこちら

通知も設計します。

1件ずつ通知すると、作業者に大量通知が飛びます。

一括更新では、完了レポート、失敗一覧、確認待ち一覧を通知する方が実務的です。

よくある失敗

kintone一括更新でよくある失敗を整理します。

失敗	起きること	対策
全件更新する	過去データや確定データまで変わる	対象一覧と除外一覧を作る
更新キーが曖昧	別レコードを更新する、新規が増える	重複禁止キーを設計する
更新前CSVを残さない	戻せない	更新対象だけバックアップする
テスト更新しない	本番で列ずれや形式エラーに気づく	少数件で先に試す
空欄上書きを見落とす	値が消える	空欄の扱いを項目ごとに決める
承認済みを更新する	証跡が崩れる	承認済み、請求済み、締結済みを除外する
テーブルを一部更新するつもりで送る	指定しない行が消える	全行取得してから更新する
API失敗をログに残さない	再実行できない	実行ログと失敗箱を作る
通知を1件ずつ送る	大量通知になる	完了レポートにまとめる

一括更新は、CSVを読み込めたら完了ではありません。更新後の検証一覧まで作って、業務上正しい値になったことを確認して完了です。

実装前チェックリスト

一括更新を実行する前に、次を確認します。

チェック	内容
更新目的	何を直す作業か説明できるか
更新対象	対象一覧で件数を確認したか
除外対象	承認済み、請求済み、締結済みを除外したか
更新キー	重複、空欄、変更予定がないか
更新項目	本当に変える項目だけに絞ったか
空欄扱い	空欄で上書きする項目を確認したか
更新前バックアップ	対象レコードの更新前CSVを保存したか
テスト更新	少数件で結果を確認したか
権限	実行者やAPIトークンの権限が適切か
ログ	成功、失敗、再実行対象を残すか
戻し方	失敗時にどのCSVやAPIで戻すか
通知	完了、失敗、確認待ちを誰に知らせるか

設計書には、次を書きます。

設計書に書くこと	理由
更新目的	作業の正当性を残す
対象条件	更新範囲を固定する
除外条件	確定データを守る
更新キー	レコード照合を安定させる
更新項目	不要な項目更新を防ぐ
実行手段	CSV、API、cli、プラグインを明確にする
バックアップ	戻せる状態にする
検証方法	更新後の正しさを確認する
ログ項目	監査と再実行に使う

Bitlightに相談できること

kintone一括更新は、CSVでもAPIでも実行できます。

しかし、業務で重要なのは、更新できることではありません。

どのレコードを、どのキーで、どの項目だけ、どの状態なら更新してよいかを決めることです。

Bitlightでは、既存のkintoneアプリと運用を見ながら、次のような設計と実装を支援できます。

• 一括更新対象の一覧条件と除外条件の整理
• 顧客番号、案件番号、外部IDなどの更新キー設計
• 更新前バックアップ、テスト更新、更新後検証の手順化
• 承認済み、請求済み、締結済みデータの保護設計
• CSV、cli-kintone、REST API、プラグインの使い分け
• API更新時の権限、リビジョン、失敗ログ、再実行処理の設計
• 定期更新バッチ、完了レポート、確認待ち一覧の実装

一括更新は、作業時間を短くするためだけの機能ではありません。

正しく設計すれば、マスタ変更、外部データ反映、担当変更、アーカイブ作業を、毎回迷わず安全に実行できる運用になります。