環境
- macOS 10.15.7
説明
cli-kintoneは、kintoneアプリのデータをファイルに入出力することができるコマンドラインツールです。
Windows、Linux、Mac OS X 版があります。
https://github.com/kintone/cli-kintone
Zipファイルを解凍後に、実行ファイルをパスの通ったディレクトリに設置します。
コマンドラインから cli-kintone を打ち込んで Usage が表示されることを確認します。
日本語解説
https://developer.cybozu.io/hc/ja/articles/202957070
英語解説
https://developer.kintone.io/hc/en-us/articles/115002614853
cli-kintoneは Go言語で書かれています。ソースから実行ファイルを生成することも出来ます。
オプション一覧
Usage
Usage:
cli-kintone [OPTIONS]
Application Options:
-d= Domain name (specify the FQDN) 必須。cybozuのドメインを指定します。例) -d sample
-a= App ID (default: 0) （必須）アプリのIDを指定します。例) -a 123
-u= User's log in name （準必須）kintoneにアクセスする際にログインパスワードを使うときに指定 例) -u user
-p= User's password（準必須）kintoneにアクセスする際にログインパスワードを使うときに指定 例) -p password
-t= API token（準必須）kintoneにアクセスする際にAPIトークンを使うときに指定 例) -t APIToken
-g= Guest Space ID (default: 0) （任意）kintoneのゲストスペースにアクセスする場合に指定
-o= Output format. Specify either 'json' or 'csv' (default: csv) （任意）出力形式を指定。省略時はCSVです。
-e= Character encoding. Specify one of the following -> 'utf-8'(default), 'utf-16', 'utf-16be-with-signature', 'utf-16le-with-signature', 'sjis' or
'euc-jp' (default: utf-8)（任意）出力形式の文字コードを指定。デフォルトはUTF-8です。--import -f でファイルから読み込んでレコードを追加・編集時は読み込み用のファイルの文字コードを指定します。（例：Shift-JISコードのファイルを読み込む場合。 --import -f import.csv -e sjis）
-U= Basic authentication user name （任意）アクセスするkintoneドメインにBASIC認証が設定されている場合に指定。パスワードとセットで使う。
-P= Basic authentication password（任意）アクセスするkintoneドメインにBASIC認証が設定されている場合に指定。ユーザー名とセットで使う。
-q= Query string （任意）アプリに渡すクエリ文字列。SQLライクな検索絞り込みが出来ます。例) -q "limit 10"
-c= Fields to export (comma separated). Specify the field code name （任意）出力する際のフィールドコードをカンマ区切りで指定。省略した場合は全てのフィールドが出力されます。例) -c "$id,文字列1行"
-f= Input file path（任意）CSVファイル等からレコードを追加・更新する場合にファイル名を指定。例) -f ./import.csv
-b= Attachment file directory （任意）添付ファイルをダウンロードする場合に、ダウンロードするディレクトリを指定。ディレクトリは自動作成される。
-D Delete records before insert. You can specify the deleting record condition by option "-q"（任意）レコードを削除する場合に指定。-q オプションを組み合わせて、クエリで絞り込んだ特定のレコードを削除することができる。
-l= Position index of data in the input file (default: 1) （任意）インポートするファイルの読み込み位置を指定することができる。
--import Import data from stdin. If "-f" is also specified, data is imported from the file instead（任意）指定すると標準入力からデータを読み込む。
--export Export kintone data to stdout（任意）指定すると標準出力にレコードを出力する。
Help Options:（任意）cli-kintoneのオプションを表示する。
-h, --help Show this help message
実行例
テスト環境は macOS 10.13.6
レコード取得系
APIトークンを使って最初の10行をCSVで取得する
cli-kintone -a 123 -t API-Token -d Domain -q "limit 10"
APIトークンを使って全てのレコードをCSVでバックアップする
cli-kintone -a 123 -t API-Token -d Domain > backup.csv
Mac OS X にてファイルを確認する
head backup.csv ファイルの先頭から10行表示
tail backup.csv ファイルの最後から10行表示
フィールドコードを指定して標準出力する
cli-kintone -a 123 -t API-Token -d Domain -c "\$id, 顧客名, 提案プラン2, オプション2"
レコードIDのみをCSVで取得する
cli-kintone -a 123 -t API-Token -d Domain -c '$id'
または、ダブルクォーテーションで囲む場合は、$をバックスラッシュでエスケイプする。
cli-kintone -a 123 -t API-Token -d Domain -c "\$id"
シェルのパイプと組み合わせて、ヘッダー行のみを取得する
cli-kintone -a 123 -t API-Token -d Domain | head -1
レコード更新系
シェルのパイプと組み合わせて、新規に追加した自動計算フィールドを更新する
自動計算フィールドを後で追加した場合、レコードの再保存を繰り返す事無く一気に更新を掛けます。
cli-kintone -a 123 -t API-Token -d Domain -c "\$id" | cli-kintone --import -a 123 -t API-Token -d Domain
ファイルを読み込んでフィールドを更新（重複禁止フィールドをキーに指定）
更新用のCSVファイル
キーにするフィールドコードにアスタリスク(*)を付けています。
ファイルの文字コードはShift-JISの場合です。
"*顧客コード","引き合い"
"20","電話"
"19",""
"18","メルマガ"
"17",""
"16",""
cli-kintone --import -f import.csv -e sjis -a 123 -t API-Token -d sample.cybozu.com
レコード追加系
ルックアップフィールドを持つアプリにレコードを追加する
ルックアップフィールドには(2019.10.16 現在)APIトークン認証ではレコードの追加・更新ができません。この場合はパスワード認証を使います。
営業支援パックの「案件管理」にレコードを追加します。
フィールドコード顧客名がルックアップ、案件名が必須項目です。
"顧客名","案件名"
"戸田ネットソリューションズ","新規案件1"
"金都運総研","新規案件2"
cli-kintone --import -a 123 -u 'userid' -p 'password' -d Domain -f ./importfile.csv
: Start from lines: 1 - 3 => SUCCESS
: DONE
データマイグレーション時の cli-kintone の使いどころ
cli-kintone を使わなくても良い場面も多い訳で、使わざるを得ない場面で利用することになります。
- 既存のkintoneアプリの一部のフィールドを他のアプリに移行したいが、フィールド名が全て同じの為移行したフィールドの区別が付かない。
こんな時は cli-kintone を使ってフィールドコードを指定してCSV出力した方が早いです。
フィールド名を変更しても良いですが、同じフィールド名で100個とかあったらムリだと思います。
cli-kintone -a 123 -t API-Token -d Domain -c "\$id, 顧客名, 提案プラン2, オプション2"
-c オプションに「出力する際のフィールドコードをカンマ区切りで指定」してやりましょう。
通知について
アプリにてファイル書き出し・読み込みした際は、ユーザーに通知が飛びます。
https://jp.cybozu.help/k/ja/user/notifications/notification_type.html
対して、cli-kintone 等による、API経由のファイル書き出し・読み込みは通知が飛びません。ただし、kintoneシステム管理で REST APIの通知をメールで送信 にチェックしている場合は、メールにて通知がされます。
また、API操作に関しては、cybozu.com運用基盤の監査ログに書き込まれます。
備考
ルックアップの更新にAPIトークン認証が使えない理由
kintoneの APIトークン はアプリ単位の払い出しになっています。
想像ですが、ルックアップはルックアップ元とルックアップ先（更新するアプリ）の少なくとも2つのAPIトークンが必要な為と思われます。
(2019.10.16現在)
おまけ
mac のターミナルで Shift-JIS のファイルを cat する
$ cat sjis.csv
"*�ڋq�R�[�h","��������"
"20","�d�b"
"19",""
"18","�����}�K"
普通にcat すると文字化けするので、nkf で変換します。
$ nkf -v
Network Kanji Filter Version 2.1.5 (2018-12-15)
Copyright (C) 1987, FUJITSU LTD. (I.Ichikawa).
Copyright (C) 1996-2018, The nkf Project.
$ nkf --help
Usage: nkf -[flags] [--] [in file] .. [out file for -O flag]
j/s/e/w Specify output encoding ISO-2022-JP, Shift_JIS, EUC-JP
UTF options is -w[8[0],{16,32}[{B,L}[0]]]
J/S/E/W Specify input encoding ISO-2022-JP, Shift_JIS, EUC-JP
UTF option is -W[8,[16,32][B,L]]
$ cat ./csv/sjis.csv | nkf -Sw
"*顧客コード","引き合い"
"20","電話"
"19",""
"18","メルマガ"
cli-kintone に渡すオプションをあらかじめ環境変数にセットする
シェルの環境変数にオプションパラメーターをセットしておきます。
$ app=100
$ echo $app
100
$ APIToken=APIトークン
$ kintoneDomain=sample.cybozu.com
cli-kintone -a ${app} -t ${APIToken} -d ${kintoneDomain} -q "limit 10"