kintone添付ファイル一括ダウンロードの設計方法｜標準制約と安全な取得手順

kintoneの添付ファイルは、1件ずつ扱ううちは大きな問題になりません。

案件レコードから見積書を開く。

請求レコードから請求書PDFを落とす。

作業報告から写真を確認する。

契約レコードから締結済みPDFを取得する。

この範囲なら、標準の添付ファイルフィールドでも運用できます。

しかし、次のような場面になると「一括ダウンロードしたい」という要望が出ます。

• 監査対応で、対象期間の契約書をまとめて提出したい
• 請求書PDFを月次でまとめて保管したい
• 現場写真を案件別フォルダに分けて納品したい
• 退職者の担当案件に紐づく資料を引き継ぎたい
• アプリ移行前に添付ファイルを退避したい
• 外部ストレージへ定期的にアーカイブしたい
• 顧客別、案件別、年月別にファイルをまとめたい

このとき、単に「全部落とせるボタン」を作るのは危険です。

全件を対象にすると、古いファイル、下書き、個人情報、社外共有してはいけない資料まで混ざります。

ファイル名が揃っていないと、ダウンロード後に何のファイルか分からなくなります。

フォルダ構成がないと、数千ファイルを人が仕分けることになります。

取得ログがないと、誰が、いつ、何を持ち出したか追えません。

APIで大量に処理すると、レコード取得やファイル取得の負荷も無視できません。

kintone添付ファイルの一括ダウンロードは、操作ボタンの追加ではなく、対象範囲、権限、命名、ログ、負荷を決める業務設計です。

この記事では、標準操作でできる範囲、一括ダウンロードが必要な業務、対象レコードと添付フィールドの絞り込み、プラグイン・API・外部出力の使い分け、ファイル名とフォルダ構成、権限・監査ログ、API負荷、よくある失敗を整理します。

kintone添付ファイルの基本設計はこちら
kintoneバックアップの設計方法はこちら

標準操作だけでは一括取得の設計が残る

kintoneヘルプでは、添付ファイルフィールドを配置すると、レコードにファイルを添付でき、レコード詳細画面では添付ファイルのファイル名とサイズが表示され、ファイル名をクリックするとダウンロードできると説明されています。

kintoneヘルプ：添付ファイル

これは、レコードに紐づくファイルを確認し、必要なファイルを個別に取得する運用には向いています。

一方で、次のような取得は、別途設計が必要です。

やりたいこと	設計が必要な理由
一覧条件に合うファイルをまとめて取得	対象レコードと添付フィールドを決める必要がある
顧客別、案件別にフォルダ分け	フォルダ名に使う項目を決める必要がある
ファイル名を自動で整える	命名規則と重複時の扱いが必要
ZIPでまとめて渡す	容量、件数、分割単位を決める必要がある
誰が取得したか残す	取得ログや承認履歴が必要
外部保管へ移す	kintoneに残す情報と外部側の権限を分ける必要がある

「一括ダウンロード機能がほしい」と言われたら、まず聞くべきなのは実装手段ではありません。

何のために、どの範囲を、どの形式で取得するのかです。

目的	取得単位の例
監査提出	対象期間、契約種別、締結済みだけ
請求保管	請求月、発行済み、請求書PDFだけ
写真納品	案件、作業日、顧客提出可の写真だけ
アプリ移行	移行対象アプリ、全添付フィールド、最終版だけ
退避保管	完了案件、保存期限到来前、外部保管対象だけ

一括ダウンロードの設計では、「全部」ではなく、目的ごとに取得条件を分けます。

一括ダウンロードが必要な業務を整理する

添付ファイルの一括取得は、業務ごとに要件が変わります。

たとえば、監査対応と現場写真の納品では、同じ「一括ダウンロード」でも設計が違います。

業務	取得対象	注意点
監査対応	契約書、請求書、証憑	取得者、取得日時、提出先を残す
月次保管	請求書PDF、納品書、検収書	請求月や取引先でフォルダ分けする
顧客提出	現場写真、報告書	社内用写真や下書きを除外する
引き継ぎ	担当案件の資料	顧客単位、案件単位でまとめる
移行	既存アプリの添付ファイル	移行先で参照できるメタデータを残す
外部保管	完了案件のファイル	kintone側に保管先URLを戻す

