データのインポートとレコードの削除

目次

はじめに

前回は、cli-kintone を使って、レコードのデータをエクスポートする方法を学びました。
今回も引き続き、 顧客リストアプリを利用してレコードの追加/更新/削除の方法を紹介していきます。

API トークンの設定

データのエクスポート で発行した API トークンの「アクセス権」設定を変更します。
今回はレコードの追加/更新/削除のため、「レコード閲覧」「レコード追加」「レコード編集」「レコード削除」にチェックを入れてください。

レコードの追加

まずは顧客リストアプリにレコードを追加してみましょう。

STEP 1. 追加するレコードのデータを CSV ファイルで用意する

顧客リストアプリに追加するレコードのデータを CSV ファイルで用意します。
CSV ファイルを用意する際は、顧客リストアプリからエクスポートしたファイルを編集するのがおすすめです。
データのエクスポート を参考に cli-kintone を使ってエクスポート、もしくは、 ファイルにデータを書き出す (External link) を参考にしてください。

1 行目は列に対応するフィールドのフィールドコード、2 行目以降が追加するデータとなります。
レコード追加の際、必須項目以外のフィールドのデータを入力する必要はありません。
「作成者」「作成日時」「更新者」「更新日時」は追加/更新ができないため、列を削除してください。
また、今回のデータには、後述の レコードの更新 で更新する「部署名」フィールドを含めていません。

1
2
3
4
"company","name","post_code","tel","fax","address","rank","mail_address","note"
"朝日商事","品川 吉織","1660001","090-××××-××××","050-××××-××××","東京都杉並区××××","A","shinagawa_yoshiki@example.com","ご挨拶を実施"
"赤松機械","中田 助勝","1036028","080-××××-××××","040-××××-××××","東京都中央区××××","B","nakata_sukekatsu@example.com","新規のお客様"
"青木建設","友岡 春樹","3300041","070-××××-××××","030-××××-××××","埼玉県浦和市××××","C","tomooka_haruki@example.com","先月お問い合わせをいただいた"

上記のファイルを「add_customers.csv」とし、文字コードを Shift-JIS にして保存します。
今回は、cli-kintone の実行ファイルを置いたディレクトリーにファイルを配置しています。

STEP 2. レコードを追加する

それではレコードを追加してみましょう。
レコードを追加する場合、record import を指定します。
ドメイン名とアプリ ID、API トークンの他に --file-path で CSV ファイルのパスを指定します。
また、データのエクスポート時と同様に --encoding オプションでインポートするファイルの文字コードを指定できます。
今回は Shift-JIS のため、sjis を指定します。

1
cli-kintone.exe record import --app 299 --base-url https://sample.cybozu.com --api-token APIトークン --encoding sjis --file-path ./add_customers.csv

以下のようにレコードが追加されます。

レコードの更新

レコードを更新する場合も、追加時と同様に record import を指定します。
また、--update-key オプションで、更新のキーとなるフィールドのフィールドコードを指定します。
--update-key オプションで指定できるフィールドは以下です。

  • レコード番号
  • 「値の重複を禁止にする」を有効にした次のフィールド
    • 文字列(1 行)
    • 数値

--update-key に指定したフィールドと、CSV ファイル内の対応する列の値が一致するレコードは上書きされます。
一致しない場合は、新規にレコードが追加されます。

さっそく、 レコードの追加 で追加したレコード情報を更新してみましょう。

STEP 1. レコード番号 の列を含むレコードのデータを CSV ファイルで用意する

id の列を含むデータを CSV ファイルで用意します。
ファイルの用意は レコードの追加時の方法 を参考にしてください。

では、「部署名」(フィールドコード:department)の値を更新する CSV ファイルを用意してみましょう。
CSV ファイルで入力を省略したフィールドは更新されないため、更新したいフィールドのみファイルに入力してください。

1
2
3
4
"id","department"
"6","経理部"
"5","開発部"
"4","営業部"

上記のファイルを「update_customers.csv」として Shift-JIS で保存します。

STEP 2. レコードを更新する

今回は、レコード番号(フィールドコード:id)を更新のキーとするため、 --update-keyid を指定しましょう。

1
cli-kintone.exe record import --app 299 --base-url https://sample.cybozu.com --api-token APIトークン --encoding sjis --file-path ./update_customers.csv --update-key "id"

先ほど追加したレコードの「部署名」が更新されていることを確認しましょう。

information

