kintone コマンドラインツール(v0)の使い方

著者名: KADOYA Ryo (External link)

目次

caution
警告

この記事で紹介している cli-kintone v0 は、2023 年 10 月 31 日をもって、セキュリティアップデートを含めたすべての開発を終了します。
cli-kintone v0 を利用している場合には、2022 年 10 月 24 日にリリースされた v1.0.0 以降の cli-kintone への移行を推奨します。

ver.1.0.0 以降の cli-kintone の使い方は、次のページを参照してください。
kintone コマンドラインツール(cli-kintone)

kintone コマンドラインツールとは

kintone コマンドラインツールは、コマンドライン上から簡単に kintone にデータのインポートやエクスポートができるツールです。
コマンドラインツールを使うと、kintone の画面から Excel/CSV をインポートして レコードを一括登録・更新する機能 (External link) でできない、次の操作も行うことができます。

  • 一括でレコードの添付ファイルをダウンロード
  • 一括で添付ファイルをレコードに添付

また、シェルスクリプトと組み合わせると、kintone のデータのインポートやエクスポートを定期実行できます。

kintone コマンドラインツールの基本的な操作方法や、活用方法を学びたい方は、 はじめよう kintone コマンドラインツール を参照してください。

コマンドラインツールのダウンロード

kintone のコマンドラインツールは Releases kintone/cli-kintone (Github) (External link) からダウンロードできます。
Windows/MacOSX/Linux 向けの実行ファイルが用意されています。
ダウンロードしたら任意のフォルダーに解凍してください。
ここでは Windows での利用を想定します。

オプションの一覧を確認する

引数をなにも指定せずに実行すると、利用可能なオプションが表示されます。

オプション 説明
--export kintoneからデータをエクスポートする場合に指定します。
データは標準出力にエクスポート(コンソールに表示)されます。
--import kintoneにデータをインポートする場合に指定します。
データは標準入力からインポートされます。
-f オプションも指定されている場合、対象ファイルからデータがインポートされます。
-d ドメイン名(必須)cybozu.comは省略可能です。
FQDNを指定することで、cybozu.com 以外のドメイン(kintone.com, cybozu.cn) を利用することもできます。
-a アプリID(必須)
-u ログイン名(APIトークンかログイン名のいずれかが必須)
-p パスワード
-t APIトークン(APIトークンかログイン名のいずれかが必須)
-g ゲストスペース内アプリの場合、ゲストスペースのIDを指定します。
-o 出力形式
「json」もしくは「csv」が指定できます。
デフォルトは「csv」です。
-e インポート・エクスポートするファイルのエンコード方式
デフォルトは UTF-8 です。
対応するエンコード方式とオプションに指定できる値は、それぞれ次のとおりです。
  • Shift-JIS: sjis
  • UTF-8: utf-8
  • UTF-16: utf-16
  • UTF-16BE: utf-16be-with-signature
  • UTF-16LE: utf-16le-with-signature
  • EUC-JP: euc-jp
  • GBK(簡体字): gbk
  • Big5(繁体字): big5
-U BASIC認証ユーザー名
-P BASIC認証パスワード
-q 条件式。条件式の書き方は クエリの書き方 を参照してください。
オプション指定時、かつ「Limit」または「offset」を含まないとき、 カーソル API を利用して処理が実行されます。
-c エクスポートするフィールドコードをカンマ区切りで指定できます。
-f データインポート時、インポートするファイル名を指定します。
-b 添付ファイルのダウンロード先、アップロード元ディレクトリーを指定します。
-l データをファイルからインポートする場合に、インポート開始行を指定します。
このオプションを指定すると、データのインポートは指定した行から開始されます。
-D インポート時にこのオプションを指定すると、既存のレコードをすべて削除してからデータをインポートします。

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

ドメイン名が「sample.cybozu.com」でアプリ ID が「999」の場合のレコードを表示するコマンドは、次のとおりです。

1
2
>cli-kintone.exe --export -a 999 -d sample -u bozuman
Password: 

bozuman ユーザーのパスワードを入力すると、CSV 形式ですべてのフィールドのデータがエクスポートされます。
JSON 形式で表示するには、-o json を指定します。
途中で中断する場合は、CTRL+C を押してください。

結果は以下のようになります。

1
2
3
4
5
"$id","$revision","レコード番号","作成日時","作成者","入社","所属","更新日時","更新者","氏名"
"4","1","4","2014-08-11T08:01:00Z","Administrator","2014-06-10","社長室","2014-08-11 T08:01:00Z","Administrator","吉田 武"
"3","1","3","2014-08-11T08:00:00Z","Administrator","2011-04-04","開発部","2014-08-11 T08:00:00Z","Administrator","加藤 義男"
"2","1","2","2014-08-11T08:00:00Z","Administrator","2007-04-02","総務部","2014-08-11 T08:00:00Z","Administrator","佐藤 知美"
"1","1","1","2014-08-11T07:59:00Z","Administrator","2006-04-03","営業部","2014-08-11 T07:59:00Z","Administrator","山田 太郎"

API トークンを利用する

