kintone コマンドラインツール （cli-kintone）
（著者：瀧ヶ平 充）
Index
はじめに
前回の記事で、cli-kintoneの導入とレコードの取得について理解していただけたと思います。
※この先kintone コマンドラインツールはcli-kintoneと表記します。
今回も引き続きフィールドコードをカスタマイズした顧客リストアプリを利用して、レコードの追加と削除のやり方を紹介します。
レコードの追加
STEP1 追加するレコードのデータをCSVファイルで用意する
まずは追加するレコードのデータのCSVファイルを作成しましょう。
このとき、必須項目以外のフィールドは入力しなくても問題ありません。
今回はこの内容をcustomers.csvとし、文字コードをShift-JISにして保存します。
STEP2 レコードを追加する
レコードを追加するときは、認証のオプションに加えて -f オプションでファイルを指定して追加します。
このとき作成したレコードのファイルのエンコーディングをエクスポート時と同様に -e オプションで指定します。
今回はShift-JISで作成したのでsjisを指定しましょう。
実行ファイルと同じ場所に customers.csv を保存した場合
customers.csv のファイルパスを指定する場合
customers.csv ファイルの途中行からインポートする場合
レコードを削除した後にレコードを追加
STEP1 全てのレコードを削除してからレコードを追加する
cli-kintoneでレコードを削除してからレコードを追加する際には -f オプションを利用した上で -D オプションを利用します。
このときクエリで絞り込みをしない場合すべてのレコードを削除してからレコードが追加されます。
STEP2 クエリで絞り込みをしたレコードを削除してからレコードを追加する
レコード追加前に一部のレコードのみを削除したい場合、-q オプションを使って削除対象レコードをクエリで絞り込んでから実行する必要があります。
クエリの書き方は前回の取得の時と同様にこちらを参考にしてください。
今回は担当者名に「瀧ヶ平」を含む最新5件のレコードを削除してから、新たにレコードを追加してみましょう。
STEP3 レコードの追加をせず削除のみ行う
空のCSVファイルを作成し、-f オプションで指定した上で -D オプションを利用すればレコードを追加せずに削除することができます。
この動作は v0.10.2 までは可能でしたが、想定されていない挙動でした。v0.11.13 から使用することはできなくなっています。
テーブルを含むレコードを追加する
こちらも前回と同様交通費申請アプリを使って確認しましょう。
STEP1 テーブルを含むレコードのCSVファイルを作成する
テーブルを含むレコードを追加する場合は、テーブルを含むレコードを取得したCSVと同じように、フィールドコードの行と各レコードの1行目の最初に*,を追加します。
既にあるレコードをcli-kintoneでエクスポートしたものを参考にCSVを作成すると間違いなく作れるかと思います。
この内容をsubtable.csvとしてShift-JISで保存しましょう。
STEP2 CSVファイルを指定してレコードを追加する
テーブルを含まない場合と同様に、 -f オプションでファイルを指定してレコードを追加します。
注意ポイント：チェックボックスや複数選択で複数チェックが入る場合のCSV表現
今回のサンプルアプリにはありませんでしたが、フィールドに複数の値が含まれる場合は "" 内に改行区切りで選択される値を表記する必要があります。
Excelなどで確認するとセルの中で改行されている形で表示されるかと思います。Excelで編集する場合はAlt + Enterを押すことでセル内で改行することができます。
テーブル内でも同様で、テーブルの行内当該のフィールドの値を "" 内改行区切りで選択される値を表記します。
CSV表現の例
上の画像のレコード2件の場合、次のCSVで表現できます
▼ エクセルで表示した場合
CSV表現の例(テーブル内のフィールドの場合)
上の画像のレコード2件をCSVで表現する場合以下になります。
▼ エクセルで表示した場合
レコードが正しく追加されてない場合のデバッグ方法
概ねエラーメッセージに対応すればエラーは解消されるとは思いますが、cybozu.com 共通管理から実行されたリクエストを見ると問題が特定しやすいです。
kintoneの右上の歯車のマークのメニューから「cybozu.com共通管理」へ移動し、左のカラムの「システム管理」内「監査ログ」の「閲覧とダウンロード」に移動します。
こちらの監査ログの一覧を見ると、レコード操作やその成否が、また表左の「i」マークをクリックすると詳細なレコード操作の内容が確認できます。
こちらを見て、cli-kintoneからリクエストが届いているか、どのようなエラー内容が出ているかを見ることでうまくいかない原因を探しやすくなりますね。
コマンドラインに出力された処理結果の見方は、Version 0.9.0 新機能紹介記事のデータインポート時に処理結果を出力するを参照してください。
第2回はここまでです。レコード追加と削除、いかがでしたでしょうか？
次はレコードの更新をやっていきます、お楽しみに。
このTipsは、cli-kintone Ver 0.10.2 と2020年3月版 kintone で確認したものになります。
テーブルデータのインポートをしてみたのですが、
”＊”の有無にかかわらず、1行＝1レコードとして登録されてしまいました。
権限の問題で監査ログを見ることもできません。
CSV作成の際、注意することはありますか？
i.ohishiさん
cstapの瀧ヶ平です。
こちらでは再現していないのですが、可能であればCSV及びアプリのフォーム設定など教えていただけますでしょうか？
コメント欄では"*"が全角になっていますが、半角の"*"であれば問題なくインポート出来るはずです。
エラーが出ているのではなく1行1レコードとなってしまっているのであればおそらくCSV自体の書き方は問題ないはずなので、テーブル化する*の部分の問題かと思います。
STEP1 全てのレコードを削除してからレコードを追加する の質問です。
cli‐kintoneコマンドで-Dオプションを利用すると、DB上の既存レコードが全て削除されますが、次に追加レコードのレコード番号は、更新されていき-Dオプションで削除されたレコード番号は、欠番になる動作仕様のようです。ある意味、当たり前の動作だと思いますが、レコード番号をリセットしたい場合があります。
cli‐kintoneコマンドで -Dオプションで全レコードを削除後に、レコード番号=1にリセットし、追加登録する方法をご存知の方がいれば教えてください。
h.yamadaさん
cstapの瀧ヶ平です。
レコード番号をリセットしたいのであれば、-Dオプションで全て削除してから行うのではなく、新たに登録するID1から始まるレコードをレコードの更新によって行い、
レコードを更新した後、更新したレコードを除くレコードを-qオプションのクエリで絞り込み、-Dオプションで削除する方法で実現するのが良いかと思います。
この方法ではリビジョンなどの情報はリセットされず、これを実行した後に新たに登録する場合はレコードIDは削除済みのレコードのID+1の値から始まります。
そもそもkintoneでは削除したレコードのIDを埋めるようにレコードを作成するのは無理そうなので、これが限界かと思います。
欠番が出ることが問題なのであれば、自動採番プラグインを用いてレコードIDとは別の番号で管理するなどの代替案はどうでしょうか？
参考になれば幸いです。
cstap:瀧ヶ平さん、
レコード番号をリセット設定するコマンドや設定手段はやはりなさそうですね。
レコード削除があってもレコード番号で綺麗に欠番なく管理するプログラムは少し面倒そうなので、アドバイスを受けた方法などで工夫してみます。
> そもそもkintoneでは削除したレコードのIDを埋めるようにレコードを作成するのは無理そう
アドバイス、ありがとうございした。
素敵なツールありがとうございます。
同一のCSVファイルにおいて、UIの「ファイル読み込み」から登録すると正常に登録されるのに、コマンドラインから登録するとレコード数文の空データしか登録されない現象があります。
アプリ自体の構造はとてもシンプルなもの（文字列フィールドのみ）なのですが、切り分け方法についてヒントいただけないでしょうか？
shiraki 様
フィードバックをありがとうございます。
GUIからは正常に登録されるということで、コマンドに何らかの誤りがあると思われますが、
個別のトラブルシューティングについてはこちらの記事コメントでは対応いたしかねます。
恐れ入りますが、コマンドの詳細を記載の上、以下のトピックに投稿いただけますでしょうか。
QA, トラブルシューティング
https://developer.cybozu.io/hc/ja/community/topics/200021040
よろしくお願い申し上げます。
「チェックボックスや複数選択で複数チェックが入る場合のCSV表現」の例のようにやってみたのですが、チェックボックス欄にうまくデータが登録されません。
ちなみに単一選択であってもレコード自体は登録されますが、値がセットされません。
何か明示されていない前提条件がありますか。
Toshimichi Konno 様
こちらの手元で確認をしたいため、
をいただくことはできますでしょうか。
お手数をおかけしますが、よろしくお願いいたします。
実行したコマンド
cli-kintone.exe -a 148 -d qsv5k -t XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -f テスト.csv
テスト.csvの中身
"チェックボックス","複数選択"
"check1","select2"
デザイン画面スクショ
上記で実行した結果はチェックボックス、複数選択には何もセットされませんでした。
Toshimichi Konno 様
詳細の記載ありがとうございます！こちらでも同様の現象を確認することができました。
おそらく、文字コードが原因と思われます。対応策としては以下の2点がございます。
・コマンド実行時に文字コードを引数で追加する
cli-kintone.exe -a 148 -d qsv5k -t XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -e sjis -f テスト.csv
・CSV保存時に「UTF-8」で保存する
Excelなどで作成した場合、初期値として文字コードが「Shift-JIS」で保存する設定になっていることが多いです。
以上、ご確認よろしくお願いいたします。
回答ありがとうございます。
こちらで確認した結果、sjisではうまくいきましたが、UTF-8では複数選択はうまくいって、チェックボックスはうまくいきませんでした。
いつもお世話になっております。
以前からコマンドラインを使用し、レコードを削除した後にレコードを追加しています。
ところが、今年に入り急に１つのアプリだけ以下のようなエラーが出るようになりました。（ドメイン等は伏せてあります）
データの内容を見てもおかしな所がなかったため、手動でアプリから一括削除とファイルからの読込を行なったところ、正常に終了し使用できます。
アプリ、コマンドライン等、修正箇所は一切ありません。
データは毎回57000件ほどあります。修正する所などご教授いただけたらと存じます。
Z:\bat-k>c:\cli-kintone.exe -a アプリ№ -d ドメイン -t トークン -D -e sjis -f Z:\kintone同期\xxxマスタ.csv
2019/05/22 15:22:18 AppError: 400 [CB_VA01] 入力内容が正しくありません。 (nlR52PzevRXEdDIC95Ri)
CSVファイルのコードが間違えているかと思って、いろいろ変えたりしても同じでした。
KAORI SUZUKI 様
おせわになっております。
手元の環境（v0.9.4）にて、SUZUKI様記載のコマンドで実行してみましたが、問題なく一括削除およびインポートができました。
恐れ入りますが、以下の点についてご教示いただけないでしょうか。
（コマンド等でバージョン確認はできないため、大体どの時期にダウンロードされたか？などご教示いただけないでしょうか）
よろしくお願いいたします。
回答いただき、ありがとうございます。
2017年5月にダウンロードしたのを使っていたので、早速最新のcli-kintoneをダウンロードしました。
最新ので実行し、エラーの詳細が分かるようになったので修正をしているところです。
'records[78][登録年月日].value': 日時はISO8601形式の必要があります。
と、ずらずら･･･っと出ます。
アプリからファイルを読み込んだときは正常にインポートできます。
このフィールドは不要だったので、除外したところ正常にインポートできました。
今後日付フィールドの読み込みが必要になったとき、改めて質問させていただきます。
ありがとうございました。
KAORI SUZUKI 様
最新版でご検証くださりありがとうございます。
また、詳細なエラーメッセージについてもありがとうございます。
cli-kintone は内部的はに kintone REST API を使ってレコードの更新等を行っています。
そのため、日時フィールドの形式は kintone REST APIの概要 の日時のフォーマットに合わせる必要があります。
kintone のアプリ画面から日時をインポートする場合は、いくつかの形式をサポートしているので（フィールドの種類ごとの記載形式）、インポートできたと推測されます。
もし、エラーとなったフィールドをインポートすることになった場合は、ぜひkintone REST APIの概要 をご参照ください。
よろしくお願いいたします。
ご丁寧な説明をいただき、ありがとうございました。
日時フィールドを使用する際は参考にさせていただきます。
（2019年7月24日）
日時フィールドを使用する機会が訪れました。
教えていただいたとおり設定をし、正常に読み込めました。
ありがとうございました。
いつもお世話になっております。
6/4の質問と別件で質問いたします。
レコードの一括削除後追加をコマンドラインで行なっています。
アプリの上部に赤い枠で、
--------------------------------------------------------
│ エラー │
│ Cannot read property 'Xa' of undefined │
--------------------------------------------------------
と表示されます。
コマンドラインの処理の画面では、正常に終了し、すべてのレコードを読み込んでおります。
アプリのレコードも確認したのですが、特におかしなフィールド等はありませんでした。
コマンドラインの内容は以下のとおりです。プロパティ'Xa'が何のことか気になるのですが･･･
c:\cli-kintone.exe -a (ｱﾌﾟﾘID) -d (ﾄﾞﾒｲﾝ) -t (ﾄｰｸﾝ) -D -e sjis -f Z:\kintone同期\(ﾌｧｲﾙ名).csv
前回回答いただいて以降、cli-kintoneは最新版を使用しております。
これはスルーしても大丈夫でしょうか？
KAORI SUZUKI 様
アプリにエラーが表示されるとのことですが、
対象のアプリに JavaScript でのカスタマイズは行っていませんでしょうか。
cli-kintone のリクエストでエラーが発生した場合は基本的にコマンドライン上でエラーを出力するため、
そちらのエラーは JavaScript カスタマイズでのエラーの可能性がございます。
以上、よろしくお願い致します。
早速のお返事ありがとうございます。
当アプリは、ご指摘のとおりカスタマイズをgusukuCustomineで行なっております。
内容は、一覧画面の検索窓追加と文字サイズ拡大です。
カスタマイズを一旦無効にした後有効にし、やり直しをしたところ、エラーが出なくなりました。
ありがとうございました。
コマンドラインツールからファイルのインポート時にエラーが発生してしまいます。
解消方法、ご教授ください。
尚、該当アプリで同一のファイルの「ファイルから読み込む」では正常に読み込まれ動作しております
※該当アプリでは、ルックアップの設定をしており、LBCの値「46139」は参照先アプリに存在しています
※アプリやフィールド閲覧権限についても、everyone：閲覧、編集などすべてにチェックを入れております
・エラーの内容
Code: GAIA_LO04
Message: フィールド「LBC」の値「46139」が、ルックアップの参照先のフィールドにないか、またはアプリやフィールドの閲覧権限がありません
・実行しているコマンドライン
--import -a 32 -d ●● -t ■■ -e sjis -f c:\meisi\受注F.csv -D
関野 貢 様
お世話になっております。
cybozu developer network 運営局です。
API トークンを利用して、ルックアップフィールドを含むレコードの追加・編集はできません。
（ルックアップ先のアプリに対する権限がないため）
恐れ入りますが、ログインIDおよびパスワードを指定して実行していただけないでしょうか。
ログインID は -u で、パスワードは -p で指定します。
--import -a 32 -d ●● -u LOGIN_ID -p PASSWORD -e sjis -f c:\meisi\受注F.csv -D
参考：kintone コマンドラインツールの使い方
よろしくお願いいたします。
早速の回答有難うございます。
ご指示の内容で実行が出来ました。
有難うございます。
初歩的な質問で申し訳ないのですが、文法の間違いや他の確認個所がありましたらお教えください。
「レコードを削除した後にレコードを追加」のSTEP２を参考に、次のコマンドを実行しましたが、レコードが削除されません。
cli-kintone.exe --import -a <アプリID> -d <ドメイン名> -t <APIトークン> -q "契約番号 = \"99999999\"" -e sjis -D -f empty.csv
アプリID,ドメイン、APIトークンも確認しましたが合っていました。
empty.csvはWindows環境ですので次のコマンドで作成し0バイトであることも確認しました。
>type nul > empty.csv
トークンの権限とアプリ権限もフルで与えてあります。
cli-kintoneはv0.11.3とv.0.10.2の両方でテストしてみましたが結果は同じでした。
佐々木 幸生 様
お世話になっております。cybozu developer network 運営局です。
回答が遅くなりまして申し訳ございません。
下記コマンドを cli-kintone v0.10.2 で検証しましたところ、正常に削除することができました。
cli-kintone.exe --import -a <アプリID> -d <ドメイン名> -t <APIトークン> -q "契約番号 = \"99999999\"" -e sjis -D -f empty.csv
恐れ入りますが、以下の点をご確認の上、再度 cli-kintone v0.10.2 でお試しいただけますでしょうか。
- アプリID, ドメイン名, APIトークン, ファイルのパスが正しいか
- APIトークンに閲覧、編集、削除権限が付与されているか
- コマンドに書いたフィールドコードとアプリのフィールドコードが一致しているか
また、こちらのコメント欄は、記事自体へのフィードバック用となりますので、
技術的な問題などに関するご質問は、ぜひコミュニティをご活用ください。
よろしくお願いいたします。
コマンドラインツールにて、定期実行で不要なデータを一括削除のみがしたいのですが、
コマンドラインツールからはできないのでしょうか？また他の方法でできるようでしたらご教授下さい。
よろしくお願いします。
isoyuka 様
お世話になっております。cybozu developer network 運営でございます。
記事にありますとおり、削除のみというのは
v0.11.13 から使用することはできなくなっています。
コマンドラインツール以外からですと、REST API のレコードの一括削除を利用していただく方法がございます。
また、恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
上記試してみてわからないなど、記事から派生した技術的なご質問はcybozu developer コミュニティをご活用ください。
よろしくお願い致します。