CSV ファイルに添付ファイルフィールドの列を含めてレコードを追加・更新する場合、--attachments-dir オプションが必須です。
詳細は 添付ファイルのダウンロードとアップロード を参照してください。

テーブルを含むレコードの追加・更新

こちらは データのエクスポート の交通費申請アプリを使って確認しましょう。
わかりやすくするために、下表のように一部のフィールドコードを変更しています。
「明細」はテーブルフィールドで、「日付」「訪問先」「交通手段」「金額」はテーブル内のフィールドです。

フィールド名 フィールドコード
レコード番号 id
社員番号 number
所属部署 department
承認者 authorizer
タイトル title
明細 detail
日付 date
訪問先 place
交通手段 transportation
金額 price
合計金額 sum
備考欄 remarks

また、顧客リストアプリと同じく、API トークンの「アクセス権」設定で「レコード閲覧」「レコード追加」「レコード編集」「レコード削除」にチェックを入れてください。

STEP 1. テーブルを含むレコードのデータを CSV ファイルで用意する

交通費申請アプリに登録されているデータをエクスポートし、CSV ファイルの中身を変更します。
今回は、更新対象をわかりやすくしたいため、--fields オプションに以下の項目を指定してフィールドを絞り込んでエクスポートします。

  • レコード番号(フィールドコード:id)
  • タイトル(フィールドコード:title)
  • 明細(フィールドコード:detail)
1
cli-kintone.exe record export --app 300 --base-url https://sample.cybozu.com --api-token APIトークン --encoding sjis --fields "id,title,detail" > C:\Users\Desktop\update_table.csv

エクスポートした CSV ファイルの中身は以下になります。
前回の記事で説明したとおり、* の行から次の * の前の行までが 1 つのレコードのデータを表しています。
以下の場合、レコード番号がそれぞれ、1,2,3 の 3 つのレコードがエクスポートされています。

1
2
3
4
5
6
7
8
9
*,"id","title","detail","date","place","transportation","price"
*,"1","7月分交通費","5039","2023-07-01","大阪支社訪問","新幹線(往復)","30000"
,"1","7月分交通費","5052","2023-07-04","通勤往復","電車(往復)","1500"
,"1","7月分交通費","5053","2023-07-06","通勤往復","電車(往復)","1500"
*,"2","6月分交通費","5043","2023-06-01","通勤往復","電車(往復)","1000"
,"2","6月分交通費","5050","2023-06-05","出張","飛行機(往復)","20000"
*,"3","7月分交通費","5047","2023-07-05","健康診断","バス(片道)","500"
,"3","7月分交通費","5048","2023-07-07","通勤往復","電車(往復)","2100"
,"3","7月分交通費","5049","2023-07-17","通勤往復","電車(往復)","2100"

今回は、次のように CSV ファイルを変更してみましょう。

  • レコード番号が 1 のレコードについて、テーブルの最終行の金額(フィールドコード:price)を変更する。
  • レコード番号が 2 のレコードについて、テーブルに行を追加する。
  • テーブルのデータを含むレコードを新規に追加する。

CSV ファイル内の id 列に値が入っていない行は新規レコードとして追加されます。

1
2
3
4
5
6
7
8
9
*,"id","title","detail","date","place","transportation","price"
*,"1","7月分交通費","5039","2023-07-01","大阪支社訪問","新幹線(往復)","30000"
,"1","7月分交通費","5052","2023-07-04","通勤往復","電車(往復)","1500"
,"1","7月分交通費","5053","2023-07-06","通勤往復","電車(往復)","2000"
*,"2","6月分交通費","5043","2023-06-01","通勤往復","電車(往復)","1000"
,"2","6月分交通費","5050","2023-06-05","出張","飛行機(往復)","20000"
,"2","6月分交通費","","2023-06-10","出張","新幹線(往復)","30000"
*,"","8月分交通費","","2023-08-07","大阪支社訪問","新幹線(往復)","30000"
,"","8月分交通費","","2023-08-09","通勤往復","電車(往復)","2100"

上記のファイルを「update_table.csv」として保存します。

STEP 2. テーブルを含むレコードを追加・更新

コマンドはレコードの更新時と同様に、--update-key オプションを使用します。

1
cli-kintone.exe record import --app 300 --base-url https://sample.cybozu.com --api-token APIトークン --encoding sjis --file-path ./update_table.csv --update-key "id"

