カテゴリー内の他の記事

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

(著者:サイボウズ KADOYA Ryo

Index

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

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

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

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

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

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

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

Releases kintone/cli-kintone (Github)

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

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

cki-kintone.png

オプション 説明
--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の場合の例

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

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

APIトークンを利用する

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

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

Shift-JISでCSVファイルにエクスポートする

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

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

-cオプションを使うことで、エクスポートするフィールドを指定できます。

  • テーブルの値を出力する場合は、テーブル自体のフィールドコードを指定してください(テーブル内のフィールドコードを指定して出力はできません)。

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

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

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

既存のデータを更新する

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

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

また、$idカラムを指定せずに、特定のフィールド(レコード番号フィールド除く)を指定してレコードを更新することもできます。
特定のフィールドで更新する場合は、CSVファイルのヘッダ行にあるフィールドコードの先頭に、更新キーを表すマーク"*"をつけます。
このとき、更新キーとなるフィールドは「値の重複を禁止する」設定を有効にしておく必要があります。
顧客コードでレコードを更新するCSVファイルの例

新規にデータを登録する

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

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

 

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

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

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

書き出し

テーブル付きのレコードを書き出す場合、1レコードの内容が複数行に分けて書き出され、CSVデータのエクスポート結果は以下のようになります。

この例では異動年月日と異動部署がテーブルになっています。
書き出したCSVの1行目には1列目に"*"マークが出力され、その後フィールドコード名が並びます。
2行目以降で"*"マークがついていない行は、テーブル内の2行目以降のデータになります。
上記のCSVデータの場合、5レコードがエクスポートされています。
$idが5の『異動年月日』と『異動部署』を含むテーブル内に2行分のデータが入っているため、CSVでも2行分のデータがエクスポートされています。

読み込み

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

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

ダウンロード

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

-bオプションを指定したとき、添付ファイルフィールドの値はダウンロードされたファイルのダウンロードフォルダからの相対パスとなります。

添付ファイルは、downloadフォルダ以下の<添付ファイルのフィールドコード>-<$id>フォルダにそれぞれ保存されます。

また、-cオプションを指定したとき、エクスポートするフィールドに"$id"または"レコード番号"が含まれていない場合には、
添付ファイルは、downloadフォルダ以下の<添付ファイルのフィールドコード>-<Index(※)>フォルダにそれぞれ保存されます。

※ Index は0から始まり、取得対象のレコード数に合わせて増加します。
例)取得対象のレコードが3件の場合
<添付ファイルのフィールドコード>-0
<添付ファイルのフィールドコード>-1
<添付ファイルのフィールドコード>-2

アップロード

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

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

制限事項

セキュアアクセス環境には対応していません。

アップロードできるファイルサイズの上限は10MBです。

下記のフィールドに登録されている情報の操作はできません。

  • グループフィールド内の下記のフィールド
    レコード番号、作成者、作成日時、更新者、更新日時
  • カテゴリ
  • ステータス
  • グループ

おわりに

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

関連Tips

このTipsは、cli-kintone Ver 0.11.0 と2020年3月版で確認したものになります。

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

Avatar
cybozu Development team

Seki様

ご質問いただきありがとうございます。cybozu developer network運営チームです。

IPアドレス制限をすべて"拒否"にするのは行けないと思います。

手元に確認環境がないため動作を見れていませんが、

IPアドレスを、開放または一部開放(コマンドライン実行用のIPアドレス)とした上で、ログイン名とパスワード認証でお試ししていただけますでしょうか。

Avatar
Seki

cybozu Development team様

回答ありがとうございます。
という事は、そもそも REST API での連携とセキュアアクセス(クライアント証明書)が併用出来ないという事で宜しいでしょうか?

この手の分野の知識に乏しいため常識的な確認かも知れませんが、教えてください。

 

以上、宜しくお願い致します。

Avatar
cybozu Development team

Seki様

 

お世話になっております。
ご質問いただきありがとうございます。cybozu developer network運営チームです。

現時点でREST APIに証明書の情報を載せる方法がないので、
REST APIを使って、証明書が入っている環境と外部サービス間でデータをやり取りすることはできません。
ご希望に添えず申し訳ございません。

cli-kintoneを使う場合、証明書が入っている環境でも、IPアドレス許可 + ログイン名とパスワードの認証でレコード取得できるかと思います。

ご確認お願い致します。

Avatar
oota

お返事が遅くなり、すみません

現状ですと、証明書が入っている場合に利用するのが難しそうですね...

検証していただき、ありがとうございます

Avatar
合同会社いぶき
合同会社いぶきにより編集されました
Avatar
合同会社いぶき

cybozu Development team様

 

いつもありがとうございます。

上記にてコメントを提出させていただきましたが、自己解決致しました。

