cli-kintone v0将于 2023 年 10 月 31 日停止维护，请使用 2022 年 10 月 24 日发布的 v1.0.0 或更高的 cli-kintone 版本!

Index

• kintone命令行工具是什么

• 下载命令行工具

• 确认选项列表

• 通过用户名/密码获取并显示kintone数据

• 使用API令牌

• 用GBK文字编码导出到CSV文件

• 指定要导出的字段

• 指定筛选条件和排序

• 从文件导入数据

• 导出或导入表

• 上传或下载附件

• 限制事项

• 最后

• 相关Tips

kintone命令行工具是什么

kintone命令行工具是指可以通过命令行来方便地将数据导入到kintone或从kintone里导出。
用kintone的标准功能，可将Excel或CSV文件里的数据导入到kintone。但以下操作无法做到，只能使用命令行工具来完成。

• 批量下载记录内的附件文件

• 批量上传附件到记录里

结合Shell脚本使用的话，可以定期执行kintone数据的导入或导出。
对kintone命令行工具的使用方法感兴趣的同学，请参考入门篇kintone 命令行工具（日语）。

下载命令行工具

可从以下链接中下载kintone命令行工具。
提供有Windows/MacOSX/Linux的执行文件。
下载后，请解压到任意文件夹。本篇介绍在Windows上的使用方法。

Releases kintone/cli-kintone　(Github)

确认选项列表

如果未指定任何参数直接执行，将显示可使用的选项列表。

通过用户名/密码获取并显示kintone数据

以下范例中，域名为sample.cybozu.cn、应用ID为999。

>cli-kintone.exe --export -a 999 -d sample -u bozuman    
Password:

输入bozuman用户密码，所有字段数据将以CSV格式导出。
如要以JSON格式显示，请指定-o json。 如需要中途退出，按CTRL+C。

结果显示如下

*,"$id","$revision","入职时间","部门","姓名","表格","调动记录","调动前部门","记录编号","创建人","创建时间"
*,"7","3","2020-02-07","营业","李四","1782","2019-12-17","市场部","7","aki","2020-02-07T01:08:00Z"
*,"6","4","2016-02-10","开发部","陈飞","1783","2020-02-12","","6","aki","2020-02-07T01:00:00Z"
*,"5","4","2006-02-07","人事部","周世杰","1784","2020-02-12","行政部","5","aki","2020-02-07T00:58:00Z"

使用API令牌

如使用API令牌，无需输入密码即可导入或导出数据。
API令牌在“应用的设置” > “API令牌”中发行。请根据要执行的操作给API令牌设置相应的权限。

>cli-kintone.exe --export -a 999 -d sample -t c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3

※ 如果要添加或更新的数据中含有Lookup字段，不可使用API令牌。
请使用用户名/密码。

用GBK文字编码导出

kintone在默认情况下按UTF-8导出字符串数据。
使用-e选项可以指定要导出的文字编码。

>cli-kintone.exe --export -a 999 -d sample -t c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3 -e gbk

执行结果重定向到CSV文件

如下，使用 “>“ 可将cli-kintone的执行结果重定向给CSV文件。

重定向不是cli-kintone 的功能，是一般命令行工具自带的功能。根据OS不同，使用方法和输出结果也不一样。

>cli-kintone.exe --export -a 999 -d sample -t c4vIhZ2pez5BhthY3j796pCsv117qyGTx7lHYKM3 -e gbk > sample.csv

指定要导出的字段

使用-c选项，可指定要导出的字段。

• 如要导出表格的值，请指定表格的字段代码（不可指定表格内的字段的字段代码）。

>cli-kintone.exe --export -a 999 -d sample -u bozuman -c "$id,入职时间，姓名,部门"

"$id","入职时间","姓名","部门"
"7","2020-02-07","李四","营业"
"6","2016-02-10","陈飞","开发部"
"5","2006-02-07","周世杰","人事部"

指定筛选条件和排序

使用-q选项，可以指定筛选条件和排序。
关于条件的写法请参考此处。

>cli-kintone.exe --export -a 999 -d sample -u bozuman -c "$id,姓名,入职时间,部门" -q "入职时间 > \"2014-12-01\" order by 入职时间 asc"

"$id","入职时间","姓名","部门"
"6","2016-02-10","陈飞","开发部"
"7","2020-02-07","李四","营业"

从文件导入数据

更新现有数据

要更新现有数据，需要在CSV文件中添加$id列。

以下是要将周世杰的所属部门改为策划部门，陈飞的所属部门改为人事部的CSV文件例子

"$id","姓名","部门"    
"6","陈飞","人事部"    
"5","周世杰","策划部"

>cli-kintone.exe --import -a 999 -d sample -u bozuman -e gbk -f sample.csv

如果要通过$id以外的特定字段来更新记录，需要在CSV文件的首行中，在要作为更新key的字段代码前面添加"*"标记。

这种情况，作为更新key的字段要设置为“值为唯一”。
以下使用员工号来更新记录时的CSV文件例子

"*员工号","姓名","部门"    
"0001","周世杰","人事部"    
"0002","陈飞","策划部"

