カテゴリー内の他の記事

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でエクスポートする

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

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

次のように「>」を使用することで、cli-kintoneの実行結果をCSVファイルにリダイレクトできます。

リダイレクトは cli-kintone の機能ではなく、一般的なコマンドラインで利用できる機能です。OSによっては、利用方法や出力結果が異なる場合があります。

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

-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キーで入力)でファイルを区切ります。

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

制限事項

  • クライアント証明書を利用したセキュアアクセス環境での操作には対応していません。
    IPアドレス制限設定環境下では、アクセスが許可されたIPアドレスからツールを実行する必要があります。
  • アップロードできる添付ファイルのサイズの上限は、1ファイルあたり10MBです。
  • 下記のフィールドに登録されている情報の操作はできません。
    • グループフィールド内の下記のフィールド
      レコード番号、作成者、作成日時、更新者、更新日時
    • カテゴリ
    • ステータス
    • グループ

おわりに

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

関連Tips

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

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

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

Avatar
木村政志

cybozu developer network 運営様

ご回答ありがとうございます。頂きました情報をもとに対応を検討いたします。
ありがとうございました。

Avatar
mm

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

一覧の絞り込みで、絞り込んだデータをcsvにしたいのですが、そのオプションはありますか?

例えば、この図で「未申請」を選んでcsvにしたいです。

それとも、-cオプションで1つずつエクスポートするフィールドを指定する必要がありますでしょうか。

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

Avatar
cybozu Development team

mm 様

お世話になっております。cybozu developer network 運営でございます。

その場合は-cオプションや-qオプションを指定して同様の条件で出力いただくことになります。

詳しくは 絞り込み条件と並び順を指定する をご参照ください。

また、恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
試してみたわからないなど、記事から派生した技術的なご質問はcybozu developer コミュニティをご活用ください。

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

Avatar
mm
ご返信ありがとうございます。
早速出力を試したのですが、アプリが使用できませんでした。
このツールは最新のWindows(64bit機)のOSに対応していますでしょうか。
Avatar
cybozu Development team

mm 様

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

こちらのツールは、Windows(64 bit 機)の OS で動作確認済です。
また、同様のエラーを再現できないため調査することが困難となっております。

重ねてのご案内にはなりますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
試してみてわからないなど、記事から派生した技術的なご質問は cybozu developer コミュニティをご活用ください。

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

Avatar
佐々木

cli-kintoneを実務で使用させて頂こうと思っているのですが、
エクスポートがうまく出来ないので、ご教授頂きたいです。
アプリデータを項目指定しないままで、エクスポートは出来るのですが、
添付ファイルなどがあり、うまく取り込めないので、項目指定をして、
必要な項目のみをエクスポートしようとしております。
その際、全項目エクスポートした時の「フィールドコード」を使用しているのですが、
「$id」「$revision」しかうまくエクスポートできないです。
他の「フィールドコード」はエクスポート項目指定しても無視されます。
日本語は使用できないとか、使用する為に何か必要、とかはございますでしょうか?
(もしかしたら、私のケアレスミスかもしれませんので、その時はご容赦ください)
お手数をおかけしますが、ご確認頂けましたら幸いです。
よろしくお願いいたします。

Avatar
cybozu Development team

佐々木 様

お世話になっております。cybozu developer network 運営でございます。

日本語のフィールドもご利用いただけますので、なにか指定の方法などがまちがっているのかもしれません。もう一度リファレンスやこの記事の内容をご確認いただきますようおねがいします。
(もしくは固有の環境問題ということも有りえます)

恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、どう指定すればいいかわからないなどありましたら、
ご質問はcybozu developer コミュニティをご活用ください。
その際は入力内容やエラー内容などを記載されるとより有志からの反応があるかとおもいます。

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

Avatar
佐々木

cybozu developer network 運営様

質問をしてしまって、申し訳ございませんでした。
cybozu developer コミュニティにて、
質問させて頂こうと思います。
ご回答、ありがとうございました。

Avatar
宮崎秀幸

画面上でのCSV出力/取込はできているので、本機能でカテゴリーをCSV出力/取込できるように出来ませんでしょうか。

Avatar
cybozu Development team

宮崎秀幸 様

お世話になっております。cybozu developer network 運営でございます。

こちらの制限事項(英語)にありますように、現在カテゴリーには対応しておりません。
> The following record data cannot be retrieved: Category, Status, Field group.