目的が曖昧なまま一括取得を作ると、すぐに要望が膨らみます。

「契約書だけでよい」と言っていたのに、覚書、本人確認書類、見積書もほしい。

「案件別でよい」と言っていたのに、顧客別、年月別、担当者別にも出したい。

「一度だけ」と言っていたのに、毎月実行したい。

このような変更に耐えるには、取得設定を業務ルールとして持つ方がよいです。

設定項目	例
取得目的	監査提出、請求保管、写真納品、移行
対象アプリ	契約、請求、作業報告、案件
対象一覧	締結済み契約、発行済み請求、完了作業
対象フィールド	契約書PDF、請求書PDF、顧客提出写真
除外条件	下書き、社内用、破棄済み、閲覧不可
出力形式	ZIP、フォルダ、外部ストレージ
ログ	実行者、日時、対象件数、ファイル数、容量

対象レコードと添付フィールドを絞り込む

一括ダウンロードの品質は、対象レコードの絞り込みでほぼ決まります。

よくない設計は、アプリ内の全レコード、全添付フィールドを無条件で取得することです。

これでは、不要ファイルも機密ファイルも混ざります。

まず、一覧条件を業務目的に合わせます。

目的	一覧条件の例
締結済み契約の提出	ステータス = 締結済み、締結日が対象期間内
請求書PDFの月次保管	請求月 = 対象月、発行状態 = 発行済み
顧客提出写真の出力	作業日が対象期間内、写真区分 = 顧客提出可
完了案件の退避	案件状態 = 完了、完了日が対象期間内
担当者引き継ぎ	担当者 = 対象者、案件状態が進行中

次に、添付フィールドを分けます。

フィールド	取得可否の考え方
契約書PDF	監査や法務提出で取得対象にする
請求書PDF	月次保管や外部会計連携で取得対象にする
社内メモ添付	原則として一括取得対象から外す
本人確認書類	専用手順と承認がある場合だけ取得する
顧客提出写真	顧客共有用フラグがあるものだけ取得する
下書き添付	取得対象から外す

添付ファイルの設計時点で、フィールドを分けておくと一括取得が安定します。

1つの「添付ファイル」フィールドに、見積書、契約書、本人確認書類、社内メモ、写真を全部入れていると、あとから安全に切り分けるのが難しくなります。

kintone添付ファイルの基本設計はこちら

一括ダウンロードを前提にするなら、添付ファイルフィールドは「何でも入れる箱」ではなく、取得してよい単位で分けます。

プラグイン・APIカスタマイズ・外部出力の使い分け

一括ダウンロードの実装手段は、1つではありません。

業務頻度、対象件数、権限、ログ要件で選びます。

手段	向いているケース	注意点
手動ダウンロード	件数が少なく、頻度も低い	人の作業に依存する
プラグイン	一覧画面から現場担当が取得したい	対象条件、命名、ログ要件を確認する
JavaScriptカスタマイズ	特定画面にボタンを置きたい	ブラウザ処理の容量や待ち時間に注意する
外部バッチ	件数が多い、定期実行したい	API制限、保管先、実行ログを設計する
外部ストレージ連携	長期保管や外部共有が多い	kintone側と外部側の権限を合わせる

年に数回、対象も限定的なら、プラグインや画面カスタマイズで足ります。

毎月、大量のファイルを、フォルダ分けして、外部保管まで行うなら、外部バッチの方が安定します。

監査や個人情報を扱うなら、取得前の承認と取得後のログが必要です。

ここで大事なのは、手段を先に決めないことです。

要件	選び方
現場が一覧からすぐ取得したい	プラグインまたは画面ボタン
顧客別フォルダに分けたい	API処理または外部バッチ
取得ログを必ず残したい	ログアプリと連動する実装
1回の容量が大きい	分割出力または外部保管
定期実行したい	スケジューラ付き外部処理
取得前承認が必要	申請アプリと連動

