kintoneコマンドラインツール cli-kintone を使ってkintoneクエリを理解する

# 環境

* 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の場合です。

```import.csv
"*顧客コード","引き合い"
"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トークン認証ではレコードの追加・更新ができません。この場合はパスワード認証を使います。

営業支援パックの「案件管理」にレコードを追加します。
フィールドコード顧客名がルックアップ、案件名が必須項目です。

```importfile.csv
"顧客名","案件名"
"戸田ネットソリューションズ","新規案件1"
"金都運総研","新規案件2"
```

```bash
cli-kintone --import -a 123 -u 'userid' -p 'password' -d Domain -f ./importfile.csv
: Start from lines: 1 - 3 => SUCCESS
: DONE
```

<img width="999" alt="スクリーンショット 2019-10-03 12.46.32.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/214523/80e62bce-f41e-b198-2f37-79dd8f2ce9f3.png">

<img width="703" alt="スクリーンショット 2019-10-03 12.46.48.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/214523/a3408654-5eb5-7314-32e1-9ee90351653b.png">

# データマイグレーション時の cli-kintone の使いどころ

cli-kintone を使わなくても良い場面も多い訳で、使わざるを得ない場面で利用することになります。

* 既存のkintoneアプリの一部のフィールドを他のアプリに移行したいが、フィールド名が全て同じの為移行したフィールドの区別が付かない。

<img width="805" alt="スクリーンショット 2019-10-16 11.53.22のコピー.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/214523/39fbd6d1-dc68-89fa-6a24-207bcf4d06be.png">

こんな時は cli-kintone を使ってフィールドコードを指定してCSV出力した方が早いです。
フィールド名を変更しても良いですが、同じフィールド名で100個とかあったらムリだと思います。

```bash
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 する

```bash
$ cat sjis.csv
"*�ڋq�R�[�h","��������"
"20","�d�b"
"19",""
"18","�����}�K"
```

普通にcat すると文字化けするので、nkf で変換します。

```bash
$ 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 に渡すオプションをあらかじめ環境変数にセットする

シェルの環境変数にオプションパラメーターをセットしておきます。

```bash
$ app=100
$ echo $app
100
$ APIToken=APIトークン
$ kintoneDomain=sample.cybozu.com
cli-kintone -a ${app} -t ${APIToken} -d ${kintoneDomain} -q "limit 10"
```


---