>cli-kintone.exe --import -a 999 -d sample -u bozuman -e gbk -f sample.csv

新添加记录

如CSV文件中没有$id列，或者$id列的值为空，相应行将作为新记录添加。

"姓名","部门","入职时间"    
"张三","测试部","2014-08-11"

>cli-kintone.exe --import -a 999 -d sample -u bozuman -e gbk -f sample.csv

执行上面操作后的结果如下：

"$id","入职时间","姓名","部门"
"8","2020-03-17","张三","行政部"
"7","2020-02-07","李四","营业"
"6","2016-02-10","陈飞","策划部"
"5","2006-02-07","周世杰","人事部"

删除现有数据后再添加

指定-D选项，可先删除现有的所有记录，之后再添加数据。

导出或导入表

导出

导出含有表格的记录时，1条记录的内容分多行导出。以下是CSV数据的导出结果。

*,"$id","入职时间","姓名","部门","表格","调动时间","调动前部门"
*,"17","2020-03-17","张三","行政部","1795","2020-03-17",""
*,"7","2020-02-07","李四","营业","1782","2019-12-17","市场部"
*,"6","2016-02-10","陈飞","策划部","1783","2020-02-12","客服部"
*,"5","2006-02-07","周世杰","人事部","1784","2020-02-12","行政部"
,"5","2006-02-07","周世杰","人事部","1796","2015-03-19","法务部"

此例子中，[调动时间]字段和[调动前部门]字段是表格。
导出的CSV中，第一行第一列输出"*"标记，之后才是各字段的字段代码。
第二行起，如果存在未标记"*"的行，说明是表格第二行及之后的数据。
上面的CSV数据中，导出了4条记录。
记录编号为5的记录中包含了2行表格数据，表格内字段是【调动时间】和【调动前部门】，因此在CSV中分两行输出。

导入

导入时也一样，第2行之后，未标记"*"的行将作为表格的第二行及之后的数据导入。
忽略前面未标注"*"，且不是表格行的值。

上传或下载附件

下载

用-b选项指定下载的文件的保存目录。文件夹不存在时，将自动生成。
下面例子中，“照片”字段的字段类型为附件。

>cli-kintone.exe -a 999 -d sample -u bozuman -c "$id,姓名,照片" -b download

"$id","姓名","照片"
"17","张三","照片-17\zhangsan.png"
"7","李四","照片-7\lisi.png"
"6","陈飞","照片-6\chenfei.png"
"5","周世杰","照片-5\zhoushijie.png"

指定-b选项时，附件字段的值是所下载的文件从download文件夹起的相对路径。

附件将分别被保存到download文件夹下的<附件字段代码>-<字段编号>这个文件夹中。
另外，如指定了-c选项，要导出的字段中如不包含"$id"或者"记录编号"字段，附件保存在download文件夹下的<附件字段代码>-<Index(※)>文件夹里。

※Index根据要获取的记录条数， 从0开始递增。
例）要获取的记录为3条
<附件的字段代码>-0
<附件的字段代码>-1
<附件的字段代码>-2

上传

和下载时一样，用-b选项可以指定要上传的文件夹。
CSV文件中要输入的值是从上传文件夹起的相对路径。

>cli-kintone.exe -a 999 -d sample -u bozuman -b upload -f sample.csv

指定多个附件时，用CR字符（如果是Microsoft Excel，用ALT+Enter键输入）间隔各文件。

"$id","姓名","照片"
"5","周世杰","照片-5\zhoushijie1.png
照片-5\zhoushijie2.png"

如要删除记录的附件，只要将要删除的附件字段的值设为空白。

如要删除多个附件中的其中一部分，只要在文件中输入要保留的文件的文件名即可。

下面例子中，将删除$id为5的记录内的一张照片。

"$id","姓名","照片"
"5","周世杰","照片-5\zhoushijie1.png"

限制事项

• 在安装了客户证书的SecureAccess的环境下无法操作。
  在设置了IP地址限制的环境里，只能用允许访问的IP来使用此工具。

• 可上传的每个附件的大小上限为10MB。

• 以下字段不可导出

  • 状态

  • 执行者
    

  • 分类

  • 关联记录
    

  • 组合
    组合内的字段可以导出。

  • 装饰表单的字段（空白栏、标签、边框）

• 以下字段即使导入了，也不会对其进行更新或添加。

  • 从Lookup来源字段复制值的字段

  • 计算

  • 设置了自动计算的单航文本框

  • 状态

  • 执行者

  • 分类

  • 创建人

  • 创建时间

  • 更新人

  • 更新时间

  • 关联记录

  • 组合
    组合内的字段可以导出。
    

  • 装饰表单的字段（空白栏、标签、边框）

最后

命令行工具因为需要用到REST API，因此需要标准版才可使用。
请注意，对大数据量进行操作时会给kintone带来很大的负荷，会对性能产生影响。

相关Tips

• 通过定期执行来实现数据同步的简单方法（日语）

• kintone命令行入门系列（分几篇文章来详细介绍kintone命令行工具的使用方法）（日语）

此Tips在kintone-ci Ver 0.14.0 和2022年8月版中确认过。