APIで取得するときの基本手順

APIで添付ファイルを一括ダウンロードする場合、基本の流れは次の通りです。

1. 対象アプリと一覧条件を決める
2. 複数レコード取得APIやカーソルAPIで対象レコードを取得する
3. 添付ファイルフィールドからfileKey、ファイル名、サイズを読む
4. 取得対象から除外するファイルを判定する
5. ファイルダウンロードAPIでfileKeyごとに取得する
6. ファイル名を整え、フォルダへ配置する
7. ZIP化または外部ストレージへ保存する
8. 取得ログを残す

cybozu developer networkのファイルダウンロードAPIでは、fileKeyを指定してファイルをダウンロードし、レスポンスボディにファイル内容が入ると説明されています。

また、ファイルキーには、アップロードAPIのレスポンスで取得する一時保管用のキーと、レコード取得APIなどで取得する添付済みファイルのキーの2種類があり、ダウンロードAPIで指定するのは後者だと説明されています。

cybozu developer network：ファイルをダウンロードする

複数レコード取得APIでは、一度に取得できるレコードは500件までで、offsetの上限は10,000件です。

cybozu developer network：複数のレコードを取得する

対象が多い場合は、カーソルAPIも検討します。

カーソル作成APIでは、レコードを一括で取得するためのカーソルを作成し、1回のGETリクエストでカーソルから取得するレコード数を1から500まで指定できると説明されています。

cybozu developer network：カーソルを作成する

カーソルからレコードを取得するAPIでは、nextがtrueなら同じカーソルIDで続きのレコードを取得でき、falseならすべて取得済みと説明されています。

cybozu developer network：カーソルからレコードを取得する

処理	設計上の注意
レコード取得	必要なフィールドだけ取得する
fileKey取得	添付済みファイルのfileKeyを使う
ファイル取得	1ファイルずつ処理し、失敗を記録する
並列処理	同時実行数を制御する
大量取得	500件単位、カーソル、分割条件を使う
出力	ファイル名、フォルダ、ZIP分割を決める

APIで一括ダウンロードする場合は、レコード一覧を取ってから添付済みfileKeyを集め、ファイル単位で取得する流れとして設計します。

ファイル名とフォルダ構成の設計

一括ダウンロード後に使える状態にするには、ファイル名とフォルダ構成が重要です。

元のファイル名をそのまま出すだけでは、次のような問題が起きます。

• 見積.pdfが何十個も並ぶ
• 同名ファイルが上書きされる
• 顧客名や案件名が分からない
• どのレコードから取得したか追えない
• ファイル名に使えない文字が含まれる
• 長すぎるファイル名で扱いづらい

ファイル名には、業務上のキーを入れます。

ファイル種別	ファイル名例
契約書	契約_契約番号_顧客名_締結日_ファイル名.pdf
請求書	請求_請求月_請求番号_顧客名_ファイル名.pdf
現場写真	写真_案件番号_作業日_写真区分_連番.jpg
見積書	見積_案件番号_見積番号_版_ファイル名.pdf
証憑	証憑_申請番号_支払日_支払先_ファイル名.pdf

同名ファイルがあり得る場合は、レコード番号や添付フィールドコードを入れます。

重複対策	例
レコード番号を入れる	R1234_契約書.pdf
フィールドコードを入れる	contract_file_契約書.pdf
連番を入れる	写真_001.jpg
fileKeyの一部を入れる	契約書_7E339F.pdf

フォルダ構成も、目的ごとに変えます。

目的	フォルダ構成例
監査提出	監査提出/2026年度/契約種別/顧客名/
月次請求保管	請求書/2026-06/顧客名/
写真納品	案件番号_案件名/作業日/写真区分/
移行退避	アプリ名/レコード番号/フィールドコード/
担当引き継ぎ	担当者名/顧客名/案件名/

ルールを複雑にしすぎると、運用が続きません。

まずは、次の4点が分かる命名にします。

入れる情報	理由
業務種別	契約、請求、写真などを分ける
レコード識別子	kintone上の元データへ戻れる
取引先や案件	人が見て判断できる
日付や版	どの時点のファイルか分かる

