カテゴリー内の他の記事

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

Hitoshi Hayakawa 様

解決しそうだということで良かったです。
今後ともcybozu developer networkをよろしくお願いいたします。

Avatar
cybozu Development team

shu kobayashi 様

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

はい、kintone コマンドラインツールについてもoffsetの上限値制限の影響がございます。
kintone コマンドラインツールが受ける影響に関して、開発チームにて対応を予定しています。

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

Avatar
kuma

いつもお世話になっております。csvからデータをインポート(新規登録)しようとしています。

下記の記載

「レコード番号以外の特定のフィールドでレコードを更新するには、CSVファイルのヘッダ行にあるフィールドコードの先頭に更新キーを表すマーク"*"をつけます。」

に従ってフィールドコードの先頭に更新キーを表すマーク"*"をつけていますが、

Status: 404 Not Found
Message: 「updateKey」に指定した条件にあてはまるレコードが見つかりません。
Errors detail: (none)

というエラーが出てしまいます。

該当のCSVでは行数は1行だけで、新しいレコードをアプリに追加しようとしています。そのため、CSV内のupdatekeyは該当のアプリにはまだ存在しません。

cli-kintoneではcsvからレコードを新規登録することはできないのでしょうか?

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

Seki 様

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

更新ではなく、新規登録する場合は、更新キーを指定する必要がございません。

詳細は「ファイルからデータをインポート」の「新規にデータを登録する」をご参考ください。

Avatar
Yasu.Nakashima

こんにちわ。

コマンドラインツールを使ってkintoneからデータをGETする機能を作っています。

簡単にデータ取得の流れは、以下の通りです。

 EXCELからマクロ実行→バッチ実行→cli-kintoneにて指定したkintoneアプリからデータ取得→取得データをCSVでファイル出力

 

取得自体は問題なく出来ています。

けれど、取得レコードを特定の文字列フィールドの値で絞り込みたいのですが、

「クエリ記法が間違っています。」とエラーになり、うまくいきません。

クエリ記法について御教授願えないでしょうか。

 

実行しているコマンドは以下のようなものです。

 cli-kintone.exe -a 1 -d https://testtestabcabc.cybozu.com/ -u testuser -p pass -c="$id,hiduke,hinmei,user,status" -q="作成日時>=LAST_MONTH(1) and sakujo !=削除 order by hiduke asc" -e="sjis" > test.csv

 

フィールドコード「sakujo 」の値が「削除」でないレコードを取得したいです。

当フィールドはドロップダウンで、用意した項目は1つで「削除」、初期値は「------」です。

ドロップダウンですので、

 -q="作成日時>=LAST_MONTH(1) and sakujo not in (""削除"") order by hiduke asc"

といったコマンドも試してみましたが、同様の結果でした。

 

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

Avatar
cybozu Development team

Yasu.Nakashima 様

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

クエリ記法につきましては以下の記事を参考に記述ください。
https://developer.cybozu.io/hc/ja/articles/202331474#step2

ご認識の通りドロップダウンフィールドについては、
上記のリンク先にも記載の通り、=, != は使用できません。

ドロップダウン in ("値") で指定可能ですが、コマンドラインツールでは 「"」はエスケープする必要があります。

コマンドプロンプトの場合は以下の通り、「\」でのエスケープです。

