kintone CSV出力の設計方法｜抽出条件・文字化け・外部連携で崩れない構成

kintoneのCSV出力は、よく使われる機能です。

顧客一覧をExcelで加工する。

月末時点の案件をバックアップする。

請求対象を会計ソフトへ渡す。

BIツールへ読み込む。

外部システムへ定期的に連携する。

監査や取引先へ提出する。

移行前後の差分を確認する。

こうした場面で、kintoneからCSVを書き出します。

ただし、CSV出力は「ダウンロードできれば終わり」ではありません。

どの一覧条件で出したのか分からない。

出力項目の順番が毎回違う。

Excelで開いたら文字化けする。

顧客番号や郵便番号の先頭ゼロが消える。

ユーザー選択がログイン名なのか表示名なのか混ざる。

日付形式が受け取り先の想定と違う。

添付ファイルや変更履歴も出ていると思っていた。

コメントCSVが別ファイルになっており、突合できない。

再ダウンロードしたファイルと今回出力したファイルの違いが分からない。

CSVを外部へ渡した後に、元レコードが更新されて数値がずれる。

このような問題は、操作手順の不足ではなく、CSV出力を業務の出口として設計していないことから起きます。

kintone CSV出力で最初に決めるべきなのは、「どのボタンを押すか」ではなく、「誰に、何の目的で、どの条件・項目・形式のデータを渡すか」です。

この記事では、kintone CSV出力を、外部提出、バックアップ、Excel加工、BI連携、外部システム連携に使う前提で、一覧条件、出力項目、項目順、文字コード、先頭ゼロ、日付、コメント、添付ファイル、出力権限、出力履歴、定期出力まで含めて整理します。

kintone CSVインポートの設計方法はこちら
kintoneバックアップの設計方法はこちら
kintone一括更新の設計方法はこちら

CSV出力は外部へ渡すデータ仕様

kintoneの画面で見るデータと、CSVで外部へ渡すデータは同じではありません。

画面では、人が見やすい名前、色、一覧、グラフ、関連レコード、添付ファイル、コメントが使えます。

CSVでは、列、値、文字コード、区切り文字、ファイル名、出力日時で管理します。

この違いを理解せずに出力すると、受け取り側で崩れます。

用途	CSVに求められること	注意点
Excel加工	人が開いて集計しやすい	表示名、文字コード、先頭ゼロ
外部提出	条件と時点を説明できる	出力対象、出力日時、提出版
バックアップ	戻しや比較に使える	更新キー、全項目、保存先
会計連携	取り込み形式に合う	コード、税区分、日付形式
BI連携	毎回同じ列構造になる	項目順、型、NULL扱い
システム連携	自動処理しやすい	フィールドコード、差分、ログ

CSV出力は、kintoneの外へデータを渡す行為です。

そのため、出力前に次を決めます。

観点	決めること
目的	提出、加工、保存、連携、復元のどれか
対象	どのアプリ、どの一覧条件、どの時点か
項目	どのフィールドを、どの順番で出すか
形式	文字コード、区切り文字、ヘッダー、表示名
権限	誰が出力でき、誰に渡してよいか
保存	どこに、何日分、どの名前で残すか
再利用	再ダウンロード、再出力、差分出力の扱い

kintoneヘルプでは、ファイルに書き出す流れとして、書き出すレコードを絞り込み、ファイルに書き出し、出力されたファイルをダウンロードする流れが説明されています。

kintoneヘルプ：ファイルにデータを書き出す

この流れを業務に合わせて固定すると、毎回の出力が説明できる作業になります。

出力目的を決める

CSV出力の設計は、目的で変わります。

同じ顧客アプリからCSVを出す場合でも、バックアップ用と外部提出用では、出す項目も保存ルールも違います。

目的	出力する項目	除外しやすい項目
社内Excel加工	担当者、状態、金額、期限、分類	個人情報、社外秘メモ
取引先提出	契約番号、納品日、請求対象、合計	社内メモ、利益率、担当者内部メモ
バックアップ	更新キー、主要項目、復元に必要な項目	不要な計算結果だけの項目
一括更新前退避	更新キー、更新対象項目、確認項目	今回戻さない項目
会計連携	取引先コード、税区分、金額、日付	kintone内だけの進捗項目
BI連携	集計軸、数値、日付、カテゴリ	長文備考、添付ファイル

出力目的が曖昧だと、つい「全部出す」になります。

全部出すと、受け取り側で不要な列が増え、個人情報や社内メモまで外へ出る可能性があります。