権限・監査ログ・持ち出しリスク

一括ダウンロードで最も危ないのは、権限外の情報をまとめて持ち出すことです。

cybozu developer networkのファイルダウンロードAPIでは、必要なアクセス権として、アプリのレコード閲覧権限、ファイルが添付されたレコードの閲覧権限、ファイルが添付されたフィールドの閲覧権限が挙げられています。

cybozu developer network：ファイルをダウンロードする

つまり、一括ダウンロードの権限設計は、添付ファイル単体ではなく、アプリ、レコード、フィールドの権限設計に依存します。

リスク	対策
機密フィールドを取得してしまう	対象フィールドを明示的に限定する
本人確認書類が混ざる	専用アプリや専用手順に分ける
社外共有不可ファイルを含める	共有可否フラグを設ける
退職者や外部委託者が取得する	実行権限を限定する
取得後の保管場所が不明	出力先を会社管理領域に固定する
誰が取得したか分からない	ログアプリに記録する

取得ログには、最低限これを残します。

ログ項目	用途
実行ID	一括処理を追跡する
実行者	誰が取得したか確認する
実行日時	いつ取得したか確認する
目的	監査、保管、移行などの理由を残す
対象条件	どの一覧条件で取得したか残す
対象アプリ	どのアプリから取得したか残す
レコード件数	対象範囲を把握する
ファイル件数	実際に取得した数を確認する
合計容量	ZIP分割や外部保管判断に使う
失敗件数	再実行対象を分ける
出力先	どこに保存したか残す

機密性が高いファイルでは、実行前承認も考えます。

取得前に確認すること	例
取得目的	監査提出、顧客提出、移行
承認者	管理者、法務、経理責任者
取得範囲	対象期間、対象顧客、対象ファイル種別
出力先	社内共有ストレージ、限定フォルダ
保存期限	取得後いつ削除するか

kintoneセキュリティの設計方法はこちら

API負荷と大量ファイル処理

添付ファイルの一括ダウンロードは、レコード取得より重くなりがちです。

理由は、レコード一覧を取るだけでなく、ファイル本体を1つずつ取得するからです。

たとえば、次のようなケースを考えます。

項目	例
対象レコード	2,000件
1レコードあたり添付	3ファイル
合計ファイル数	6,000ファイル
平均サイズ	2MB
合計容量	約12GB

この規模では、ブラウザ上で一気にZIP化する設計は避けた方がよいです。

外部バッチで、対象を分割し、途中再開できるようにします。

cybozu developer networkのREST API共通仕様では、レスポンスヘッダーとして、同時接続数の上限値を示すX-ConcurrencyLimit-Limitと、現在の同時接続数を示すX-ConcurrencyLimit-Runningが説明されています。

cybozu developer network：kintone REST APIの共通仕様

一括ダウンロードでは、次の制御を入れます。

制御	内容
件数分割	対象期間、顧客、案件、レコード番号で分ける
並列数制御	同時ダウンロード数を決める
リトライ	一時失敗だけ待機して再実行する
失敗箱	何度も失敗するファイルを別扱いにする
再開位置	最後に成功したレコードやファイルを残す
ZIP分割	容量や件数で分ける
実行時間帯	利用者が少ない時間帯に回す

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

大量の添付ファイルを扱う場合は、ブラウザで一気に処理せず、分割、再開、失敗ログ、出力先を持つバッチとして設計します。

外部保管へつなぐ場合

一括ダウンロードの目的が、単なる手元保存ではなく外部保管なら、ダウンロードして終わりにしない方がよいです。

外部ストレージへ保存し、kintoneには保管先URLや出力ログを戻す設計があります。

kintone側に残すもの	外部保管側に置くもの
ファイル種別	ファイル本体
対象レコード	フォルダ構成
保管先URL	版履歴
取得日時	大容量ファイル
実行者	共有権限
保存期限	アーカイブ

外部保管に逃がす場合も、注意点があります。