API トークンを利用すると、パスワードを入力しなくてもデータをインポート・エクスポートできます。
API トークンは、アプリの設定 > API トークンから取得できます。
実行する操作に合わせて、API トークンに適切な権限を設定してください。

1
>cli-kintone.exe --export -a 999 -d sample -t c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3

追加・更新の対象にルックアップフィールドが含まれている場合、API トークンを利用できません。
ユーザー名/パスワードを利用してください。

Shift-JIS でエクスポートする

kintone ではデフォルトで UTF-8 で文字列データがエクスポートされます。
-e オプションを使うことで、エクスポートする文字エンコーディングを指定できます。

1
>cli-kintone.exe --export -a 999 -d sample -t c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3 -e sjis

CSV ファイルに実行結果をリダイレクトする

次のように「>」を使用することで、cli-kintone の実行結果を CSV ファイルにリダイレクトできます。
リダイレクトは cli-kintone の機能ではなく、一般的なコマンドラインで利用できる機能です。
OS によっては、利用方法や出力結果が異なります。

1
>cli-kintone.exe --export -a 999 -d sample -t c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3 -e sjis > sample.csv

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

-c オプションを使うことで、エクスポートするフィールドを指定できます。
テーブルの値を出力する場合は、テーブル自体のフィールドコードを指定してください。
テーブル内のフィールドコードを指定して出力はできません。

1
>cli-kintone.exe --export -a 999 -d sample -u bozuman -c "$id,氏名,所属"

出力例は次のとおりです。

1
2
3
4
5
"$id","氏名","所属"
"4","吉田 武","社長室"
"3","加藤 義男","開発部"
"2","佐藤 知美","総務部"
"1","山田 太郎","営業部"

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

-q オプションを使うことで、絞り込み条件と並び順を指定できます。
条件式の書き方は クエリの書き方 を参照してください。

1
>cli-kintone.exe --export -a 999 -d sample -u bozuman -c "$id,氏名,入社" -q "入社 < \"2014-01-01\" order by 入社 asc"

出力例は次のとおりです。

1
2
3
4
"$id","氏名","入社"
"1","山田 太郎","2006-04-03"
"2","佐藤 知美","2007-04-02"
"3","加藤 義男","2011-04-04"

ファイルからデータをインポートする

既存のデータを更新する

既存のデータを更新するには、CSV ファイルに「$id」カラムを用意します。

以下は、加藤さんの所属を企画部に、山田さんの所属を人事部に変更する CSV ファイルの例です。

1
2
3
"$id","氏名","所属"
"3","加藤 義男","企画部"
"1","山田 太郎","人事部"

このファイルをインポートするコマンドは次のとおりです。

1
>cli-kintone.exe --import -a 999 -d sample -u bozuman -e sjis -f sample.csv

また、「$id」カラムを指定せずに、特定のフィールド(レコード番号フィールド除く)を指定してレコードを更新できます。

特定のフィールドで更新する場合は、CSV ファイルのヘッダー行のフィールドコードの先頭に、更新キーを表すマーク「*」をつけます。
このとき、更新キーとなるフィールドは「値の重複を禁止する」設定を有効にしておく必要があります。

以下は、顧客コードでレコードを更新する CSV ファイルの例です。

1
2
3
"*顧客コード","氏名","所属"
"0001","加藤 義男","企画部"
"0002","山田 太郎","人事部"

このファイルをインポートするコマンドは次のとおりです。

1
>cli-kintone.exe --import -a 999 -d sample -u bozuman -e sjis -f sample.csv

新規にデータを登録する

次のように CSV ファイルに「$id」カラムが存在しない場合や、「$id」カラムの値が空文字列の場合、新規にレコードが登録されます。

1
2
3
"氏名","所属","入社"
"山本 慎吾","開発部","2014-08-11"
"田中 雄太","営業部","2014-08-11"

このファイルをインポートするコマンドは次のとおりです。

1
>cli-kintone.exe --import -a 999 -d sample -u bozuman -e sjis -f sample.csv

インポートすると、次のようにレコードが追加されます。

1
2
3
4
5
6
7
"$id","氏名","所属"
"6","田中 雄太","営業部"
"5","山本 慎吾","開発部"
"4","吉田 武","社長室"
"3","加藤 義男","企画部"
"2","佐藤 知美","総務部"
"1","山田 太郎","人事部"

既存のデータを削除して登録する

-D オプションを指定すると、既存のレコードをすべて削除してからデータを追加します。

テーブルの書き出し、読み込み

書き出し

テーブル付きのレコードを書き出す場合、1 レコードの内容が複数行に分けて書き出されます。

以下は、テーブルを書き出した際の CSV データのエクスポート例です。

1
2
3
4
5
6
7
*,"$id","氏名","入社","所属","異動年月日","異動部署"
*,"5","山本 慎吾","2014-08-11","開発部","2015-01-04","総務部"
,"5","山本 慎吾","2014-08-11","開発部","2016-03-01","営業部"
*,"4","吉田 武","2014-06-10","社長室",,
*,"3","加藤 義男","2014-06-01","企画部",,
*,"2","佐藤 知美","2007-04-02","休職","2015-01-04","総務部"
*,"1","山田 太郎","2006-04-03","総務部",,