逆に、必要な更新キーや時点情報を出していないと、後から突合できません。

CSV出力では、目的ごとに出力仕様を作ります。

出力仕様	内容
出力名	月次請求連携、案件バックアップ、顧客提出用など
対象アプリ	アプリ名、アプリID
対象一覧	保存済み一覧名、絞り込み条件
出力項目	フィールド名、フィールドコード、順番
文字コード	UTF-8、Shift_JISなど
区切り文字	カンマ、タブなど
表示名	ユーザー、組織、グループを表示名にするか
保存先	Drive、Box、社内フォルダ、kintone添付など
保存期間	何世代、何か月、何年残すか
再出力	同じ条件で再度出す場合の扱い

CSV出力は「全部出す」ほど安全になるわけではありません。提出先や用途に必要な列だけを、説明できる条件で出すことが重要です。

一覧条件と出力項目を固定する

kintoneヘルプでは、レコード一覧画面に表示されているレコードをファイルに書き出せると説明されています。

また、頻繁に書き出す場合は、書き出すフィールドや絞り込み条件を指定した一覧を保存しておくと、同じ条件で書き出せると案内されています。

kintoneヘルプ：ファイルにデータを書き出す

この「一覧条件を保存する」ことが、CSV出力設計では重要です。

手作業で毎回絞り込むと、条件が揺れます。

条件	揺れやすい例	固定する方法
日付範囲	今月、前月、締め日が人によって違う	月次出力用一覧を作る
ステータス	完了だけ、承認済みだけ、請求対象だけ	出力用の状態を定義する
担当部署	部署名変更、兼務、退職者	組織コードや部門マスタで管理
除外条件	テストデータ、取消、重複	除外フラグや状態を持つ
並び順	顧客順、日付順、番号順	出力仕様に明記する

出力項目も固定します。

kintoneの出力画面では、ファイルに書き出す項目を指定し、並び替えることができます。

kintoneヘルプ：ファイルにデータを書き出す

外部システムやBIツールに渡すCSVでは、列名や順番が変わるだけで取込が失敗することがあります。

Excelで加工するだけでも、列順が変わるとVLOOKUPやPower Queryの参照が壊れることがあります。

出力項目は、次のように表で管理します。

順番	kintoneフィールド	フィールドコード	CSV列名	用途
1	顧客番号	customer_code	customer_code	突合キー
2	顧客名	customer_name	customer_name	表示
3	請求月	billing_month	billing_month	月次集計
4	請求金額	billing_amount	amount	会計連携
5	税区分	tax_type	tax_type	会計連携
6	担当者	owner	owner_login	問い合わせ先
7	更新日時	updated_at	updated_at	差分確認

CSVを再度kintoneに読み込む可能性があるなら、更新キーを必ず出します。

kintoneヘルプでは、一括更新に使用するファイルを書き出す際には、値を更新するフィールドと更新キーにするフィールドを書き出すと説明されています。

更新キーは、更新するレコードとファイルの行を紐づけるために使われます。

kintoneヘルプ：レコードのデータをファイルに書き出す際の注意事項

kintone一括更新の設計方法はこちら

文字化け・先頭ゼロ・日付形式の注意点

CSV出力で現場がつまずきやすいのは、出力後にExcelで開いたときです。

文字化けする。

顧客番号の先頭ゼロが消える。

郵便番号や電話番号が数値扱いになる。

日付が別形式に見える。

金額の桁区切りが消えて見える。

ユーザー選択がログイン名で出て、誰か分かりにくい。

これらは、kintoneから出せるかどうかではなく、受け取り側でどう使うかの問題です。

kintoneヘルプでは、ファイル書き出し時に文字コードと区切り文字を選択でき、Excelで開く場合は区切り文字にカンマを選ぶことがすすめられています。

kintoneヘルプ：ファイルにデータを書き出す

文字コードは、受け取り先で決めます。

受け取り先	選びやすい方針	注意点
Excelで人が開く	Shift_JISやExcelで扱いやすい形式を検討	機種依存文字や絵文字に注意
Googleスプレッドシート	UTF-8を基本にする	Excel再保存で崩れないようにする
外部システム	連携仕様に合わせる	文字コードを仕様書に明記する
BIツール	UTF-8を基本にする	列名、型、NULL扱いも固定する
kintoneへ再取込	読み込み側の仕様に合わせる	ヘッダー、更新キー、表示名に注意

先頭ゼロは、CSV出力後のExcel操作で壊れやすい項目です。

顧客番号、商品コード、郵便番号、電話番号、部署コードは、計算する数字ではなくコードです。

