第 1 回 kintone コマンドラインツール(cli-kintone v0)を使ってみよう!

著者名:三宅 智子(サイボウズ株式会社)

目次

information

このチュートリアルは ver. 0.x.x の cli-kintone の使い方を紹介しています。
ver.1.0.0 以降の cli-kintone の使い方を紹介するチュートリアルは次のページを参照してください。
はじめよう cli-kintone

はじめに

kintone では Excel/CSV を使ってデータの インポート (External link) エクスポート (External link) ができますが、コマンドラインからも CSV ファイルを使って同様なことができます!

kintone コマンドラインツール とは、簡単にコマンドライン上から kintone にデータのインポート・エクスポートをできるようにしたツールのことです。
なお、コマンドラインは CSV ファイルのみ対応しています。

「はじめよう kintone コマンドラインツール」では、以下のような方向けに、基本的な操作方法や活用方法を紹介していきます。

  • エクセルなどと連携させたいけど、プログラミング少し苦手という方
  • コマンドラインでのデータのインポートやエクスポートをしたいという初心者の方

通常の CSV のデータ入出力ではできないことも、こちらのコマンドラインツールを使えばできる!なんてこともあったりします。

初回は、まず「環境設定」と「レコードデータの取得」というテーマでお届けします。

環境の準備

kintone のコマンドラインツールを利用するにあたり、まずは下準備です。
OS は Windows/Linux/Mac OS X の 3 種類での動作を確認しています。
本シリーズでは、Windows の利用を想定して記事を書いています。

コマンドラインツールのダウンロードと基本的な使い方については以下で紹介しています。

それではさっそく環境設定に移っていきましょう!

注意事項

  • コマンドラインツールは、動作を保証するものではありません。
  • ソースコードの変更および再配布、商用利用等はライセンスにしたがってご利用可能です。

STEP1 ツールをダウンロードする

kintone コマンドラインツールの動作 OS やダウンロード用のツールについては kintone コマンドラインツール(cli-kintone v0) に記載があるので、まずはそちらを確認します。

kintone コマンドラインツールは Releases kintone/cli-kintone (Github) (External link) からダウンロードできます。
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 の場合、「Windows キー」+「R キー」で下の「ファイル名を指定して実行」画面を立ち上げて、名前欄に「cmd」と入力します。
OK をクリックするとコマンドプロンプトが立ち上がります。
Mac の場合は、ターミナルというアプリケーションを起動します。

STEP3 コマンドラインツールを実行する

cd コマンドで、cli-kintone.exe を置いたディレクトリーに移動します。
ディレクトリーはフォルダーと同義で、以下ディレクトリーと表記します。
次のコマンドを入力して実行すると、指定したディレクトリーに移動してくれます。
cd は「Change Directory」を指しているので、コマンドの意味を覚えておくといいですね!

1
cd <スペース> <exeファイルを置いたディレクトリ>

他にもこの先知らないコマンドが出てくるかもしれないですが、そんなときは検索して調べてみてください。
次に引数を何も指定せずに実行すると、コマンドラインツールで利用可能なオプションが表示されます。
オプションの詳細は kintone コマンドラインツール(v0)の使い方 を参照してください。

mac OS をご利用の方は、cli-kintone コマンドを実行する前に、ダウンロードした「cli-kintone」へパスを通していただく必要があります。
.bash_profile などに cli-kintone が保存されているディレクトリーへパスを通していただければ、cli-kintone コマンドが実行可能になります。

この後、上記のオプションを利用して各種操作をしていきます。

コマンドラインツールを利用する際は、常に最新のバージョンを使うことをおすすめします。
なお、セキュアアクセス環境には対応していません。

データの取得

この後のシリーズでは、データの追加/削除/更新などの処理についても紹介しますが、第 1 回は「データの取得」を試してみたいと思います。

その前にデータを取得するアプリを用意してください。
ここでは アプリストア (External link) にある 顧客リストアプリ (External link) を利用します。

デモデータも数件入れておきます。
あとから分かりやすいようにフィールドコードも英数に修正しておきましょう。

アプリの準備ができたら、上述のオプションを利用してデータを取得します。
パターンがいくつかあるので、順に紹介していきます。

STEP1 ユーザー名とパスワードで kintone のデータを表示する