注意点	対策
個人フォルダに保存される	会社管理の共有領域に固定する
URLが切れる	定期確認やリンク再生成の手順を作る
外部権限が広すぎる	kintone権限と外部権限を合わせる
ファイル名が変わる	kintone側に出力時のファイル名を残す
二重管理になる	kintone側の正本/写しの扱いを決める

外部保管に移すなら、kintoneの添付ファイルを削除するか、残すかも決めます。

方針	向いているケース
kintoneにも残す	現役業務で頻繁に参照する
外部に移してURLだけ残す	完了案件や長期保管が中心
一定期間だけ二重保管	移行直後や監査対応中
機密ファイルは外部専用	権限管理を厳しくしたい

よくある失敗

kintone添付ファイルの一括ダウンロードでよくある失敗を整理します。

失敗	起きること	対策
全件取得ボタンを作る	不要ファイルや機密ファイルまで混ざる	目的別の一覧条件を作る
1つの添付フィールドに全部入れる	取得してよいファイルだけ選べない	種別ごとにフィールドを分ける
ファイル名をそのまま出す	同名ファイルが上書きされる	レコード番号や業務キーを入れる
フォルダ構成がない	ダウンロード後に仕分けが必要になる	顧客、案件、年月で分ける
ログがない	誰が何を取得したか分からない	実行ログアプリを作る
ブラウザで大容量ZIPを作る	固まる、失敗時に再開できない	外部バッチにする
fileKeyを混同する	ダウンロードできない	添付済みfileKeyを使う
権限を確認しない	持ち出し事故につながる	アプリ、レコード、フィールド権限を見る
外部保管先が個人管理	退職や権限変更で見失う	会社管理領域に保存する

一括ダウンロードで守るべきなのは、取得できることではなく、必要なファイルだけを、追跡できる形で、安全に取り出すことです。

実装前チェックリスト

実装前に、次を決めます。

チェック	内容
取得目的	監査、月次保管、顧客提出、移行、退避のどれか
対象アプリ	契約、請求、作業報告、案件など
対象一覧	どの条件でレコードを絞るか
対象フィールド	どの添付ファイルフィールドを取得するか
除外条件	下書き、社内用、破棄済み、機密を除外するか
権限	誰が実行できるか、誰の権限で取得するか
ファイル名	レコード番号、顧客名、日付、版を入れるか
フォルダ構成	顧客別、案件別、年月別など
出力形式	ZIP、フォルダ、外部ストレージ
容量	分割が必要か
ログ	実行者、日時、件数、出力先、失敗を残すか
再実行	失敗したファイルだけ再実行できるか
保存期限	取得後のファイルをいつまで残すか

設計書には、ボタン名やプラグイン名だけでなく、次を書きます。

設計書に書くこと	理由
対象条件	取得範囲を固定する
取得対象フィールド	機密ファイル混入を防ぐ
命名規則	ダウンロード後に迷わない
フォルダ構成	提出や保管に使える形にする
実行権限	持ち出し範囲を限定する
ログ項目	監査や再実行に使う
分割条件	大量ファイルでも止まりにくくする
外部保管ルール	kintone外に出した後を管理する

Bitlightに相談できること

kintoneの添付ファイル一括ダウンロードは、プラグインやAPIで実現できます。

ただし、業務で本当に必要なのは、落とせる機能そのものではありません。

どのファイルを、どの条件で、誰が、どこへ、どの名前で、どのログを残して取得するかです。

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

• 一括ダウンロード対象の一覧条件と添付フィールドの整理
• 契約書、請求書、写真、証憑ごとの取得ルール設計
• ファイル名、フォルダ構成、ZIP分割の設計
• 実行権限、承認、取得ログの設計
• APIによるfileKey取得、ファイルダウンロード、再実行処理の実装
• 大量ファイル処理の分割、同時実行制御、失敗ログ設計
• 外部ストレージ保管とkintone側の保管先URL管理

添付ファイルは、増えてから整理すると手戻りが大きい領域です。

一括ダウンロードを作るタイミングで、ファイル種別、添付先、権限、保管先まで一度整理しておくと、監査、移行、顧客提出、保管のたびに迷わなくなります。