大変申し訳ございませんが、取り下げさせていただきます。

 

*弊社作成のアプリの設定誤りがございました。

 

Avatar
Taiki Goto

お世話になっております。

コマンドラインツールの構文が同じなのに環境によって出力結果が違うということはありえるのでしょうか?

 

実はサブテーブルつきのアプリからサブテーブルを-cオプションで指定しているのですが、私が実行して出力されたcsvのとお客様の環境で実行し出力されたcsvに差異があります。

サブテーブルは6つの項目からなり、私のほうで実行すると6つが出力されるだけなのですが、お客様の環境で実行すると6つの項目のほかにサブテーブルのフィールドコードの名称の列が出力されます。

パッと見た感じサブテーブルの行ID?

出力対象の1レコード目がサブテーブル3行だとすると10000,10001,10002

2レコード目がサブテーブル2行なら10003,10004となります。

 

よろしくお願いします。

Avatar
Taiki Goto

デバックした結果 record['テーブル'][value][0][id]のようでした。

よろしくお願いします。

Avatar
cybozu Development team

Taiki Goto様

返事が遅れまして申し訳ありません。

record['テーブル'][value][0][id]でしたら、テーブルの行IDですね。
行IDは本記事の記載通りに、普通に出力されます。

全く同じ構文でしたら、環境依存かもしれません。
こちらで試した結果、同じく行IDが出力されます。

Avatar
Taiki Goto

cybozu Development team様

お世話になっております。

あれから色々試したのですがcli-kintoneのバージョンの違いのようです。

 バージョン7では行IDは出力されませんでした。

 

 

 

Avatar
cybozu Development team

Taiki Goto 様

バージョンの違いですね。失礼しました。

 

Avatar
鈴木

お世話になっております。

kintoneコマンドラインツールを使用して添付ファイルを含むレコードの取得をしようとしたところ、

コマンド上に以下のような文章が表示され、取得できませんでした。

レコード数は200件ほどです。

 

2017/09/26 14:57:16 Get https://×××.cybozu.com/guest/xx/k/v1/form.json: dial tcp XXX.XX
X.XXX.XXX:443:  i/o timeout

 

問題としては何が考えられるでしょうか

Avatar
cybozu Development team

鈴木 様

いつもお世話になっております。
cybozu developer networkの運営事務局です。

ご質問のエラーはkintoneで用意しているものではないので、
Webなどの情報を参考にすると、お客様環境のネットワークに依存した問題だと思われます。
(APIクライアントからcybozu.comへの接続が怪しいのではないかと思います。)

エラーメッセージからwebで検索すれば原因がわかるかと思いますので、
それらを参考にして解決していただければと思います。

よろしくお願いします。

Avatar
鈴木

cybozu Development team 様

 

回答いただき、ありがとうございます。

確認してみます。

Avatar
Atsushi Yatabe

フィールド、システム識別子ごとの利用可能な演算子と関数一覧について、

日時または日付が空(null?)の場合の条件を付けたいのですが、どのようにすれば良いでしょうか?

以下のようにやってもうまくいきません。

>cli-kintone.exe -a 999 -d sample -u bozuman -q "日付 != \"\""

Avatar
cybozu Development team

Atsushi Yatabe様

ご質問の件ですが、記事のシナリオから離れているため、コミュニティでご質問をお願いできますでしょうか。

コマンドラインツールのクエリはREST APIのクエリの記述法と同様ですので、

REST APIフォーラムでご質問いただければと存じます。https://developer.cybozu.io/hc/ja/community/topics/200034355

Avatar
mamoru

大変助かりました!

1点だけなのですが、コマンドラインツールを利用してDATETIME型をインポートすると時間がずれます。

どのように対応すればよろしいでしょうか?ご教示くださいませ。

リクエスト値:2018/8/1  11:26:00

入力値:2018-08-01 23:26

 

Avatar
cybozu Development team

mamoru 様

お世話になっております。cybozu developer network事務局でございます。

cli-kintoneはREST APIの仕様と同一となっており、通常、日時フィールドはUTC時間で保存されるため誤差が発生します。
https://developer.cybozu.io/hc/ja/articles/202166330

また、ご質問の件は記事と直接関係がないため、コミュニティでご質問頂きますようお願い致します。

Avatar
gunyakun

お世話になっております。

cli-kintoneのコマンドを使って、カラム指定をしてエクスポートしたいのですが、サブテーブルの項目だけエクスポートされません。

(カラム指定しなければ、エクスポートされます。)

以下のように記載しておりますが、何か書き方が間違っているのでしょうか?

ご教授の程、よろしくお願い致します。

例)部・役職・氏名はサブテーブルです。