各レコードのサブテーブルの更新と、レコードの追加が行われます。

更新用 CSV ファイル

更新されたレコード
テーブルの最終行の金額が変更されたレコード

テーブルに新規の行が追加されたレコード

追加されたレコード

既存のレコードのテーブルを更新する場合の注意点

一部の行だけを更新する場合

テーブル内に更新しない行があっても、CSV ファイルにはすべての行データを記載してください。
ファイルに記載のない行はテーブルから削除されます。

一部の列(フィールド)だけを更新する場合

テーブルの一部の列だけを更新する場合でも、すべてのフィールドのデータを記載してください。
ファイルに記載されていないテーブルのフィールドは、空で更新されます。

ただし、すべての行において更新しない列がある場合には、行 ID を記載することで元のデータを保持できます。
行の ID は、テーブルフィールドのフィールドコードの値として確認できます。

たとえば、次のテーブルで「price」列のデータだけを更新したいとします。

date place transportation price
2023-08-07 大阪支社訪問 新幹線(往復) 3000040000
2023-08-09 通勤往復 電車(往復) 2100

この場合、次の CSV ファイルを作成します。
「detail」が行の ID です。

1
2
3
*,"id","title","detail","price"
*,"1","7月分交通費","5039","40000"
,"1","7月分交通費","5053","2100"

レコードの削除

最後にレコードを削除してみましょう。
レコードの削除は、削除対象を指定する方法と、すべてのレコードを一括で削除する方法の 2 パターンが存在します。

caution
警告

削除したレコードは元に戻せません。

特定のレコードを削除する

まずは、特定のレコードを削除してみましょう。
特定のレコードを削除する場合は、追加/更新時と同様に削除対象を記載した CSV ファイルを用意します。

STEP 1. 削除するレコードのデータを CSV ファイルで用意する

顧客リストアプリから削除するレコードのデータを CSV ファイルで用意します。
列にはレコード番号フィールドのフィールドコードを指定します。

1
2
3
"id"
"1"
"2"

CSV ファイルの 2 行目以降は、削除するレコードのレコード番号か、 アプリコード (External link) を設定している場合はアプリコードを含むレコード番号のどちらかを指定してください。
上記のファイルを「delete_customers.csv」として保存します。

STEP 2. レコードを削除する

削除する際は、record delete を指定します。
record delete を使ったレコードの削除は、API トークン認証のみ対応しています。
追加/更新時と同様に、ドメイン名とアプリ ID、API トークンを設定し、--file-path で CSV ファイルのパスを指定します。

1
cli-kintone.exe record delete --app 299 --base-url https://sample.cybozu.com --api-token APIトークン --file-path ./delete_customers.csv

コマンドを実行すると、削除を確認するメッセージが表示されます。
削除する場合は「y」を入力して、Enter キーを押します。キャンセルする場合は「n」を入力します。

information

--yes または -y オプションをつけてコマンドを実行すると、削除確認のメッセージが表示されずにレコードを削除できます。

1
2
# --yes オプションをつけると、確認メッセージが表示されずにレコードが削除されます
cli-kintone.exe record delete --app 299 --base-url https://sample.cybozu.com --api-token APIトークン --file-path ./delete_customers.csv --yes

すべてのレコードを削除

--file-path オプションを省略すると、すべてのレコードを削除できます。

1
cli-kintone.exe record delete --app 299 --base-url https://sample.cybozu.com --api-token APIトークン

レコードが正しく追加・更新・削除されていない場合のデバッグ方法

インポートや削除に失敗した場合、コマンドライン上のエラーメッセージを確認することでエラー原因を確認できますが、監査ログ上でもリクエスト結果を確認できます。
監査ログは一定期間の保存が可能なため、レコードの操作結果を後から確認できます。
詳細は、「 監査ログを閲覧する (External link) 」を参照ください。

監査ログの詳細では、次のことを確認できます。

  • アクション:レコードの操作の内容(追加/更新/削除)
  • 結果:アクションの結果
  • 補足:操作対象のアプリやレコード番号、API トークン

これらの内容を参照して、データの内容に誤りがないかなどを確認してみてください。

おわりに

今回は、cli-kintone を使って、レコードのデータを追加/更新/削除する方法を学びました。

次回は、 添付ファイルのダウンロードとアップロード の方法について学びましょう。

information

この Tips は、cli-kintone Ver 1.8.0 と 2023 年 8 月版 kintone で動作を確認しています。