カテゴリー内の他の記事

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

この記事では ver. 0.x.x の cli-kintone の使い方を紹介しています。 ver.1.0.0 以降の cli-kintone の使い方は、次のページを参照してください。
kintone コマンドラインツール(cli-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です。
  • 次のフィールドはエクスポートできません。
    • ステータス
    • 作業者
    • カテゴリー
    • 関連レコード
    • グループ
      グループフィールド内のフィールドはエクスポートできます。
    • フォームを装飾するフィールド(スペース、ラベル、罫線)
  • 次のフィールドにインポートしても値は登録・更新されません。
    • ルックアップ元からコピーされるフィールド
    • 計算
    • 自動計算が設定されている文字列(1行)フィールド
    • ステータス
    • 作業者
    • カテゴリー
    • 作成者
    • 作成日時
    • 更新者
    • 更新日時
    • 関連レコード
    • グループ
      グループフィールド内のフィールドはインポートできます。
    • フォームを装飾するフィールド(スペース、ラベル、罫線)

おわりに

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

関連Tips

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

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

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

Avatar
K.otsuki

<質問①>

cli-kintone.exeを使用して、コマンドラインからフィールドを

指定してエクスポートを実施していますが、-cオプションを

使用しないと全フィールドが出力されますが、-cでフィールドコード

を指定すると何も出力されません。

フィールドコードは添付の赤枠を指定しています。

アプリID、ドメイン、APIトークンはダミーです。

後のコマンドは実物です。

<実行コマンド>

cli-kintone.exe --export -a 99 -d test -t 9ZxiUytrempInM78UI -e sjis > c:\test\Kintone.csv -c  "処理年月日"

<質問②>

コマンドをバッチファイルにしてWindowsのタスクスケジューラで実行してもデータはエクスポートされません(実行されない)が、バッチファイルをダブルクリックかコマンドプロンプトから実行した場合にはデータはエクスポートされます。何か違いがあるのでしょうか。

目的はサーバーでWindowsタスクスケジューラで実行したいと

思っています。

ご教授頂ければと思います。

Avatar
cybozu Development team

K.otsuki

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

質問①ですが、フィールドコードは正しいでしょうか?ご提示いただいている実行コマンド上は、「処理年月日」とありますが、添付頂いている画像上のフィールドコードは「出勤時刻」となっています。

質問②については、お客様固有の環境や、記事から派生した技術的なご質問となりますので、cybozu developer コミュニティをご活用ください。
その際バッチファイルの内容など詳細がありますと有志のメンバーが答えやすいかと存じます。
コミュニティを確認したところ、タスクスケジューラ利用で想定通り動作をすることができている他のユーザー様はいらっしゃるようでした

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

 

Avatar
cybozu Development team

Ten 様

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

長らく返答をお待たせし、申し訳ありません。

cli-kintone の v0.14.0正式リリース版にて、下記の動作が実装されたことを確認できました。
プレリリース版では誤った情報をお伝えしたことをお詫び申し上げます。
今後ともよろしくお願い申し上げます。

---

Go言語の仕様に基づく挙動から、フィールドの一覧を取得する API(/k/v1/app/form/fields.json) のレスポンスに基づく挙動になります。
その結果、「実行するたびに変わる」状態ではなくなります。

ただし、次の点はご注意いただければと思います。

  • 仕様として順番の固定を保証するものでないこと
Avatar
Ten

cybozu developer network 運営様
いつもお世話になっております。
ご連絡ありがとうございます。動作確認できました。
注意点についても承知いたしました。
今後ともよろしくお願いいたします。

Avatar
kfuji

cybozu Development team様

お世話になっております。
cli-kintone.exeを使用して、アプリデータの作成日時及び更新日時を取得した際、
日時を日本時間で出力したいが、出力可能か否かを教えて頂きたいです。
また、デフォルトで出力される日付のフォーマットは「YYYY-MM-DDTHH:MM:SSZ」(TとZは固定)となりますが、
「YYYY-MM-DD HH:MM:SS」のようなフォーマットでエクスポートすることは可能でしょうか。
可能であればその手順を教えていただきたいです。

Avatar
cybozu Development team

kfuji 

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

日時の出力はUTC(YYYY-MM-DDTHH:MM:SSZ)限定となっており、
出力されたデータからご自身で任意のフォーマットに変換いただくこととなります。

例えばExcelであればこちらのサイトで紹介されているようにJSTなどに変換は可能です。

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

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

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