出力後にExcelで直接開くと、見た目が変わることがあります。

対策は、kintone側の型だけでは足りません。

対策	内容
文字列フィールドにする	kintone上でコードを数値として持たない
出力仕様に明記する	先頭ゼロを保持する列を指定する
Excel側の取り込み手順を決める	CSVをダブルクリックで開かない運用にする
提出先に確認する	コード列を文字列として受け取れるか確認する
チェック列を持つ	桁数、空欄、重複を確認する

日付形式も注意が必要です。

kintoneヘルプの出力ファイル補足では、日付や日時の形式は、ファイルを書き出すユーザーの表示言語設定やWebブラウザーの言語設定によって異なると説明されています。

kintoneヘルプ：出力されたファイルに関する補足事項

外部連携でCSVを使うなら、日付を人の表示設定に依存させない方が安全です。

日付は、受け取り先で必要な形式を決めます。

たとえば、YYYY-MM-DD、YYYY/MM/DD、日時ならタイムゾーンを含めるか、時刻をJSTで固定するかを決めます。

必要なら、出力後に変換する中間処理を置きます。

CSV出力の文字化けや先頭ゼロの問題は、出力ボタンの問題ではなく、受け取り先の文字コード、型、日付形式まで含めたデータ仕様の問題です。

コメント・添付ファイル・テーブルの扱い

kintoneの画面で見えるものが、すべて同じCSVに出るわけではありません。

kintoneヘルプの入出力できるデータ一覧では、添付ファイルや関連レコード一覧は入出力対象ではないものとして示されています。

また、コメントは出力できますが、変更履歴は出力対象ではありません。

kintoneヘルプ：入出力できるデータの一覧

レコードのデータを書き出す際の注意事項でも、ラベル、添付ファイル、関連レコード一覧、変更履歴はファイルに書き出せないデータとして示されています。

kintoneヘルプ：レコードのデータをファイルに書き出す際の注意事項

出力設計では、CSVに含めるものと、別で扱うものを分けます。

対象	CSV出力での扱い	設計すること
通常フィールド	出力しやすい	項目順、列名、型
計算フィールド	計算結果が出る	再計算元も必要か確認
チェックボックス	選択肢ごとに列が分かれる	受け取り先の列構造を固定
複数選択	選択肢ごとに列が分かれる	選択肢追加時の列増加
テーブル	行の扱いを検証する	親レコードとの突合キー
コメント	レコードとは別CSV	コメント機能、突合キー、保管
添付ファイル	標準CSVには出ない	別ダウンロード、保管先、URL
関連レコード一覧	標準CSVには出ない	参照先アプリを別出力
変更履歴	標準CSVには出ない	監査要件がある場合は別設計

コメントについては、レコードを書き出す際に出力オプションを使うと、レコードとは別のCSVファイルで出力されると説明されています。

kintoneヘルプ：レコードのデータをファイルに書き出す際の注意事項

コメントCSVを使う場合は、本文のレコードCSVと突合できるキーを確認します。

コメントは業務履歴として重要なことがありますが、レコードの値とは別物です。

添付ファイルも同じです。

契約書、請求書、写真、証憑などが添付されているアプリで、CSVだけを書き出しても、ファイル本体のバックアップにはなりません。

cli-kintoneのrecord exportでは、--attachments-dirを指定した場合、添付ファイルをローカルディレクトリにダウンロードできると説明されています。

また、--conditionや--fieldsで出力条件やフィールドを指定でき、--encodingで文字エンコーディングも指定できます。

cli-kintone：record export

kintone添付ファイルの設計方法はこちら

Excel加工と外部システム連携の境界

kintone CSV出力の用途は、大きく2つに分かれます。

人がExcelで加工する用途。

外部システムが機械的に読み込む用途。

この2つを同じCSVで満たそうとすると、どちらにも使いにくくなります。

観点	Excel加工向け	外部システム向け
列名	人が読める名前	フィールドコードや仕様上の列名
ユーザー	表示名が見やすい	ログイン名やIDが安定
日付	人が見やすい形式	仕様で決めた固定形式
金額	見た目より数値処理を優先	カンマなし、通貨記号なし
空欄	人が判断できる	NULL、空文字、0を区別
並び順	確認しやすさ	取込仕様に合わせる
添付	手動で参照しやすい	ファイルパスやIDを持つ

たとえば、ユーザー選択を表示名で出すと、人は読みやすいです。

一方で、kintoneへ再取込したり、外部システムで担当者を突合したりするなら、ログイン名やコードが必要になります。

