このチュートリアルはver. 0.x.xのcli-kintoneの使い方を紹介しています。
ver.1.0.0以降のcli-kintoneの使い方を紹介するチュートリアルは次のページを参照してください。
はじめよう cli-kintone
はじめに
kintoneではExcel/CSVを使ってデータの インポート や エクスポート ができますが、コマンドラインからも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)
からダウンロードできます。
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」を指しているので、コマンドの意味を覚えておくといいですね!
|
|
他にもこの先知らないコマンドが出てくるかもしれないですが、そんなときは検索して調べてみてください。
次に引数を何も指定せずに実行すると、コマンドラインツールで利用可能なオプションが表示されます。
オプションの詳細は
kintone コマンドラインツール(v0)の使い方を参照してください。
mac OSをご利用の方は、cli-kintoneコマンドを実行する前に、ダウンロードした「cli-kintone」へパスを通していただく必要があります。
.bash_profile
などにcli-kintoneが保存されているディレクトリーへパスを通していただければ、cli-kintoneコマンドが実行可能になります。
この後、上記のオプションを利用して各種操作をしていきます。
コマンドラインツールを利用する際は、常に最新のバージョンを使うことをおすすめします。
なお、セキュアアクセス環境には対応していません。
データの取得
この後のシリーズでは、データの追加/削除/更新などの処理についても紹介しますが、第1回は「データの取得」を試してみたいと思います。
その前にデータを取得するアプリを用意してください。
ここでは
アプリストア
にある
顧客リストアプリ
を利用します。
デモデータも数件入れておきます。
あとから分かりやすいようにフィールドコードも英数に修正しておきましょう。
アプリの準備ができたら、上述のオプションを利用してデータを取得します。
パターンがいくつかあるので、順に紹介していきます。
STEP1 ユーザー名とパスワードで kintone のデータを表示する
ドメイン名が「sample.cybozu.com」でアプリIDが「777」、ログイン名が「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トークンの権限を設定します。
APIトークン認証を使った場合は、すべてAdministratorが実行した操作として判断されます。
|
|
STEP3 Shift-JIS で CSV ファイルにエクスポートする
データをコマンドライン上で表示するだけでなく、次はファイルにエクスポートしてみます。
諸事情(後述)によりここではAPIトークンを利用しています。
kintoneでは、指定しない限りUTF-8で文字列データがエクスポートされます。
それ以外の文字コードでエクスポートしたい場合は-e
オプションを利用します。
ここでは「sample.csv」というファイルにShift-JIS形式でエクスポートします。
エクスポート先のディレクトリーを指定せずCSVにエクスポートすると、コマンドラインツールの実行ファイルを置いたディレクトリーに保存されます。
Cドライブ直下などに実行ファイルを置いていると、システム管理権限の影響で「アクセス拒否されました」というエラーが発生します。
その場合は、必ずエクスポート先のディレクトリーのパスを指定してください。
実行ファイルを置いたディレクトリーにそのまま保存
|
|
ディレクトリーを指定して保存(ここではデスクトップに保存)
|
|
API トークンを使用する理由
ユーザー認証でデータをCSVにエクスポートすると、パスワードを要求するメッセージが表示されません。
要求はされないもののコマンド上でパスワード入力すると、データとともに「Password」という文字列がCSVにエクスポートされます。
「コマンド > ファイルのパス」という書き方をファイルのリダイレクトといいます。
これはコマンドライン(コマンドプロンプト)への出力内容をファイルにエクスポートするという処理です。
なのでデータとともにPasswordという文字列もエクスポートされるのです。
基本的にはファイルへのエクスポートという操作は、バッチ処理(自動実行)を想定したものなので、その場合は認証オプションの後ろに続けて-p
オプションでパスワード指定してエクスポートするようにしてください。
STEP4 エクスポートするフィールドを指定する
さらに-c
オプションを使うと、エクスポートするフィールドを指定できるので、やってみます。
ここでは $idと会社名と担当者名のみエクスポートします。
書き方としては、-c "書き出したいフィールドコード"
になります。
フィールド名ではなく、フィールドコードで指定します。
ここよく間違うので注意ポイントです!
STEP5 絞り込み条件と並び順を指定する
-q
オプションを使うことで、絞り込み条件と並び順を指定できます。
条件式の書き方は
クエリの書き方を参照してください。
ここでは、部署名が「営業部」のレコードの $idと会社名と担当者名と部署名を、レコード番号降順でエクスポートします。
クエリ指定箇所のエスケープ処理も忘れずに!
STEP6 テーブルのデータはどのような形式で表示されるのか確認する
最後にテーブル付きのレコードデータはどのように表示されるのか見てみます。
慣れれば大丈夫ですが、少し見方がややこしいので要注意です。
ここでは以下の
交通費申請アプリ
を利用しています。
3件ほどデータを登録してコマンドラインツールで表示してみます。
|
|
CSVファイルのエクスポート結果は以下になります。
|
|
CSVでどのフィールドがどこに対応しているのか見にくい場合は、Excelファイルで開いて見てください。
ここから見方の解説です。
書き出したCSVの1行目には1列目に「*」マークが出力され、その後にフィールドコード名が並びます。
2行目以降で「*」マークがついていない行は、テーブル内の2行目以降のデータになります。
上記のCSVデータの場合、3レコードがエクスポートされています。
レコード番号一番テーブル内に4行分、レコード番号2番のテーブル内に3行分のデータが入っているため、CSVでもそれぞれその行数分のデータがエクスポートされています。
実際に登録しているデータは以下になります。
考えるときの参考にしてみてください。
また、テーブルの操作は次回以降の記事で詳しく解説します。
- テーブルを含むレコードの登録: 第 2 回 レコードの登録・削除をしてみよう
- テーブルを含むレコードの更新: 第 3 回 レコードの更新をしてみよう
まとめ
第1回、無事最後まで完走できましたでしょうか?
次回はデータの追加と削除をやっていきます。
このTipsは、cli-kintone Ver 0.10.2と2020年3月版kintoneで動作を確認しています。