在 kintone 應用程式中，我們常常會使用「附件」欄位來保存檔案，例如合約、報表或照片。除了透過 UI 介面直接上傳，kintone 也提供 REST API，讓開發者能以程式碼進行檔案上傳，這在自動化流程或與外部系統整合時特別實用。

不過，這個 API 在使用上有一些細節需要特別留意。本篇文章將介紹上傳檔案 API 的用法、常見問題與注意事項。

上傳檔案 API 基本資訊

使用此 API 上傳的檔案會先存放在 kintone 的暫存區，並回傳一組檔案鍵值 fileKey。之後必須搭配「新增記錄」或「更新記錄」API，才能將檔案正式附加到記錄的附件欄位中。

Endpoint

POST https://sample.cybozu.com/k/v1/file.json

Content-Type

multipart/form-data

回傳結果

成功時會取得一組 fileKey，取得後需搭配新增／更新記錄 API，才能將檔案正式添加至附件欄位中。
※僅有透過此 API 取得的 fileKey，才能搭配新增／更新記錄 API 使用。

使用範例

使用 JavaScript Fetch API

const blob = new Blob(['Sample Test File'], { type: 'text/plain' });
const formData = new FormData();

// 由於檔案上傳 API 使用 POST 方法，因此需要設定 CSRF Token
formData.append('__REQUEST_TOKEN__', kintone.getRequestToken());
formData.append('file', blob, 'test.txt');

const headers = { 'X-Requested-With': 'XMLHttpRequest' };

const resp = await fetch('/k/v1/file.json', {
  method: 'POST',
  headers,
  body: formData,
});

const respData = await resp.json();
console.log(respData);

使用 kintoneRestAPIClient

若是使用官方提供的 kintone REST API Client，可用 uploadFile 方法簡化操作：

const client = new KintoneRestAPIClient();

const resp = await client.file.uploadFile({
  file: {
    name: 'test.txt',
    data: blob,
  },
});

console.log(resp.fileKey);

注意事項與限制

• 一次僅能上傳一個檔案，若需要上傳多個檔案，需逐一呼叫 API。
• 暫存檔有效期為 3 天：若未在期限內搭配新增／更新記錄 API，檔案會自動刪除。
  （注意：暫存檔也會佔用磁碟空間）
• fileKey 有兩種，無法混用：
  • 上傳檔案 API 產生的 fileKey → 可用於新增／更新記錄
  • 讀取記錄 API 取得的 fileKey → 用於下載檔案
• 檔名注意編碼：若為日文或中文檔名，需使用 UTF-8 編碼。
• 上傳取得的 fileKey 僅能使用一次：透過新增／更新記錄 API 使用時，單一 fileKey 僅能添加至一個附件欄位一次。無法同時套用至多個附件欄位，亦無法重複使用於其他更新操作。

常見問題

可以直接複製記錄中的 fileKey 到另一個附件欄位嗎？

不行。
如前述，上傳檔案 API 產生的 fileKey 與記錄中已存在的 fileKey 並不相同，只能使用上傳檔案 API 回傳的 fileKey 搭配新增／更新記錄 API，才能將檔案正確附加到附件欄位。

若要將記錄中的附件複製到另一附件欄位，必須先透過「下載檔案 API」使用記錄中的 fileKey 下載檔案，再透過「上傳檔案 API」重新上傳，取得新的 fileKey，最後搭配新增／更新記錄 API 將其寫入另一附件欄位。

可以透過 event object 直接更新 fileKey 嗎？

不行。
event object 能改寫的欄位有限制，附件欄位並不支援此方式。若要將檔案寫入附件欄位，仍需透過新增或更新記錄 API，並使用上傳檔案取得的 fileKey。

相關限制可參考官方文件：
https://cybozu.dev/zh-tw/id/073cb99467614b140b2a9c42/#record-create-overwrite-field-values

結語

kintone 的上傳檔案 API 為開發者提供了靈活的檔案處理方式，特別適合應用於自動化流程或與外部系統整合。需要注意的是，僅有 fileKey 並不代表檔案已經寫入記錄，必須搭配新增／更新記錄 API 才能完成附件保存。同時，也要清楚區分「上傳 API 產生的 fileKey」與「記錄中已存在的 fileKey」，避免誤用造成錯誤。