ご希望に添えず申し訳ございません。

 
 
 
Avatar
sakata m

お世話になっております。cli-kintone --exportでクエリを指定せずにCSV出力した際、出力したカラムの並び順の規則性が見えないのですが、どういった規則なのでしょうか?

Avatar
cybozu Development team

sakata m 様

お世話になっております。cybozu developer network 運営です。

cli-kintone でCSV出力される列の順番は、実行する度に異なります。これは不具合ではなくGo言語の仕様に起因するものです。

回避策として、エクスポートするフィールドを指定するを参照して -c オプションで列を固定できます。

Avatar
takashi.k

cli-kintone 便利に使わせていただいております。

が、インポートを実行している際、時々「データベースがロックされているため、操作に失敗しました。時間をおいて再度お試し下さい。」のメッセージでエラー、ストップしてしまいます。

言われた通り、時間をおいて再実行すると、正常に終了するので、操作手順に間違いはないと思うのですが、

上記エラーはどういった状況で、何故起こるのでしょうか?なにか対策があればご教示いただきたく、宜しくお願いします。

 

Avatar
cybozu Development team

takashi.k 様

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

お問い合わせいただきましたエラーは、kintoneの環境上で多数の処理が実行されている際に発生するエラーです。
様々な原因で起こりうるため、個別の発生原因については恐れ入りますがお答えしかねます。

ご認識いただいております通り、時間をおいて再度実行いただくようお願いいたします。

Avatar
Taka

特定のPCから今まで毎日実行出来ていたcli-kintone.exeですが、数日前から突然下記のエラーを返すようになってしまい、データがエクスポートできなくなりました。

※cli-kintone.exe実行時のエラーは、下記の通りです。

2021/09/24 10:05:21 Get https://XXXXX.cybozu.com/k/v1/form.json: x509: certificate has expired or is not yet valid.

このPCからWebブラウザを使って、上記のURLにアクセスすると、同様にアクセスできずません。ブラウザから証明書の内容を表示すると、上記と同じメッセージ「有効期限が切れているかまだ有効ではありません」と表示されます。しかし、その証明書に表示されている期限は、有効期間内です。

また、他のPCで同じexeを実行した場合、問題なくエクスポートできています。

どこを確認し、何を修正するべきか検討がつきません。ご教示頂ければ幸いです。

 

Avatar
cybozu Development team

Taka 様

お世話になっております。cybozu developer network 運営局です。

以下のことをご確認いただけないでしょうか。

  • 対象の PC のブラウザから、kintone にアクセスできること
    https://{Taka 様の subdomain}.cybozu.com/k/
  • PC の時刻設定があっていること
    PC の時刻設定が正しくない場合、「有効期限が切れているかまだ有効ではありません」と表示されることがあるようです。

また、cybozu.com にセキュアアクセスが設定されている場合、クライアント証明書を利用した cli-kintone の実行には対応しておりません。
アクセスが許可されたIPアドレスから cli-kintone を実行してください。

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

Avatar
Taka

cybozu Development team様

エラーが解消しました!!
ありがとうございます。

対象のPCのブラウザからもアクセスできず、ブラウザの証明書を見ると「有効期限が切れているかまだ有効ではありません」と表示されていました。有効期限も切れていました。

有効期限内のRoot証明書をインポートしたところ、
対象のPCからサイボウズにアクセス出来て、cli-kintone.exeもコマンドラインからエラーなく実行することが出来ました。

アドバイス頂き大変助かりました!

Takaにより編集されました
Avatar
nari

お世話になっております。
「-c オプションで列を固定できます」のご回答を拝見したのですが、指定した列の順番とCSVファイルの列の並びが違っていました。
指定した列の順番どおりの項目順でCSV出力する方法はありますか。

Avatar
cybozu Development team

nari 様

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

macOS 11.6 Big Sur 環境にて動作確認したところ、
-c オプションを用いることで列の並びを固定することができました。
今一度、nari 様の実行環境を見直していただけますでしょうか?

恐れ入りますがが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
記事から派生した技術的なご質問は cybozu developer コミュニティをご活用ください。

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

Avatar
nari

cybozu Development team様
バージョンが古かったようです。
v0.12.0をダウンロードしてで試したところ指定通りの順番でCSV出力できました。

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