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で動作を確認しています。