サイボウズ「連携コネクタ」を使ってkintoneの値をCSVファイルに出力ができるのですがkintoneの機能での書き出しと書き出し形式がかなり異なるようです。
- kintoneの「ファイルに書き出す」で作られるCSVファイル
- 連携コネクタの「表データをCSVファイルに出力」で作られるCSVファイル
それぞれのフィールドがどのような形式で書き出されるのか調べてみました。
検証用アプリ作成
まず、検証用に全種類のフィールドを配置したアプリを作成して、適当にレコードを作成しました。
kintone「ファイルに書き出す」
まずは、kintoneの「ファイルに書き出す」を確認します。
文字コードと区切り文字は選択ができますが、今回はShift-JIS/カンマ区切りで出力します。
[アプリ名]_[書き出し日時].csv
というファイルが作成されてダウンロード可能になります。
ポイント1：ヘッダーはフィールドの「表示名」
ヘッダーはフィールドコードではなく表示名になります。
同じ表示名のフィールドが複数ある場合は、同じ値になるので注意が必要です。
ポイント2：複数選択
kintoneのファイルに書き出すで書き出されるレコードは、チェックボックスや複数選択の選択肢ごとにヘッダーが設定され、選択されている値に「1」が入っています。
ポイント3：テーブルの行
⚠️テーブルを書き出すと、1レコードの内容が複数行に分けて書き出されます、と出る通り、テーブルを書き出すと、先頭に「レコードの開始行」という列が追加されて、レコード1つにつき1つ、レコードの開始行に「＊」が入ったCSVになります。
テーブルの1行目の値は「＊」の行に入るのですが、2行目以降の値は「＊」のない行に入ります。テーブル外のフィールドの行は、同じ値が入っています。
1つのレコードにテーブルが複数ある場合は、1つ目のテーブルの1行目の値だけが「＊」の行に入り、2つ目以降のテーブルの行は1行目も含め、1つ目のテーブルの値が入っていない行に入ります。
| レコードの開始行 | テーブル外 フィールド |
テーブル1 フィールドA |
テーブル1 フィールドB |
テーブル2 フィールドC |
テーブル2 フィールドD |
|---|---|---|---|---|---|
| ＊ | (同じ値) | AAA | BBB | ||
| (同じ値) | CCC | DDD |
ポイント4：改行区切り
チェックボックスや複数選択フィールドは、選択肢ごとにヘッダーが分かれていますが、カテゴリーやユーザー選択・グループ選択・組織選択フィールドは、「改行区切り」になります。CSVファイルをExcelで開くと「セル内改行」になっています。
「ファイルから読み込む」で使用するファイルも、この形式に沿って作成しなければならないので、テーブルを含むレコードをインポートするのはとても大変です。
連携コネクタ「表データをCSVファイルに出力」
次に連携コネクタを使ってCSVファイルを出力してみます。
ステップ：[kintone]レコードの一覧取得
「取得するフィールド」にはフィールドコードを手動で入力する必要があるのが地味に大変💦と思いましたが、APIのパラメータと同じなので、何も指定しなければ全フィールド取得でした。
取得するフィールドの注意点1
テーブル内のフィールドは テーブルのフィールドコード を設定します。
取得するフィールドの注意点2
存在しないフィールドコードを設定しても無視されますが、重複して記載すると「表データエラー：表データの追加に失敗しました」というエラーになります。
ステップ：表データをCSVファイルに出力
文字コードと列の区切り文字に加え、行の区切り文字も指定ができます。
今回はUTF-8/カンマ区切り/Unixの改行、にしました。
UTF-8のCSVをExcelで開く際、「テキストファイルウィザード」ではなく、PowerQuery系の読み込みを使わないと、文字列（複数行）内の改行でデータが崩れてしまうので注意です。
Excelで開く場合には、Shift_JISにした方が便利です。
私は最初、Shift_JISにしたらエラーになりました。その詳細はこちらの記事で。
ファイル名の指定には、ボタンを押した日時を入れようと、sample_[executed_at]を指定しました。
書き出したCSVファイルをダウンロードできるようにするにはアップロードするステップも忘れずに。
ポイント1：ヘッダーはフィールドコード
表データをCSVファイルに出力の設定のヘッダーの列名
選択肢は、「内部IDを使用する」「表示されている列名を使用する」だったので、前者が「フィールドコード」後者が「フィールド表示名」かな？と思ったのですがどちらでやってみても、フィールドコードでした。謎。
ポイント2：カテゴリー、チェックボックス、複数選択はJSON形式（文字列の配列）
kintoneのファイルの書き出しでは、ヘッダーが選択肢ごとになっていたチェックボックス・複数選択、選択された値が改行区切りになっていたカテゴリー、ですがこちらは、1つのセルにJSON形式の文字列として出力されます。
| レコード番号 | カテゴリー | チェックボックス | 複数選択 |
|---|---|---|---|
| 1 | ["カテゴリー1","カテゴリー2"] | ["A"] | ["あ"] |
| 2 | ["カテゴリー1"] | ["あ","い"] |
ポイント3：添付ファイル、ユーザー/グループ/組織選択、テーブルはJSON形式（オブジェクトの配列）
添付ファイル、ユーザー/グループ/組織選択、テーブルはオブジェクトの配列を表すJSON形式です。
[{"contentType":"application/pdf","fileKey":"202608021258304BFD797B4AFA41EAB924CA1D51767B6E305","name":"テスト用.pdf","size":"144469"},{"contentType":"application/pdf","fileKey":"20260802125830226DC4D83F15419FA343DA3DB413C1E2012","name":"テスト用2.pdf","size":"3732218"}]
[{"code":"user1","name":"山田 太郎"}]
[{"id":"77823","value":{"テーブル内チェックボックス":{"type":"CHECK_BOX","value":["sample1","sample2"]},"テーブル内ユーザー選択":{"type":"USER_SELECT","value":[{"code":"user1","name":"山田 太郎"},{"code":"user2","name":"鈴木 花子"}]},"テーブル内文字列":{"type":"SINGLE_LINE_TEXT","value":"テーブル内文字列1"},"テーブル内添付ファイル":{"type":"FILE","value":[{"contentType":"application/pdf","fileKey":"20260802130556D06D04316BBB4329BBC965FA0F47AA33184","name":" テスト用.pdf","size":"144469"},{"contentType":"application/pdf","fileKey":"20260802130556BCE81AE7C8934FFB811F4049BADBF6E2103","name":"テスト用2.pdf","size":"3732218"}]}}},{"id":"77924","value":{"テーブル内チェックボックス":{"type":"CHECK_BOX","value":["sample1"]},"テーブル内ユーザー選択":{"type":"USER_SELECT","value":[{"code":"user2","name":"鈴木 花子"}]},"テーブル内文字列":{"type":"SINGLE_LINE_TEXT","value":"テーブル内文字列2"},"テーブル内添付ファイル":{"type":"FILE","value":[{"contentType":"image/png","fileKey":"2026081601011371911F4324AA4C35AEE0FD5AD8E04C9B070","name":"ブランク.png","size":"24796"}]}}}]
JavaScriptなどで扱うには便利な形式ですが、連携コネクタ上でこのJSON形式の値を分解・加工して利用するのは難しそうです。
まとめ
フィールドごとの書き出し形式の違いを以下の表にまとめました。
| kintoneファイルに書き出す | 連携コネクタからの出力 | |
|---|---|---|
| リッチエディター | HTMLタグの書き出しを選択 | HTMLタグ込み |
| チェックボックス | 選択肢ごと1列 | 選択された値の文字列の配列 |
| 複数選択 | 選択肢ごと1列 | 選択された値の文字列の配列 |
| カテゴリ | 複数選択されている場合は改行区切り | 選択された値の文字列の配列 |
| ユーザー選択 | 表示名/コード/両方を選択 複数選択されている場合は改行区切り |
code/nameのオブジェクトの配列 |
| グループ選択 | 表示名/コード/両方を選択 複数選択されている場合は改行区切り |
code/nameのオブジェクトの配列 |
| 組織選択 | 表示名/コード/両方を選択 複数選択されている場合は改行区切り |
code/nameのオブジェクトの配列 |
| 添付ファイル | （書き出し不可） | fileKey/nameなどのオブジェクトの配列 |
| テーブル | 1行ごと | 1行ごとにidのついたオブジェクトの配列 |
連携コネクタでkintoneのレコード追加・更新をする際に、複数選択が可能なフィールドの値を複数設定するには、キーの値をカンマ区切りで指定します。
例）
チェックボックス"sample1"と"sample2"を選択
➡️ 値に「sample1,sample2」を入力
ユーザー{"code":"user1","name":"山田 太郎"}と{"code":"user2","name":"鈴木 花子"}を選択
➡️ 値に「user1,user2」を入力
同様に、添付ファイルはアップロード用fileKeyをカンマ区切りにすれば複数の添付ファイルを設定できます。
出力時はJSON形式でテーブル全体を取得できますが、入力時には同じ形式をそのまま指定できるわけではありません。
テーブルの複数行を連携コネクタで設定するのはどうすればいいのでしょうか。難しそうです。