kintone コマンドラインツール（cli-kintone v0）
cli-kintone とは
kintone コマンドラインツール（cli-kintone）は、コマンドで kintone へデータをインポートしたり、エクスポートしたりできるツールです。
cli-kintone を使うと、
kintone の画面からレコードを一括登録・更新する機能
ではできない、次の操作ができます。
- 一括でレコードの添付ファイルをダウンロードする。
- 一括で添付ファイルをレコードに添付する。
cli-kintone は CLI ツールとして提供されているため、プログラムから kintone のデータのインポートやエクスポートができます。
この記事では、cli-kintone の基本的な使い方を説明しています。
詳しい使い方や活用方法を知りたい場合は、
はじめよう kintone コマンドラインツール を参照してください。
GitHub
https://github.com/kintone-labs/cli-kintone
ライセンス
GNU General Public License v2.0
ドキュメント
https://github.com/kintone-labs/cli-kintone/blob/master/README.md
注意事項
- cli-kintone を使ってレコードをインポート／エクスポートするには、スタンダードプランが必要です。
- 大量のレコードデータを操作すると、kintone に負荷がかかり、パフォーマンスに影響することがあります。
導入方法
cli-kintone の Windows／macOS／Linux 向けの実行ファイルは、
GitHub
からダウンロードできます。
ファイルをダウンロードしたら解凍して、実行ファイルを任意の場所においてください。
Quickstart
ここでは、Windows での使い方を例に説明します。
データをエクスポートする
STEP1：下準備
-
次のフィールドを配置した、kintone のアプリを作成します。
フィールド名 フィールドの種類 フィールドコード 備考 社員番号 文字列（1行） EmployeeId 氏名 文字列（1行） Name 入社日 日付 JoinDate 所属 ドロップダウン Division 項目には、次の値を設定します。 - 開発部
- 総務部
- 営業部
- 企画部
- 人事部
写真 添付ファイル Photo -
テストデータとして、2 件のレコードを追加します。
-
作成したアプリの URL で、アプリ ID を確認します。
URL のhttps://sample.cybozu.com/k/123の末尾の数字部分が、アプリ ID です。 上記の場合、アプリ ID は、123です。 -
「レコード閲覧」の権限を付けた API トークンを生成します。
手順の詳細は、 API トークンを生成する を参照してください。
STEP2：ログイン名／パスワードでレコードの情報を表示する
レコードの情報を表示するには、--export を指定します。
--export に続けて、必ずドメイン名とアプリ ID も指定します。
-d：ドメイン名-a：アプリ ID
ログイン名は、-u オプションで指定します。
実行例
|
|
パスワードの入力を求められます。
指定したユーザーのパスワードを入力すると、CSV 形式で、アプリのレコード情報が表示されます。
項目の見出し名は、フィールドコードの値です。
実行例
|
|
STEP3：API トークンでレコードの情報を表示する
API トークンを使って、レコードの情報を表示できます。
API トークンは、-t オプションに指定します。
実行例
|
|
STEP4：Shift-JIS でレコードの内容を表示する
cli-kintone の標準の文字コードは、UTF-8 です。
Shift-JIS でレコードの内容を表示するには、-e オプションに sjis を指定します。
実行例
|
|
STEP5：ファイルにエクスポートする
シェルのリダイレクト機能を使うと、出力結果をファイルに出力できます。
実行例
|
|
STEP6：絞り込み条件とデータの並び順を指定する
絞り込み条件や、データの並び順を指定する場合には、-q オプションでクエリを指定します。
クエリ記法は、
クエリの書き方 を参照してください。
実行例
|
|
STEP7：添付ファイルをダウンロードする
レコードに添付されたファイルをダウンロードする場合には、-b オプションに、ダウンロード先のフォルダー名を指定します。
フォルダー名は、実行している場所からの相対パスです。
実行例
|
|
添付ファイルは、指定したフォルダー下の、レコードごとに作られるフォルダーへダウンロードされます。
レコードごとに作られるフォルダーの命名規則は、次の 2 とおりです。
-
-cオプションを指定していない、または-cオプション で $id を指定した場合
フォルダー名は、「フィールドコード-$idの値」です。1 2 3 4 5 6 7attachments ├── Photo-1 │ ├── yamada-taro.png ├── Photo-2 │ └── suzuki-hanako.png └── Photo-3 └── takahashi-ichiro.png -
-cオプションで $id を指定していない場合
フォルダー名は、「フィールドコード-0から始まる数字」です。1 2 3 4 5 6 7attachments ├── Photo-0 │ ├── yamada-taro.png ├── Photo-1 │ └── suzuki-hanako.png └── Photo-2 └── takahashi-ichiro.png
STEP8：テーブルのデータを表示する
下準備
-
STEP1 で作成したアプリに、テーブルのフィールドを追加します。
フィールド名 フィールドの種類 フィールドコード 備考 配属情報 テーブル AssignInformation テーブルには、「配属日」「配属部署」を配置します。 配属日 日付 AssignDate 「レコード登録時の日付を初期値にする」のチェックボックスを外します。 配属部署 ドロップダウン AssignDivision 項目には、次の値を設定します。 - 開発部
- 総務部
- 営業部
- 企画部
- 人事部
-
作成したテストデータを 1 件追加します。
「異動情報」テーブルには、2 行追加してください。
テーブルのデータを表示する
標準機能のファイル書き出しと同じように
、テーブルのデータは、1 レコードの内容が複数行に分けて表示されます。
ファイルの先頭列の「*」から次の「*」の前までの行が、1 つのレコードのデータです。
実行例
|
|
STEP9：フィールドを指定する
エクスポートするフィールドを指定するには、-c オプションで指定します。
複数のフィールドを指定する場合は、半角カンマ（,）でフィールド名を区切ります。
テーブルのデータを表示する場合は、テーブルのフィールドコードを指定します。テーブル内のフィールドは指定できません。
フィールドの並び順を指定したい場合は、出力したいフィールドの並び順どおりになるよう、-c オプションでフィールドコードを並べます。
実行例
|
|
データをインポートする
STEP1：下準備
-
次のフィールドを配置した、kintone のアプリを作成します。
フィールド名 フィールドの種類 フィールドコード 備考 社員番号 文字列（1行） EmployeeId 「値の重複を禁止する」のチェックボックスを選択する 氏名 文字列（1行） Name 入社日 日付 JoinDate 所属 ドロップダウン Division 項目には、次の値を設定します。 - 開発部
- 総務部
- 営業部
- 企画部
- 人事部
写真 添付ファイル Photo -
作成したアプリの URL で、アプリ ID を確認します。
URL のhttps://sample.cybozu.com/k/123の末尾の数字部分が、アプリ ID です。 上記の場合、アプリ ID は、123です。 -
「レコード追加」「レコード編集」「レコード削除」の権限を付けた API トークンを生成します。 手順の詳細は、 API トークンを生成する
を参照してください。
STEP2：レコードを追加する
レコードをインポートするには、--import を指定します。
--import に続けて、必ずドメイン名とアプリ ID も指定します。
-d：ドメイン名-a：アプリ ID
レコードを追加するには、-f オプションで、レコードに追加する内容を記載した CSV ファイルを指定します。
CSV ファイルの 1 行目は、項目名です。
項目名には、対応するフィールドのフィールドコードを指定します。
CSV ファイルの例
|
|
実行例
|
|
STEP3：レコードを更新する
既存のレコードを更新するには、次の 2 つの方法があります。
方法1：レコード ID を使う
方法 1 では、レコード ID が一致しているレコードを更新します。
CSV ファイルに、「$id」項目を用意します。
「$id」には更新するレコード ID を指定します。
「$id」項目の値が空文字の場合は、新規にレコードが追加されます。
レコードID が 1 のレコードを更新し、「坂本 舞子」のデータを追加する CSV ファイルの例
|
|
実行例
|
|
方法2：フィールドコードを使う
方法 2 では、指定したフィールドコードの値が一致するレコードを更新します。
データを特定するためのキーとなるフィールドコードの項目名の先頭に、* をつけます。
キーとなるフィールドには、「値の重複を禁止する」を設定してください。
また、レコード番号フィールドは指定できません。
社員番号が「0005」のレコードを変更する CSV ファイルの例
|
|
実行例
|
|
STEP4：既存のレコードをすべて削除して追加する
既存のデータをすべて削除してレコードを追加するには、-D オプションを指定します。
実行例
|
|
STEP5：添付ファイルをアップロードする
レコードにファイルを添付するには、-b オプションで、アップロードするファイルを配置したフォルダー名を指定します。
フォルダー名は、実行している場所からの相対パスです。
CSV の添付ファイルフィールドの値に指定するファイルは、実行している場所からの相対パスです。
*CSV の例
|
|
フォルダー構成の例
|
|
実行例
|
|
ファイルを複数指定する場合
ファイルを複数指定する場合には、改行（CR）で区切ります。Microsoft Excel では、ALT + Enter キーで入力できます。
*CSV の例
|
|
添付ファイルを削除する場合
添付ファイルフィールドに添付されているファイルをすべて削除する場合は、値を空白にします。
一部の添付ファイルを削除したい場合には、残したいファイル名だけにします。
社員番号が「0006」のレコードの添付ファイルを削除し、社員番号が「0007」の添付ファイルを「ishikawa-megumi.png」のみにする CSV の例
|
|
STEP6：テーブルのデータを更新する
下準備
-
STEP1 で作成したアプリに、テーブルのフィールドを追加します。
フィールド名 フィールドの種類 フィールドコード 備考 配属情報 テーブル AssignInformation テーブルには、「配属日」「配属部署」を配置します。 配属日 日付 AssignDate 「レコード登録時の日付を初期値にする」のチェックボックスを外します。 配属部署 ドロップダウン AssignDivision 項目には、次の値を設定します。 - 開発部
- 総務部
- 営業部
- 企画部
- 人事部
-
作成したテストデータを 1 件追加します。
テーブルのデータを更新する
標準機能のファイル読み込みと同じように
、テーブルのデータは、1 レコードの内容を複数行に分けて作成します。
ファイルの先頭列の「*」から次の「*」の前までの行が、1 つのレコードのデータを表します。
ファイルの先頭列は、「*」という項目名にします。
各レコードのデータの開始行の先頭列には「*」を記載し、それ以外は空にします。
CSV ファイルの例
|
|
実行例
|
|
補足
オプション一覧
オプションを指定せずに実行すると、オプションの一覧が表示されます。
|
|
メインのオプション
レコードをインポート、またはエクスポートする
| オプション | 説明 |
|---|---|
| --export | kintone からデータを取得し、標準出力にエクスポートします。 ファイルに出力する場合は、 OS のシェルの機能であるリダイレクトを利用します。 詳しくは、 ファイルにエクスポートする を参照してください。 |
| --import | 標準入力から、kintone にデータをインポートします。 ファイルからインポートする場合には、 -f オプションを同時に指定してください。詳しくは、 ファイルからデータをインポートする を参照してください。 |
--export または --import 以降に指定するオプション {notes-options-sub}
| オプション | 必須 | 説明 |
|---|---|---|
| -d | 必須 | ドメイン名 exmaple.cybozu.com のようにドメインを指定します。 サブドメイン名だけを指定すると、「.cybozu.com」が自動で付与されます。 |
| -a | 必須 | アプリID |
| -u | 条件必須 | ログイン名 パスワードで認証する場合は必須です。 |
| -p | 条件必須 | パスワード パスワードで認証する場合は必須です。 |
| -t | 条件必須 | APIトークン API トークンで認証する場合は必須です。 |
| -U | 省略可 | Basic 認証のログイン名 |
| -P | 省略可 | Basic 認証のパスワード |
| -g | 省略可 | ゲストスペースの ID |
| -o | 省略可 | 出力形式 次の値を指定します。
|
| -e | 省略可 | ファイルのエンコード方式 次の値を指定します。
|
| -q | 省略可 | レコードの絞り込み条件 条件式の書き方は、 クエリの書き方 を参照してください。 このオプションを指定している場合に、クエリに limit や offset を含まないときは、カーソル API を使ってレコードが取得されます。 |
| -c | 省略可 | エクスポートするフィールドコード 複数のフィールドウィ指定する場合は、カンマ区切りで指定します。 詳細は、 フィールドを指定する を参照してください。 |
| -f | 省略可 | インポートするファイル名 |
| -b | 省略可 | 添付ファイルのフォルダー名 エクスポートする場合は、添付ファイルを保存するフォルダー名を、インポートする場合は、アップロードするファイルを配置したフォルダー名を相対パスで指定します。 |
| -l | 省略可 | インポートの開始行 指定した行からインポートされます。 省略すると、データの 1 行目からインポートします。 |
| -D | 省略可 | 既存レコードをすべて削除してからインポートをするか |
制限事項
- IP アドレス制限を設定している場合、ツールを実行する環境の IP アドレスのアクセスを許可してください。
クライアント証明書を利用しての実行はできません - アップロードできる添付ファイルのサイズ上限は、1 ファイルあたり 10MB までです。
- 次のフィールドはエクスポートできません。
- ステータス
- 作業者
- カテゴリー
- 関連レコード
- グループ
グループフィールド内のフィールドはエクスポートできます。 - フォームを装飾するフィールド（スペース、ラベル、罫線）
- 次のフィールドにインポートしても値は登録・更新されません。
- ルックアップ元からコピーされるフィールド
- 計算
- 自動計算が設定されている文字列（1 行）フィールド
- ステータス
- 作業者
- カテゴリー
- 作成者
- 作成日時
- 更新者
- 更新日時
- 関連レコード
- グループ
グループフィールド内のフィールドはインポートできます。 - フォームを装飾するフィールド（スペース、ラベル、罫線）
関連 Tips
更新履歴
詳細は、
GitHub の Releases
を参照してください。
- 2018 年 01 月 10 日 Version 0.9.0
- ユーザーエージェント名を修正
- 標準入力をインポートデータに指定できる機能を追加
- CSV の読み込み開始行を指定できる機能を追加
- 100 行以上のインポート処理でエラーメッセージが表示されない問題に対応し、インポート処理で 100 行毎に結果を出力するよう修正
- Basic 認証のロジックを修正
- 2018 年 04 月 12 日 Version 0.9.1
- ゲストスペース内のアプリに対して次のコマンドを使用するとインポートに失敗するバグを修正
cli-kintone.exe -d {ドメイン名} -a xx -g xx -t {APIトークン} -f {ファイルパス}
- ゲストスペース内のアプリに対して次のコマンドを使用するとインポートに失敗するバグを修正
- 2018 年 05 月 15 日 Version 0.9.2
- 3rd party library のバージョンを最新版ではなく、バージョン指定してリリースするように変更
- 2019 年 02 月 27 日 Version 0.9.3
- Shift-JIS でエクスポートした場合、エクスポートされたファイルのフィールドに。
- UTF-8 から Shift-JIS に変換できない文字が含まれていると、フィールドの値が移動するバグを修正
- 2019 年 04 月 2 日 Version 0.9.4
- 特殊な文字コードをもつ文字列に関する不具合を修正
- 2019 年 11 月 26 日 Version 0.10.0
- Go のバージョンを 1.9.3 から 1.13.3 に更新
-vまたは--versionを使用してツールのバージョンを取得できるように更新
- 2019 年 11 月 28 日 Version 0.10.1
- エクスポートするレコードがない場合のメッセージを変更
- 2020 年 02 月 12 日 Version 0.10.2
- データの取得方法を以下のように変更
-qオプションを指定した際、クエリに「limit」または「offset」が含まれない場合にカーソル API を実行するように変更- クエリに「limit」または「offset」が含まれている場合にレコード一括取得 API を実行するように変更
- ユーザーエージェント名を下記フォーマットに変更
cli-kintone/バージョン(OS 情報) - Mac OS X/Linux と Windows でのビルドやデータ操作方法の説明を README にて更新
- データの取得方法を以下のように変更
- 2020 年 03 月 31 日 Version 0.11.0
- 以下のエンコーディング方式に対応
- GBK（簡体字）
- Big5（繁体字）を追加
- UTF-8（BOM 付き）ファイルのインポートに対応
- Go のバージョンを 1.13.3 から 1.13.7 に更新
- 以下のエンコーディング方式に対応
- 2020 年 12 月 07 日 Version 0.11.3
- Go のバージョンを 1.13.7 から 1.15.5 に更新
- レコードの添付ファイルを削除できる機能を追加
- 2022/09/07 Version 0.14.0
- 内部的に利用している go-kintone を v0.4.1 から v0.4.3 に更新
それに伴い、エクスポートできるフィールドに一部変更があります。- グループフィールドに設置した次のフィールドをエクスポートできるようになりました。
- レコード番号、作成者、作成日時、更新者、更新日時
- 関連レコードフィールドがエクスポートされなくなりました。
- グループフィールドに設置した次のフィールドをエクスポートできるようになりました。
- 内部的に利用している go-kintone を v0.4.1 から v0.4.3 に更新
この記事で紹介しているサンプルコードは、2022 年 8 月版 kintone および cli-kintone Version 0.14.0 で動作を確認しています。