cli-kintone.exe -a 100 -d aaa -t トークン -c "$id,更新者,更新日時,顧客コード,会社,営業所,郵便番号,都道府県,市区町村,住所,部,役職,氏名" -q "更新日時 > \"2018-09-05T03:46:05\"" -e sjis >C:\kintone\EXP.cav

 

 

 

 

 

Avatar
cybozu Development team

gunyakun 様

お世話になっております。cybozu developer network事務局でございます。

サブテーブルを指定する場合は、テーブル自体のフィールドコードを指定してください。

技術的な質問がある場合は、コミュニティをご活用ください。

よろしくお願い致します。

Avatar
Sog

お世話になります。

コマンドラインツールのV0.9.3をダウンロードして動かしてみたところ、--export時に-e sjisを指定すると日本語のフィールドが取得できません。

-e sjisを指定しないと問題はなさそうですね。

V0.9.2では-e sjisを指定すればきっちりsjisで取得できていましたが・・。

何か仕様変更が入ったのでしょうか?

Avatar
cybozu Development team

Sog 様

お世話になっております、cybozu developer network事務局でございます。

ご指摘の点につきまして、弊社環境でも同様の事象を確認しました。

本件の対応・進捗につきましては、こちらでご報告させていただきます。

ご不便をおかけして申し訳ございません。

cybozu Development teamにより編集されました
Avatar
cybozu Development team

Sog 様

お世話になっております、cybozu developer network事務局でございます。

 

コマンドラインツールのVersion 0.9.3について、エクスポート時にsjisで日本語のフィールドが取得できない件、

修正の対応が完了いたしました。

下記ページの「Version 0.9.4」をご利用ください。

https://github.com/kintone/cli-kintone/releases

 

この度はご迷惑をお掛けしまして申し訳ございません。

引き続きご活用いただけますと幸いです。

Avatar
TK

お世話になっております。

cli-kintoneのWindows64版のZIPを解凍したところ、セキュリティに引っ掛かかってしまいます。

こちらの環境のせいでしょうか??。

Avatar
cybozu Development team

TK 様
お世話になっております、cybozu developer network事務局でございます。

添付いただいた画像を拝見する限りでは、cli-kintone.exeファイルによって
お客様環境のセキュリティサービスが起動しているようです。
お客様環境や設定によって、どのような条件でセキュリティサービスが起動するのか異なるため、
対策方法はご案内できかねます。

ご期待に添えず、申し訳ございません。

Avatar
TK

cybozu Development team 様

お世話になっております。

そうですよね、すみませんお手数おかけしました!

これからもよろしくお願いします!

Avatar
Hitoshi Hayakawa

Version 0.9.4 を使って、いくつかのアプリのデータをダウンロードしているのですが、特定のアプリだけ何の応答も返さずに終了してしまいます(エラーも何もでません)。

プログラムは ./cli-kintone --export -d xxxxx.cybozu.com -a 12345 -u USERNAME -p PASSWORD みたいな呼び出し方をしています。わざとパスワードを変更した場合は「[CB_WA01] ユーザーのパスワード認証に失敗しました」が、アプリから閲覧権限を抜いた場合「 [CB_NO02] 権限がありません」が表示されるため、パスワードやアプリの権限の問題では無いと思います。どのような原因が考えられるでしょうか?

Avatar
cybozu Development team

Hitoshi Hayakawa様

お世話になっております。

こちらでも検証いたしましたが、再現しない状況です。
恐れ入りますが、以下についてご確認いただけないでしょうか?

  1. Version0.9.0または0.8のコマンドラインツールでも同じ状況となるか。
    以前のバージョンは以下からダウンロードいただけます。
    https://github.com/kintone/cli-kintone/releases

  2. アプリをコピーして新規作成し、レコードを数件登録してコマンドラインツールを実行したときに同じ状況となるか。

以上、よろしくお願いいたします。

cybozu Development teamにより編集されました
Avatar
Hitoshi Hayakawa

1. 0.9.0/0.8 のどちらも同じ状況でした(0.8の場合、--export オプションが使えないということはありますが)。

2. アプリをコピーし、作成したアプリに対していくつか適当にデータを入力して CLI ツールを実行したところ、入力したデータが落ちてきました。原因は何が考えられるでしょうか?

→ すいません、どうも lookup フィールドの設定が誤っていたようです。CLI以前に CSV でもデータが0バイトになっているので、そのあたりの設定を直せばおそらく CLI でもダウンロードできそうです(まだ未確認)。

お騒がせしました。

Hitoshi Hayakawaにより編集されました
Avatar
shu kobayashi

cybozu developer network運営チームさん

kintone コマンドラインツールの利用にあたって、
こちらのAPI仕様変更の影響はありますでしょうか??

https://cs.cybozu.co.jp/2019/006924.html

漠然とした質問で申し訳ございませんが、宜しくお願いいたします。

サインインしてコメントを残してください。