ドメイン名が「sample.cybozu.com」でアプリ ID が「777」、ログイン名が「myname」の場合の例です。

1
2
>cli-kintone.exe --export -a 777 -d sample -u myname
Password:

ユーザーのパスワードを入力すると、以下のように CSV 形式ですべてのフィールドのデータがエクスポートされます。
セキュリティ保護のため、パスワードを入力してもコマンドライン上には何も見えないようになっています。

kintone.com や cybozu.cn のドメインを指定する場合は、「sample」だけでなく、「sample.kintone.com」「sample.cybozu.cn」のように FQDN (External link) を指定するようにしてください。

1
2
3
4
5
6
"$id","$revision","Attachment","lat","Zipcode","Address","Department","Name","Mail","Other","number","Fax","lng","Company","Tel"
"5","3","small_star4_pink.png","35.3748","1234345","東京都江東区有明3-11-1","営業部","三宅 友助","miyake@cybou.co.jp","テスト","5","03-5678-5678","139.4737","サイボー株式会社","03-1234-1234"
"4","3","small_star6_orange.png","35.372","1350064","東京都江東区青海2-5-10","販売部","末宗 秀雄","suemune@asahi.co.jp","テスト","4","03-5678-5680","139.4649","朝日商事","03-1234-1236"
"3","3","small_star7_yellow.png","35.3740","1350091","東京都港区台場1-7-1","総務部","長田 助勝","nagata@akamatasu.co.jp","テスト","3","03-5678-5679","139.4625","赤松機械","03-1234-1235"
"2","3","small_star1_blue.png","35.3748","1350063","東京都江東区有明3-11-1","営業部","友岡 春夫","tomooka@aoki.co.jp","テスト","2","03-5678-5678","139.4737","青木建設","03-1234-1234"
"1","4","small_star5_purple.png","35.3748","1350065","東京都江東区有明3-11-1","営業部","俊成 たくと","toshinari@aoyama.co.jp","テスト","1","03-5678-5678","139.47.37","青山建設","03-1234-1234"

1 行目にはフィールド名ではなく、フィールドコードがエクスポートされます。

JSON 形式で表示するには、認証オプションの後ろに続けて -o json を指定します。
他のサービスにデータを受け渡したい時などは、JSON 形式のデータを利用するケースが多いです。

途中で処理を中断したい場合は、CTRL+C を押してください。

STEP2 APIトークンを利用してkintoneのデータを表示する

API トークンを利用すると、パスワードを入力しなくてもデータをインポート・エクスポートできます。
API トークンを使うメリットには以下があります。

  • ユーザー認証が必要ない。
  • 限られたアプリのみ操作できる。
  • 実行できる操作を制限できる。

API トークンの生成方法は API トークンを生成する (External link) を参照してください。
実行したい操作に合わせて、API トークンの権限を設定します。
API トークン認証を使った場合は、すべて Administrator が実行した操作として判断されます。

1
>cli-kintone.exe --export -a <アプリID> -d <ドメイン名> -t <APIトークン>

STEP3 Shift-JIS で CSV ファイルにエクスポートする

データをコマンドライン上で表示するだけでなく、次はファイルにエクスポートしてみます。
諸事情(後述)によりここでは API トークンを利用しています。

kintone ではデフォルトで UTF-8 で文字列データがエクスポートされるので、それ以外の文字コードでエクスポートしたい場合は -e オプションを利用します。
ここでは「sample.csv」というファイルに Shift-JIS 形式でエクスポートします。

エクスポート先のディレクトリーを指定せず CSV にエクスポートすると、コマンドラインツールの実行ファイルを置いたディレクトリーに保存されます。
C ドライブ直下などに実行ファイルを置いていると、システム管理権限の影響で「アクセス拒否されました」というエラーが発生します。
その場合は、必ずエクスポート先のディレクトリーのパスを指定してください。

実行ファイルを置いたディレクトリーにそのまま保存
1
>cli-kintone.exe --export -a <アプリID> -d <ドメイン名> -t <APIトークン> -e sjis > sample.csv
ディレクトリーを指定して保存(ここではデスクトップに保存)
1
>cli-kintone.exe --export -a <アプリID> -d <ドメイン名> -t <APIトークン> -e sjis > C:\Users\Desktop\sample.csv
API トークンを使用する理由