kintoneヘルプでも、ユーザー、組織、グループを表示名で出力するオプションがあり、チェックを外すとユーザーはログイン名、組織は組織コード、グループはグループコードで出力されると説明されています。

また、表示名で記載されている場合は、ファイルを読み込んだときにユーザー選択などのデータを登録・更新できないと注意されています。

kintoneヘルプ：ファイルにデータを書き出す

Excel加工用CSVと外部連携用CSVは、出力仕様を分ける方が安全です。

出力仕様	列名	ユーザー	保存先
社内確認用	日本語列名	表示名	チーム共有フォルダ
再取込用	フィールド名またはフィールドコード	ログイン名	管理者フォルダ
会計連携用	会計側の列名	担当者コード	連携フォルダ
BI用	英字列名	ID/コード	データ基盤
監査提出用	提出先指定の列名	必要最小限	提出版フォルダ

Excelでの加工を前提にする場合も、加工後に正本がどこにあるかを決めます。

Excelで修正した結果をkintoneへ戻すのか。

Excelは集計だけに使い、kintoneは変更しないのか。

外部へ提出したCSVを正式版として保存するのか。

ここを決めないと、CSV出力後にデータの責任が曖昧になります。

kintone帳票出力の設計方法はこちら

定期出力と自動化の判断

毎回同じ条件でCSVを出しているなら、手動操作を続けるべきかを見直します。

ただし、自動化するかどうかは、頻度だけでは決めません。

状態	判断
年数回の提出	標準画面からの手動出力でよいことが多い
月次バックアップ	一覧条件、保存先、ファイル名を固定する
週次のBI投入	cli-kintoneやAPIによる定期出力を検討する
日次の外部連携	REST API、カーソル、連携ログを設計する
大量データ出力	件数、ファイルサイズ、分割単位を決める
添付込み出力	CSVと添付ファイルの保存構造を分ける

標準画面からのCSV出力は、人が確認しながら実行する場面に向きます。

一方で、毎日や毎週の連携では、作業者の手順に依存すると抜け漏れが起きます。

cli-kintoneのrecord exportでは、条件、並び順、出力フィールド、文字コード、添付ファイルディレクトリを指定できます。

cli-kintone：record export

REST APIで取得する場合、複数レコード取得APIは、1回に取得できるレコードが500件まで、offsetの上限が10,000件と説明されています。

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

大量データを扱う場合は、カーソルAPIも選択肢になります。

cybozu developer networkでは、レコードを一括取得するためのカーソル作成APIが説明されており、取得対象フィールド、クエリ、1回の取得件数を指定できます。

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

自動化する場合は、CSVを出す処理だけでなく、次を設計します。

項目	内容
実行条件	毎日、毎週、締め後、承認後
対象条件	どのステータス、どの期間、どの部署
出力項目	フィールドコード、列順、型
ファイル名	アプリ名、用途、日付、版
保存先	外部ストレージ、連携フォルダ、ログアプリ
成功ログ	件数、ファイルサイズ、保存先
失敗ログ	権限、API制限、文字コード、添付失敗
再実行	同じ条件で上書きするか、別版にするか
通知	完了、失敗、件数異常

自動化しても、人の確認が不要になるわけではありません。

外部提出や会計連携では、実行前に締め状態を確認する。

BI連携では、件数や合計が前回と大きく違わないかを見る。

バックアップでは、保存先にファイルが残っているかを確認する。

このように、定期出力では、処理と確認を分けます。

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

出力履歴と再ダウンロード

CSV出力では、ファイルを出した事実も管理します。

いつ、誰が、どの条件で、どのファイルを出したのか。

そのファイルを誰に渡したのか。

再出力した場合、前回ファイルと何が違うのか。

ここが残らないと、外部提出や監査対応で困ります。

kintoneヘルプでは、ファイル書き出し後に出力されたファイル画面へ遷移し、書き出し完了後にファイル名をクリックしてダウンロードすると説明されています。

ファイル名は、アプリ名に日時のタイムスタンプが付く形式で、コメントCSVの場合は_commentsが付く例も示されています。

kintoneヘルプ：ファイルにデータを書き出す

この標準の出力結果に加えて、業務上は次を残すとよいです。

