kintone 命令行工具的使用方法(cli-kintone v0)

aki发表于:2019年12月20日 12:18:02更新于:2023年07月28日 09:47:09

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

Index

kintone命令行工具是什么

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

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

  • 批量上传附件到记录里

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

下载命令行工具

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

Releases kintone/cli-kintone (Github)

确认选项列表

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

0016322bef2ce7263cb744879668941

 

选项说明
--export要从kintone导出数据时使用此选项。
数据按照标准格式输出(显示在console里)。
--import要将数据导入到kintone时使用此选项。
数据按照标准格式导入。
使用-f 选项可以从特定的文件中导入数据。
-d域名(必须)cybozu.com可省略。
使用FQDN可指定cybozu.com 以外的域名(kintone.com, cybozu.cn) 。
-a应用ID(必须)
-u登录名称(须要API令牌或者登录名称)
-p密码
-tAPI令牌(须要API令牌或者登录名称)
-g如果是来宾空间内的应用,要指定来宾空间的ID。
-o输出格式。可指定'json'或'csv'。默认'csv'。
-e文字编码。默认UTF-8。日文指定'sjis',简体中文导入导出时指定gbk,繁体中文指定big5。
-UBASIC验证用户名称
-PBASIC验证密码
-q

条件公式。关于条件的写法请参考此处
当指定了选项并且不包括“Limit”或“offset”时,将使用游标API执行该处理。

-c要导出多个字段时用逗号隔开。
-f导入数据时,指定要导入的文件名称。
-b指定附件要下载到哪个目录或从哪个目录上传文件。
-l从文件导入数据时,指定导入开始行。
指定了此选项时,将从所指定的行开始导入数据。
-D导入时如指定了该选项,将删除原有的记录再进行导入数据。

通过用户名/密码获取并显示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中分两行输出。


0016347ac010fc86f650b3339881841

导入

导入时也一样,第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

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