ユーザー認証でデータを CSV にエクスポートすると、パスワードを要求するメッセージが表示されません。
要求はされないもののコマンド上でパスワード入力すると、データとともに「Password」という文字列が CSV にエクスポートされます。

「コマンド > ファイルのパス」という書き方をファイルのリダイレクトといいます。
これはコマンドライン(コマンドプロンプト)への出力内容をファイルにエクスポートするという処理です。
なのでデータとともに Password という文字列もエクスポートされるのです。
基本的にはファイルへのエクスポートという操作は、バッチ処理(自動実行)を想定したものなので、その場合は認証オプションの後ろに続けて -p オプションでパスワード指定してエクスポートするようにしてください。

STEP4 エクスポートするフィールドを指定する

さらに -c オプションを使うと、エクスポートするフィールドを指定できるので、やってみます。
ここでは $id と会社名と担当者名のみエクスポートします。
書き方としては、-c "書き出したいフィールドコード" になります。
フィールド名ではなく、フィールドコードで指定します。
ここよく間違うので注意ポイントです!

STEP5 絞り込み条件と並び順を指定する

-q オプションを使うことで、絞り込み条件と並び順を指定できます。
条件式の書き方は クエリの書き方 を参照してください。
ここでは、部署名が「営業部」のレコードの $id と会社名と担当者名と部署名を、レコード番号降順でエクスポートします。
クエリ指定箇所のエスケープ処理も忘れずに!

STEP6 テーブルのデータはどのような形式で表示されるのか確認する

最後にテーブル付きのレコードデータはどのように表示されるのか見てみます。
慣れれば大丈夫ですが、少し見方がややこしいので要注意です。
ここでは以下の 交通費申請アプリ (External link) を利用しています。

3 件ほどデータを登録してコマンドラインツールで表示してみます。

1
>cli-kintone.exe --export -a <アプリID> -d <ドメイン名> -t <APIトークン> -e sjis > C:\Users\Desktop\sample.csv

CSV ファイルのエクスポート結果は以下になります。

1
2
3
4
5
6
7
8
9
*,"$id","$revision","Title","Sum","Other","Date","Place","transportation","Price","Applicant","Number","Department","Authorizer"
*,"3","1","3月分交通費","","テスト","2017-01-24","","","","tomoko","777","営業部","sato"
*,"2","1","2月分交通費","1200","テスト","2017-02-08","サイボー株式会社","電車(往復)","400","tomoko","777","営業部","sato"
,"2","1","2月分交通費","1200","テスト","2017-02-24","株式会社さぼー","バス(往復)","500","tomoko","777","営業部","sato"
,"2","1","2月分交通費","1200","テスト","2017-02-27","サイボウズ株式会社","電車(往復)","300","tomoko","777","営業部","sato"
*,"1","3","1月分交通費","31700","テスト","2017-01-18","コココ株式会社","電車(往復)","400","tomoko","777","営業部","saki"
,"1","3","1月分交通費","31700","テスト","2017-01-25","九州株式会社","飛行機(往復)","30000","tomoko","777","営業部","saki"
,"1","3","1月分交通費","31700","テスト","2017-01-30","ららら株式会社","電車(往復)","300","tomoko","777","営業部","saki"
,"1","3","1月分交通費","31700","テスト","2017-01-31","株式会社おおお","タクシー","1000","tomoko","777","営業部","saki"

CSV でどのフィールドがどこに対応しているのか見にくい場合は、Excel ファイルで開いて見てください。

ここから見方の解説です。

書き出した CSV の 1 行目には 1 列目に「*」マークが出力され、その後にフィールドコード名が並びます。
2 行目以降で「*」マークがついていない行は、テーブル内の 2 行目以降のデータになります。
上記の CSV データの場合、3 レコードがエクスポートされています。
レコード番号一番テーブル内に 4 行分、レコード番号 2 番のテーブル内に 3 行分のデータが入っているため、CSV でもそれぞれその行数分のデータがエクスポートされています。

実際に登録しているデータは以下になります。
考えるときの参考にしてみてください。

また、テーブルの操作は次回以降の記事で詳しく解説します。

まとめ

第 1 回、無事最後まで完走できましたでしょうか?
次回はデータの追加と削除をやっていきます。

information

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