ドロップダウン in (\"値\")

パワーシェルの場合は以下の通り、「\`」でのエスケープが必要になります。

ドロップダウン in (\`"値\`")

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

Avatar
Yasu.Nakashima

cybozu Development team 様

 

御回答頂き、ありがとうございます。

基本的な知識が欠けており、申し訳ございません。

エスケープすることで問題なくレコードを絞り込んで取得する事が出来ました。

Avatar
Midori Koyama

いつもお世話になっております。

コマンドラインツールを使用して、全アプリデータのバックアップ機能を作成しております。

添付ファイルのエクスポートで、ファイル名に「~」が入っているファイルの出力時に、処理が止まってしまいます。

元データのファイル名を修正する以外に、コマンドツール側でこの問題を回避する方法はありますでしょうか。
 
よろしくお願いいたします。
Avatar
cybozu Development team

Midori Koyama 様

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

こちらの方で、windows 10, mac, 最新版 cli-kintone で動作確認したのですが、
同様の現象を確認できませんでした。

お手数ですが、cli-kintone を最新版にしていただき、再度ご確認ください。
現象が続く場合は、ご使用環境(OS, コマンドラインツール名)を共有いただけないでしょうか。

以上、お手数ですがよろしくお願いいたします。

Avatar
Midori Koyama

cybozu Development team 様

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

再度確認した結果、「~」が原因ではなく「<>」が問題であることがわかりました。大変失礼いたしました。

原因の添付ファイルのファイル名は帳票プラグインで自動生成しているため、

プラグインの開発元に問い合わせて対応いたします。

この度は大変お手数おかけいたしました。

Avatar
cybozu Development team

Midori Koyama 様

ご連絡ありがとうございます。

承知いたしました。
今後とも cybozu developer network をよろしくお願いいたします。

Avatar
江口 和志

Powershellからコマンドラインツールを使って添付ファイルをダウンロードしようとしているのですが、

そうしてもクエリの記述がうまくいきません。

-q 'ステータス = "申請中 (決裁待)"' や

-q '"ステータス = "申請中 (決裁待)""' など

複数ためしましたがどうしても記法が間違っていますとなります。

どのように記載すればいいのでしょうか?

Avatar
cybozu Development team

江口 和志 様

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

こちらのコメント欄は記事内容のフィードバック目的となっており、
記事とは直接関係がない、または技術的なご質問はcybozu developer コミュニティをご活用ください。
有志により回答が得られる場所となります。

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

Avatar
kuma

cybozu Development team 様

いつもお世話になっております。

制限事項の「セキュアアクセス環境には対応していません」の箇所について質問です。

もう少し詳細にお聞きしたいのですが、セキュアアクセス環境には対応していませんとは具体的にどのようなシチュエーションなのでしょうか。

例えば10アカウント保有していて、そのうち5つのアカウントのみセキュアアクセスを設定していた場合、

セキュアアクセスの証明書を入れたPCでは使えないということでしょうか?あるいはセキュアアクセスを導入したドメインでは全く使えないという

ことでしょうか。教えてください。

 

Avatar
cybozu Development team

kuma 様

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

セキュアアクセスを設定したドメインにて、kintoneへのアクセスにクライアント証明書が必要な状況下ではご利用いただけません。

例えば、セキュアアクセスを設定した環境にてIPアドレス制限で社内IPアドレスのみ許可としている場合、
 社内での利用:利用可
 社外での利用:利用不可
となります。

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

Avatar
Huan Wang

cybozu developer network運営チーム

お疲れ様です。

 

1行目が「フィールド名」ではなく「フィールドコード」が書き出されてしまいます。
(そのため、出力したCSVを再度kintoneに取込む際にフィールドの対応付けが自動的に行われません)
「フィールド名」を出力するオプションは無いのでしょうか。

 

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

Avatar
cybozu Development team

Huan Wang 様

フィールド名を出力するオプションはありません。

出力したCSVを利用してkintoneにレコード登録する方法は以下の記事に詳細がありますので、よろしければご参考ください。

https://developer.cybozu.io/hc/ja/articles/115000717706

Avatar
Okamoto

コマンドラインツールでファイルからインポートする際に、ある項目をキーとしてレコードが「存在していたら更新」「無ければ新規追加」ということはできますでしょうか。

標準の機能ですと、ファイルから読み込む のメニューから「一括更新のキー」を指定・・・の機能と同じことがしたいです。

 

Avatar
cybozu Development team

Okamoto 様

ご質問いただきましたアップサート機能ですが、 cli-kintone には搭載されておりません。

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

Avatar
Okamoto

cybozu Development team様

回答ありがとうございます。承知しました。

 

Avatar
kwsht

コマンドラインツールを使ってkintoneからCSV形式でエクスポートしたいのですが、フィールドが意図しない並び順となりエクスポートされてしまいます。

フィールドにテーブルは使用していません。また、-cオプションは使用せず、すべてのフィールドを書き出したいです。

並び順には規則性がなく、またコマンドラインツールを実行するたびに並び順が変化します。

想定される原因についてご教示いただけますと幸いです。

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

kwsht 様

遅くなりましたが、調査結果を回答いたします。

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

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

ご不便をおかけしますがよろしくお願いいたします。

Avatar
kwsht

cybozu Development team様

ご回答ありがとうございます。承知いたしました。

追加で申し訳ございません。-c オプションで指定可能なフィールド数に制限値はありますでしょうか。

(50個程度のフィールド数定義を想定しています。本問い合わせと併せて、実機確認をいたします)

Avatar
cybozu Development team

kwsht 様

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

ご質問いただきましたフィールド数の上限値ですが、1000フィールドになります。
( レコード取得APIの制限により)

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

Avatar
kwsht

cybozu Development team様

ご回答ありがとうございます。大変参考になりました。改めまして御礼申し上げます。

Avatar
Nishimoto

いつもお世話になっております。
コマンドラインツールを使ってcsv書き出しを行ったのですが、エラーになります。
現象:
プロキシ認証が必要な環境でHTTPS_PROXY環境変数を設定した後、cli-kintoneコマンドを実行したところ、「411 Length Required」が発生しました。
コマンド:
C:\xxxxxx>set HTTPS_PROXY=https://[ユーザー名]:[パスワード]@[ホスト名]:[ポート番号]
C:\xxxxxx>scli-kintone.exe -a アプリID -d ドメイン -u ログイン名 -p パスワード -e sjis -c "$id,Spec_No" > リダイレクトするファイル名
("Spec_No"はルックアップフィールドのフィールドコードです)
結果:
YYYY/MM/DD hh:mm:ss HTTP error: 411 Length Required

弊社ではPutのアクセス制限をしているのですが、コマンドラインツールはPutを使用しておりますか?
どのような処理が行われているかを知りたいです。
また、もし、「411 Length Required」が起きた際の解決策があればご教示いただけますと幸いです。

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

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

Nishimoto 様

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

411 Length Required のエラーですが、 cli-kintone が出力するエラーではなく、
送信されたリクエストにContent-Lengthヘッダが含まれていない場合に、返されるステータスコードです。

プロキシサーバーの設定有無によってエラーが変化する場合、
cli-kintoneの実行マシンから、インターネットに出るまでの通信経路(プロキシサーバーなど)を調査する必要があると思います。

> 弊社ではPutのアクセス制限をしているのですが、コマンドラインツールはPutを使用しておりますか?

export コマンドの場合は PUT を使用しておりません。

以上、ご確認お願いいたします。

Avatar
Nishimoto

cybozu Development team様

ご回答ありがとうございます。頂きました情報をもとに確認を行ってみます。
ありがとうございました。

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