kintone コマンドラインツール （cli-kintone）
（著者：サイボウズ 三宅 智子）
Index
はじめに
kintoneではExcel/CSVを使ってデータのインポートやエクスポートをすることができますが、コマンドラインからもCSVファイルを使って同様なことができます！
kintone コマンドラインツールとは、簡単にコマンドライン上からkintoneにデータのインポート・エクスポートをできるようにしたツールのことです。
「はじめようkintone コマンドラインツール」では、以下のような方向けに、基本的な操作方法や活用方法をご紹介していきます。
- エクセルなどと連携させたいけど、プログラミング少し苦手という方
- コマンドラインでのデータのインポートやエクスポートをしたいという初心者の方
通常のCSVのデータ入出力ではできないことも、こちらのコマンドラインツールを使えばできる！なんてこともあったりします。
初回は、まず「環境設定」と「レコードデータの取得」というテーマでお届けします。
環境の準備
kintoneのコマンドラインツールを利用するにあたり、まずは下準備です。OSはWindows/Linux/Mac OS Xの3種類での動作を確認しています。
本シリーズでは、Windowsの利用を想定して記事を書いています。
コマンドラインツールのダウンロードと基本的な使い方については以下でご紹介していますので、ご参照ください。
※コマンドラインツールは、動作を保証するものではありません。
※ソースコードの変更および再配布、商用利用等はライセンスに従ってご利用可能です。
それでは早速環境設定に移っていきましょう！
STEP1 ツールをダウンロードする
kintone コマンドラインツール(β)の動作OSやダウンロード用のツールについてはこちらに記載があるので、まずはそちらを確認します。
kintone コマンドラインツールはReleases kintone/cli-kintone (Github)からダウンロードできます。Windows/Linux/Mac OS Xと3種類の実行ファイルが用意されています。
ダウンロードしたZip形式のファイルを解凍して、cli-kintone.exeをCドライブ直下Program Filesなど任意のフォルダに置いてください。
※本記事では、Version 0.7.1 windows-x64.zipを使っています。
また、本記事ではShift-JIS形式のCSVを作成して取得や更新や登録処理を行っていきます。Shift-JIS形式で保存できるテキストエディタもご準備ください。
STEP2 コマンドプロンプトを立ち上げる
Windowsの場合、「
キー」＋「Rキー」で下の「ファイル名を指定して実行」画面を立ち上げて、名前欄に「cmd」と入力します。OKをクリックするとコマンドプロンプトが立ち上がります。
（Macの場合は、ターミナルというアプリケーションを起動します。）
STEP3 コマンドラインツールを実行する
cdコマンドで、cli-kintone.exeを置いたディレクトリに移動します。
※ディレクトリはフォルダーと同義です。以下ディレクトリと表記します。
※「cd <スペース> <exeファイルを置いたディレクトリ>」 と入力すると、
指定したディレクトリに移動してくれます。Change Directoryと英語に変換するとイメージつきやすいですね！
他にもこの先知らないコマンドが出てくるかもしれないですが、そんなときは検索して調べてみてください。
次に引数を何も指定せずに実行すると、コマンドラインツールで利用可能なオプションが表示されます。
オプションの詳細はこちらの記事をご参照ください。
bash_profile などに cli-kintone が保存されているディレクトリへパスを通していただければ、cli-kintone コマンドが実行可能になります。
この後、上記のオプションを利用して各種操作をしていきます。
※コマンドラインツールを利用する際は、常に最新版であることを確認してお使いください。
※セキュアアクセス環境には対応していません。
データの取得
この後のシリーズでは、データの追加/削除/更新などの処理についてもご紹介しますが、まず第1回事始めとして「データの取得」を試してみたいと思います。
その前にデータを取得するアプリをご用意ください。ここではアプリストアにある顧客リストアプリを利用します。
デモデータも数件入れておきます。後々分かりやすいようにフィールドコードも英数に修正しておきましょう。
アプリの準備ができたら、上述のオプションを利用してデータの取得を行います。パターンがいくつかあるので、順にご紹介していきます。
STEP1 ユーザー名/パスワードでkintoneのデータを表示する
ドメイン名がsample.cybozu.com、アプリIDが777、ログイン名がmynameの場合の例です。
mynameユーザーのパスワードを入力すると、以下のようにCSV形式ですべてのフィールドのデータがエクスポートされます。
※セキュリティ保護のため、パスワードを入力してもコマンドライン上には何も見えないようになっています。
※kintone.comやcybozu.cnのドメインを指定する場合は、sampleだけでなく、sample.kintone.com/sample.cybozu.cnのようにFQDNを指定するようにしてください。
1行目にはフィールド名ではなく、フィールドコードがエクスポートされます。
JSON形式で表示するには、認証オプションの後ろに続けて-o jsonを指定します。他のサービスにデータを受け渡したい時などは、JSON形式のデータを利用するケースが多いです。
※途中で処理を中断したい場合は、CTRL+Cを押してください。
STEP2 APIトークンを利用してkintoneのデータを表示する
APIトークンを利用すると、パスワードを入力しなくてもデータをインポート・エクスポートすることができます。APIトークンを使うメリットは・・・
- ユーザー認証が必要ない
- 限られたアプリのみ操作できる
- 実行できる操作を制限することができる
などが挙げられます。
APIトークンの生成方法はこちらをご参照ください。実行したい操作に合わせて、APIトークンの権限を設定していただく形になります。
※APIトークン認証を使った場合は、全てAdministratorが実行した操作として判断されます。
STEP3 Shift-JISでCSVファイルにエクスポートする
データをコマンドライン上で表示するだけでなく、次はファイルにエクスポートしてみます。諸事情（*後述）によりここではAPIトークンを利用しています。
kintoneではデフォルトでUTF-8で文字列データがエクスポートされるので、それ以外の文字コードでエクスポートしたい場合は-eオプションを利用します。
ここではsample.csvというファイルにShift-JIS形式でエクスポートします。
※エクスポート先のディレクトリを指定せずにCSVにエクスポートすると、コマンドラインツールの実行ファイルを置いたディレクトリに保存されます。
Cドライブ直下などに実行ファイルを置いているとシステム管理権限の影響で「アクセス拒否されました」とエラーが出る可能性があります。
その場合は、必ずエクスポート先のディレクトリのパスを指定してください。
▼実行ファイルを置いたディレクトリにそのまま保存
▼ディレクトリを指定して保存（ここではデスクトップに保存）
*ユーザー認証でデータをCSVにエクスポートしようとすると、パスワード要求がされず「あれれ？」となると思います。
要求はされないもののコマンド上でパスワード入力すると、データとともに「Password」という文字列がCSVにエクスポートされます。
そもそもの説明をすると、「コマンド＞ファイルのパス」という書き方をファイルのリダイレクトと言うのですが、これはコマンドラインへの出力内容をファイルにエクスポートするという処理になります。
なのでデータとともにPasswordという文字列もエクスポートされるのです。
基本的にはファイルへのエクスポートという操作は、バッチ処理（自動実行）を想定したものなので、その場合は認証オプションの後ろに続けて-p オプションでパスワード指定してエクスポートするようにしてください。
STEP4 エクスポートするフィールドを指定する
さらに-cオプションを使うと、エクスポートするフィールドを指定することができるので、やってみます。ここでは$idと会社名と担当者名のみエクスポートします。
書き方としては、「-c "書き出したいフィールドコード"」になります。
※フィールド名ではなく、フィールドコードで指定します。ここよく間違うので注意ポイントです！
STEP5 絞り込み条件と並び順を指定する
-qオプションを使うことで、絞り込み条件と並び順を指定できます。条件式の書き方はこちらを参照してください。
ここでは、部署名が「営業部」のレコードの$idと会社名と担当者名と部署名を、レコード番号降順でエクスポートします。
クエリ指定箇所のエスケープ処理も忘れずに！
STEP6 テーブルのデータはどのような形式で表示されるのか確認する
最後にテーブル付きのレコードデータはどのように表示されるのか見てみます。慣れれば大丈夫ですが、少し見方がややこしいので要注意です。
ここでは以下の交通費申請アプリを利用しています。
3件ほどデータを登録してコマンドラインツールで表示してみます。
CSVファイルのエクスポート結果は以下になります。
CSVでどのフィールドがどこに対応しているのか見にくい場合は、Excelファイルで開いて見てください。
ここから見方の解説です。
書き出したCSVの1行目には１列目に"*"マークが出力され、その後フィールドコード名が並びます。2行目以降で"*"マークがついていない行は、テーブル内の２行目以降のデータになります。
上記のCSVデータの場合、3レコードがエクスポートされています。レコード番号1番のテーブル内に4行分、レコード番号2番のテーブル内に3行分のデータが入っているため、CSVでもそれぞれその行数分のデータがエクスポートされています。
実際に登録しているデータは以下になります。考えるときの参考にしてみてください。
また、テーブルを含むレコードの登録については「第2回 レコードの登録・削除をしてみよう」で、
テーブルを含むレコードの更新については「第3回 レコードの更新をしてみよう」で詳しく解説していきます。
第1回、無事最後まで完走できましたでしょうか？今回はここら辺で！次回はデータの追加と削除をやっていきます。お楽しみに＾＾
このTipsは、cli-kintone Ver 0.10.2 と2020年3月版 kintone で確認したものになります。
コマンドラインツールを商用利用したいと考えております。
＞商用利用等は、ライセンスに従ってご利用可能です
→上記の”ライセンスに従って”とは、具体的に何を指しますでしょうか？
(お客様がスタンダードライセンスの契約であれば利用可能との理解で宜しいでしょうか？)
Kenji Narizuka 様
商用利用の件は、https://cybozudev.zendesk.com/hc/ja/articles/202708214 にありますとおり、GPL v2となっております。
著作権の表示をいただくことなどを条件として、商用利用、修正、再配布可能となっております。
お客様の個々の状況の場合についてご不明な点がありましたら、外部サイトですがこちらのFAQが参考になるかと思います。
またご不明な点がありましたらご連絡ください。よろしくお願いいたします。
ご回答頂きありがとうございました。
上記内容について、承知致しました。
上記に
※コマンドラインツールは、動作を保証するものではありません。
と記述がありますが、お客様（商用）にて運用しておりますが
トラブルがあった場合、問合せすることは可能なのでしょうか？
小山剛司さん
ご質問いただきありがとうございます。cybozu developer network運営チームです。
現在運用環境での動作保証はしておりませんが、何か不具合があった場合はご連絡ください。
対応検討をさせていただきます。
よろしくお願い致します。
いつも大変お世話になっております。
エクスポートについてお聞きしたいことがあります。
前に0がついている数値をCSVファイルに書き出したいのですが上手く行きません。
エクセルの表示の仕方が原因だと分かりましたが、コマンドラインツール内で表示形式を変える事は出来ますか?
(0の数値があった場合、前にシングルコーテーションが入る等)
回答のほどよろしくお願いします。
風早様
CSV出力後エクセルで開いたら、頭のゼロが消えてしまった、ということでしょうか。
こちらの回答が参考になるかもしれません。ご確認ください。
https://developer.cybozu.io/hc/ja/community/posts/115019817883/comments/115005135126
cybozu Development team様
回答ありがとうございます。
リンクの先を見させてもらいました。
私がやりたい事はその事であっているのですが、
どうしてもひと手間掛かってしまうのでそれを無くしたいです。
風早様
コマンドラインツールでは、一般的なCSV形式での出力のみ対応しております。
そのため、エクセルの表示仕様を考慮した形のエクスポート機能（数値の前にシングルコーテーションを入れる等）はございません。
cybozu Development team様
そういう事なのですね 承知致しました。
回答ありがとうございました。
cybozu Development team 担当者様
下記３点についてご教授願います。
１．「-c」で抽出したいフィールドを指定しているのですが上限値はありますでしょうか。
２．上記説明のSTEP3は「エクスポートするフィールド名をカンマ区切りで指定できます。」と記述されていますが、
STEP4では「-c "書き出したいフィールドコード"」となっています。指定はフィールドコードで間違いないでしょうか。
３．「-c」でフィールドコードを任意で指定してエクスポートをしているのですが、一部のフィールドしか取得できません。
全フィールドが取得できない理由などなにか考えられるものはありますでしょうか。
「-c」の指定をしなければ全フィールドのデータを取得できています。
SIONさん
ご質問ありがとうございます。回答させていただきます。
※ レコード取得APIの制限により
表記ズレがある部分は順次修正対応させていただきます。
ご指摘ありがとうございました。
以下の制限事項をご確認ください。それ以外で取得できないフィールドがありましたらお知らせください。
制限事項などは、こちらに記載していますので、ご参照ください。
https://github.com/kintone/cli-kintone/blob/master/README.md
Created by, Created datetime, Updated by, Updated datetime, Blank space, Label, Border.
質問させて頂きます。
CSVでのエクスポートを試してみたのですが、カラムの内容が一部のレコードだけ前詰めされます。
前詰めされるレコードに値が入っていても前詰めされます。
カラム指定をした場合としない場合と両方試しましたが変わりません。
画面から「ファイルに書き出す」を行った場合は発生しません
起きている現象は下記のようなイメージです。
No 問い合わせ内容 ステータス
1 ●●はどこで買えますか？ 完了
2 ■■の使い方を教えてください 対応中
3 対応中 ← 「問い合わせ内容」の値が入っていても「ステータス」の値が入る
kintone_user70630様
こちらの現象は再現できなかったため、お手数ですが詳細の情報をいただけますでしょうか。
必要に応じて情報にマスクしていただいて結構ですので、可能な限りでお願いいたします。
よろしくお願いいたします。
cybozu Development team様、現在コマンドラインツールを使って色々動作の確認を行っております。
一点質問です。このツールを使うとエキスポートする度にCSVの項目の順番が変わってしまうのですが、これは仕様でしょうか？それとも
何かしらの方法で順番固定する事は可能でしょうか？
ichiro uozu 様
お世話になっております。
cybozu developer network 運営局です。
-c オプションを利用すると、エクスポートするフィールドを指定できるため、CSV 項目の順序を担保できるかと思います。
よろしくお願いいたします。
> 必要に応じて情報にマスクしていただいて結構ですので、可能な限りでお願いいたします。
手順といっても下記内容のみです。
cd 指定のフォルダ
cli-kintone.exe -a アプリNo -d ドメイン -t トークン -e sjis > unspecified.csv
Windows10と7の2台で試しましたが、結果は同じでした。
別のアプリだと発生しませんでした。
★前付めされるデータと正常データをテキストで比較して見ると、ダブルクォーテーションの位置が定まっていませんでした。
データの問題なのでしょうが、なぜ発生するのか思い当たることがなく困っています。確認すべき事項があればご教授頂けますと幸いです。
kintone_user72630 様
情報をありがとうございます。
他のアプリでは発生しないということで、アプリのデータに原因があると思われます。
以下の点もご確認いただけますでしょうか。
初歩的な質問で失礼します。
mac版をダウンロードし、macのターミナルで使用する場合、
cdコマンドで、cli-kintoneを置いたディレクトリに移動したあと、
次に引数を何も指定せずに実行しても、
$ cli-kintone
-bash: cli-kintone: command not found
となってしまいます。
ご教示いただいてもよろしいでしょうか。
grezou 様
お世話になっております。
cybozu developer network 運営局でございます。
mac OS をご利用の方は、ダウンロード頂いた「cli-kintone」へパスを通していただく必要があります。
bash_profile などに cli-kintone が保存されているディレクトリへパスを通していただければ、cli-kintone コマンドが実行可能になります。
以上、よろしくお願い致します。
cybozu developer network 運営局様
お返事ありがとうございます。パスを通すことで、無事に実行可能になりました。
パスを通すやり方は、以下のページを参考にしました。
https://qiita.com/nbkn/items/01a11392921119fa0153
取り急ぎ、お礼申し上げます。
お世話になっております。
コマンドラインツールを利用して、ユーザー選択フィールド情報を取得時に
表示名などを取得したいのですが、可能でしょうか？
検索する限り見つけられず。。。ご教授いただけると助かります。
よろしくお願いします。
ここっこ 様
お世話になっております。
cybozu developer network 運営局でございます。
ご認識のとおり、cli-kintoneではユーザーの表示はユーザーコードのみとなっております。
表示名などを取得したい場合は、cli-kintoneで出力したデータに対してユーザーAPIを利用したり、レコード保存時に表示名も保存するなどの方法が考えられますのでご検討ください。
その際の技術的なご質問はcybozu developer コミュニティをぜひご活用ください。
cybozu developer network 運営局様
回答ありがとうございます。
ユーザーAPIの利用にて検討します。
ありがとうございました。
cli-kintoneコマンドラインツールを使い、レコード出力ではなく、Microsoft/officeのACCESSにある関数「Dcount」のように
レコード件数だけ出力する機能はありますでしょうか？
レコードの内容まで必要とせず、件数だけが必要という需要は聞かないでしょうか？
今回、たまたま、その需要がありました。
もし、無いようあれば、検討の余地はありませんでしょうか？
芹田 邦浩 様
お世話になっております。cybozu developer network です。
cli-kintone では、レコード件数のみ出力できる機能はございません。
REST API を直接実行する方法であれば、
レコードの一括取得（クエリで条件を指定） API を使ってレコード件数を取得できるので、ご検討ください。
また「レコード件数のみを取得できる」ご要望については、担当部署に申し伝えます。
よろしくお願いいたします。
お世話になっております。
cli-kintoneを使い、(CSVではなく)Excelファイルのインポートを試みておりますが、うまくいきません。
ちなみに、一度CSVに変換したもののインポートできております。(ただ元がExcelなので、毎回変換する手間を省きたいです)
過去にも同様の質問があったかもしれませんが、ご教授いただけると幸いです。
よろしくお願いいたします。
Chishima様
お世話になっております。cybozu developer network です。
kintoneのインポート画面とはちがい、
cli-kintoneでのインポートはCSVのみとなっております。
お手数ではありますが、Excelからの場合は一度CSVに変換いただく必要があります。
よろしくお願いいたします。
cybozu developer network 運営局様
理解いたしました。
回答ありがとうございました。
サブテーブルのデータをコマンドラインツールでcsv をインポートして追加しようと思っています。
現状でサブテーブル内にはデータは存在していません。
行番号の指定など、うまくできていないのですが、それらの操作についてどこを見ればよいでしょうか？