ログ項目	内容
出力ID	出力作業を識別する番号
出力目的	提出、連携、保存、再取込用など
対象アプリ	アプリ名、アプリID
一覧条件	保存済み一覧名、絞り込み条件
出力項目版	列定義のバージョン
実行者	操作ユーザー、APIトークン管理者
実行日時	出力開始、完了
件数	出力レコード数
ファイル名	保存ファイル名
保存先	Drive、Box、ローカル、連携先
受け渡し先	提出先、連携先、担当者
再出力理由	修正、条件変更、再提出

再ダウンロードと再出力は分けます。

再ダウンロードは、同じ出力結果をもう一度取得することです。

再出力は、現在のkintoneデータを改めてCSVにすることです。

その間にレコードが更新されていれば、内容は変わります。

CSVの再ダウンロードと再出力は別物です。外部提出や監査用途では、どの時点のデータを渡したかを出力履歴として残します。

よくある失敗

kintone CSV出力でよくある失敗を整理します。

失敗	原因	対策
対象件数が毎回違う	一覧条件を手動で変えている	出力用一覧を保存する
列順が変わる	出力項目を毎回選び直している	出力項目表を持つ
文字化けする	受け取り先の文字コードと合わない	文字コードを仕様に書く
先頭ゼロが消える	Excelで数値扱いになる	文字列列として取り込む手順を決める
日付形式が違う	表示言語やブラウザー設定に依存	連携用は固定形式へ変換する
担当者が突合できない	表示名とログイン名が混ざる	用途ごとに出力形式を分ける
添付ファイルがない	標準CSVに含まれると思っていた	添付ファイルは別で取得する
コメントが見つからない	別CSVになることを知らない	コメントCSVの突合方法を決める
変更履歴を提出できない	標準CSVで出ない	監査要件を別設計にする
再提出時に差分が分からない	出力履歴がない	出力IDと保存版を残す

多くの失敗は、kintoneの機能不足ではなく、出力後の使い方を決めていないことから起きます。

CSVは、kintoneの外に出た瞬間に、Excel、会計、BI、外部システム、提出先のルールに影響されます。

だからこそ、CSV出力は、kintone内の一覧設定だけでなく、外側の受け取り仕様まで見ます。

実装前チェックリスト

kintone CSV出力を設計する前に、次を確認します。

チェック	確認内容
出力目的	提出、加工、保存、連携、復元のどれか
対象アプリ	アプリ名、アプリID、責任者
対象一覧	保存済み一覧、絞り込み条件、並び順
出力項目	フィールド名、フィールドコード、列順
更新キー	再取込や突合に必要なキーを含めるか
文字コード	受け取り先に合わせて決める
区切り文字	カンマ、タブなど
表示名	ユーザー、組織、グループを表示名にするか
先頭ゼロ	コード列を壊さない手順があるか
日付形式	受け取り先の形式と合うか
コメント	別CSVとして扱うか
添付ファイル	別取得、外部ストレージ、URL管理
権限	ファイル書き出し権限、閲覧権限
保存先	ファイル名、フォルダ、保存期間
出力履歴	実行者、日時、件数、提出先、再出力理由
定期化	手動、cli-kintone、REST API、連携サービス

このチェックリストを埋めると、CSV出力は「必要なときに出す作業」から「説明できるデータ提供」に変わります。

特に、外部提出、会計連携、バックアップ、再取込に使うCSVでは、出力条件と出力項目を文章で残すべきです。

Bitlightに相談できること

Bitlightでは、kintone CSV出力を、外部へ渡すデータ仕様として設計します。

たとえば、次のような整理を支援できます。

• 出力目的ごとのCSV仕様作成
• 出力用一覧、絞り込み条件、並び順の設計
• 出力項目、フィールドコード、列順の整理
• 文字コード、区切り文字、日付形式、先頭ゼロのルール化
• Excel加工用、再取込用、外部連携用CSVの分離
• コメント、添付ファイル、関連レコード、変更履歴の扱い整理
• 出力権限、閲覧権限、提出先の確認
• 出力履歴、保存先、再出力ルールの設計
• cli-kintoneやREST APIを使った定期出力の実装
• バックアップ、BI、会計、外部システム連携との接続設計

kintoneからCSVを出すこと自体は難しくありません。

難しいのは、出したCSVを、誰が見ても同じ意味で扱える状態にすることです。

受け取り先がExcelなのか、会計ソフトなのか、BIなのか、監査資料なのかで、必要な列、型、文字コード、保存ルールは変わります。

CSV出力を業務の出口として設計しておけば、出力後の手戻り、再提出、突合ミスを減らせます。

kintone CSV出力は、データを外へ出す作業です。出力条件、項目、形式、履歴、受け取り先まで含めて設計すると、業務で使えるCSVになります。