上一篇文章 工具安装攻略：带你完成 cli-kintone 的安装 安装好后，这篇就一起来操作 cli-kintone，将各种包含附件的纪录汇入汇出。从官网中可以看到以下几种操作：

  • record export：汇出纪录
  • record import：汇入纪录
  • record delete：删除纪录
  • plugin info：查看外挂详情（开发阶段）
  • plugin pack：打包外挂（开发阶段）

在撰文当下（2025/02），plugin info 以及 plugin pack 还在早期开发阶段，而且这两个功能是针对开发者的，所以本篇文章会跳过这两个功能，只针对纪录操作。

事前準备

开始之前，先来建立练习用的应用程式，我们先在应用程式内新增以下栏位：

  • 单行文字方块
  • 附件栏位
  • 表格
    • 表格内的单行文字方块
    • 表格内的附件栏位

为了方便辨识，记得改个栏位名称，另外也新增几笔纪录，在附件栏位内放入一些档案。

汇出（Export）

首先来看纪录的汇出，我们在官网找到范例：

cli-kintone record export \\
--base-url https://${yourDomain} \\
--api-token ${apiToken} \\
--app ${kintoneAppId} \\
> ${filepath}

我们只要把上面范例的值替换成自己环境的 domain、token、app id 等资讯即可，最后的 ${filepath} 则是输出后的 csv 档案，因此经过修改后变成：

cli-kintone record export \\
--base-url https://brown.cybozu.com \\
--api-token pYpEfdnqB1tVI2VhhWQYSN71dBHqunfYpNLn6Cv2 \\
--app 20 \\
> test.csv

左边的 --xxx 就是参数，只要将对应的值放到右边即可，\\ 则是换行符号，当然可以再补上自己需要的参数，例如排序 --order-by、访客空间 --guest-space-id、输出栏位 --fields 等等，全部的参数选项，可以参考以下连结：

https://cli.kintone.dev/guide/options/

回到范例。因为我们还要输出附件，所以再补上新的参数 --attachments-dir，同时指定输出的资料夹，就会变成：

cli-kintone record export \\
--base-url https://brown.cybozu.com \\
--api-token pYpEfdnqB1tVI2VhhWQYSN71dBHqunfYpNLn6Cv2 \\
--app 20 \\
--attachments-dir ./cli-kintone-files \\
> ./cli-kintone-files/test.csv

以上会将输出的附件及 csv 统一放到名为 cli-kintone-files 的资料夹中。接着我们开启终端机后直接复制贴上，就会看到输出后的档案：

会输出的这样的格式，主要是因为附件档案会建立各自的资料夹，并遵循以下输出路径：

  • 输出的资料夹/栏位id-纪录编号/档案名称
  • 若有相同附件名称，则会变成在档名后方加入数字，例如 dog(2).jpg。

提醒：再次汇出并不会删除原本的档案，只有 csv 会被取代成新的，因此如果有重新汇出的需求，建议先将资料夹整个清空，不然就会变成以下情况。

汇入（Import）

跟汇出的指令一样，只是带的参数稍有不同。汇入的时候最重要的是 有没有带 --update-key，如果有填的话代表这次的汇入是要涵盖更新，反之则是新增。

为什么会说是涵盖？因为如果 --update-key 没有比对到 csv 的纪录，则该笔纪录会以「新增」的方式汇入。

以下是范例：

cli-kintone record import \\
--base-url https://sally.cybozu.com \\
--api-token pYpEfdnqB1t4I4VhhWQYSN71dBHqunSYpNLn23Cb \\
--app 183 \\
--attachments-dir ./ \\
--update-key 记录号码 \\
--file-path ./test22.csv

csv 则是：

以上指令指定了 --update-key 为「记录号码」，因此会比对 csv 上的档案将这三笔资料做更新，并且在终端机会看到成功的讯息：

[2025-02-04T10:03:27.881Z] INFO: Preparing to import records...
[2025-02-04T10:03:28.593Z] INFO: Starting to import records...
[2025-02-04T10:03:30.438Z] INFO: Imported 3 records successfully

如果新增了一笔没有比对到 --update-key 的资料，则该笔资料会以「新增」的方式汇入到 kintone。

一样会成功：

[2025-02-05T05:50:00.868Z] INFO: Preparing to import records...
[2025-02-05T05:50:01.446Z] INFO: Starting to import records...
[2025-02-05T05:50:03.127Z] INFO: Imported 4 records successfully

注意事项：--update-key 只能指定为 纪录编号、或是唯一值的单行文字方块/数字栏位。

再来我们试试看用新增的方式汇入，将指令的 --update-key 删除，重新输入后，会得到一个错误：

[2025-02-05T06:01:52.365Z] INFO: Starting to import records...
[2025-02-05T06:01:53.939Z] INFO: Imported 0 of 4 records successfully
[2025-02-05T06:01:53.940Z] ERROR: Failed to add all records.
[2025-02-05T06:01:53.940Z] ERROR: No records are processed successfully.
[2025-02-05T06:01:53.940Z] ERROR: An error occurred while processing records.
[2025-02-05T06:01:53.940Z] ERROR: [400] [GAIA_UN10] Cannot update field whose type is RECORD_ID. (QSvju4wp6ewE4lE2xLYa)

原因是「纪录编号」是 RECORD_ID，我们还没将 csv 的纪录编号栏位删除，所以发生了错误，只要把该栏从 csv 删除就可以汇入成功了。

附件的更新

其实上面的指令就有偷渡汇入附件了，就是 --attachments-dir 参数，这个代表的附件的目录位置，如果终端机目前在 Desktop，要上传的附件目录在 images 资料夹，就要写成：

// 目前位置在 Desktop

cli-kintone record import \\
--attachments-dir ./images/ \\
下略...

之后在 csv 中附件栏位写上档名就可以，其实只要自己把路径填好就可以。

多个档案汇入

如果一个附件栏位有多个档案要上传，直接在 csv 中将档案换行写上就可以，如下：

删除（Delete）

删除最简单，直接看范例：

cli-kintone record delete \\
--base-url https://${yourDomain} \\
--api-token ${apiToken} \\
--app ${kintoneAppId} \\
--file-path ${filepath}

--file-path 会是最重要的参数，若该参数没带，代表这个 app 的全部资料都被删除，因为没被指定。

--file-path 必须是一个 csv 档案，内容包含要删除的纪录编号，例如以下，只会删除编号是 25 的纪录：

并且在终端机会再次询问是否删除：

? Are you sure want to delete records? yes
[2025-02-07T02:11:32.905Z] INFO: Starting to delete records...
[2025-02-07T02:11:33.775Z] INFO: 1 records are deleted successfully

如果不希望他询问你，可以带上参数 --yes 变成 force delete：

cli-kintone record delete \\
--base-url https://${yourDomain} \\
--api-token ${apiToken} \\
--app ${kintoneAppId} \\
--yes \\
--file-path ${filepath}

以上就是 cli-kintnoe 的操作方式，希望大家可以活用该工具！