この例では異動年月日と異動部署がテーブルになっています。
書き出した CSV の 1 行目には 1 列目に「*」マークが出力され、それ以降はフィールドコード名が並びます。
2 行目以降で「*」マークがついていない行は、テーブル内の 2 行目以降のデータになります。

上記の CSV データの場合、5 レコードがエクスポートされています。
「$id」が 5 の『異動年月日』と『異動部署』を含むテーブル内に 2 行分のデータが入っているため、CSV でも 2 行分のデータがエクスポートされています。

読み込み

読み込みも同様に、2 行目以降で「*」マークがついていない行は、テーブル内の 2 行目以降のデータとして扱われます。
先頭列に「*」がついていない行の、テーブルの行以外の値は無視されます。

添付ファイルのダウンロード、アップロード

ダウンロード

-b オプションに、ダウンロード先のフォルダー名を指定します。
フォルダーが存在しない場合は、自動的に作成されます。
ここでは「写真」フィールドのフィールドタイプが添付ファイルに設定されているものとします。

1
>cli-kintone.exe --export -a 999 -d sample -u bozuman -c "$id,氏名,写真" -b download

出力例は次のとおりです。

1
2
3
4
5
"$id","氏名","写真"
"5","山本 慎吾","写真-5/photo_山本.jpg"
"4","吉田 武","写真-4/photo_吉田.jpg"
"2","佐藤 知美","写真-2/photo_佐藤.jpg"
"1","山田 太郎","写真-1/photo_山田.jpg"

添付ファイルは、-b オプションで指定したフォルダー以下の <添付ファイルのフィールドコード>-<$id> フォルダーにダウンロードされます。

1
2
3
4
5
6
download
┠ 写真-1
┃  ┗ photo_山田.jpg
┠ 写真-2
┃  ┗ photo_佐藤.jpg
┠ ...

-c オプションを使用する場合に「$id」または「レコード番号」を指定せずに添付ファイルをダウンロードすると、添付ファイルは <添付ファイルのフィールドコード>-<Index> フォルダーに保存されます。
Index は「0」から始まる整数の連番です。
たとえば、取得対象のレコードが 3 件の場合、次のフォルダーが作成されます。

1
2
3
4
5
6
7
download
┠ 写真-0
┃  ┗ photo_山田.jpg
┠ 写真-1
┃  ┗ photo_佐藤.jpg
┗  写真-2
   ┗ photo_吉田.jpg

アップロード

ダウンロードと同様に、-b オプションでアップロードするフォルダーを指定します。
CSV ファイルに記述する値はアップロードフォルダーからの相対パスとなります。

1
>cli-kintone.exe --import -a 999 -d sample -u bozuman -b upload -f sample.csv

複数の添付ファイルを指定するときは、CR 文字でファイルを区切ります。
Microsoft Excel の場合は ALT+Enter キーで CR 文字を入力できます。

1
2
3
4
"$id","氏名","写真"
"5","山本 慎吾","写真-5/photo_山本1.jpg
写真-5/photo_山本2.jpg"
"4","吉田 武","写真-4/photo_吉田.jpg"

レコードの添付ファイルを削除するときは、削除したい添付ファイルフィールドの値を空白にします。
複数のファイルを添付している場合で一部の添付ファイルを削除したい場合は、添付ファイルフィールドの値を残したいファイルのファイル名のみにします。
この例では、$id が 5 のレコードで「写真」フィールド(添付ファイルフィールド)の添付ファイルが削除されます。

1
2
3
"$id","氏名","写真"
"5","山本 慎吾",""
"4","吉田 武","写真-4/photo_吉田.jpg"

制限事項

  • クライアント証明書を利用したセキュアアクセス環境での操作には対応していません。
    IP アドレス制限を設定した環境では、アクセスが許可された IP アドレスからツールを実行する必要があります。
  • アップロードできる添付ファイルのサイズの上限は、1 ファイルあたり 10MB です。
  • 次のフィールドはエクスポートできません。
    • ステータス
    • 作業者
    • カテゴリー
    • 関連レコード
    • グループ
      グループフィールド内のフィールドはエクスポートできます。
    • フォームを装飾するフィールド(スペース、ラベル、罫線)
  • 次のフィールドにインポートしても値は登録・更新されません。
    • ルックアップ元からコピーされるフィールド
    • 計算
    • 自動計算が設定されている文字列(1 行)フィールド
    • ステータス
    • 作業者
    • カテゴリー
    • 作成者
    • 作成日時
    • 更新者
    • 更新日時
    • 関連レコード
    • グループ
      グループフィールド内のフィールドはインポートできます。
    • フォームを装飾するフィールド(スペース、ラベル、罫線)

おわりに

コマンドラインツールは REST API を使用するため、スタンダードコースのライセンスが必要です。
大量のデータ操作は kintone に負荷がかかり、パフォーマンスに影響することがあります。

関連 Tips

information

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