在使用 kintone 建置庫存管理系統、預約申請系統時，經常會遇到兩個共通的挑戰：

1. 多人同時操作
2. 跨多個應用程式進行資料更新

只要其中一個環節沒有妥善處理，就可能導致資料不一致的問題，例如：

• 庫存數量被算錯，出現「超賣」
• 同一時段被重複預約
• 一個應用程式成功更新，另一個卻失敗，留下不完整的資料

為了處理這類「需要同時更新多筆、甚至跨多個應用程式資料」的需求，kintone 提供了 bulkRequest API，讓多個 REST API 請求可以被當成「同一次處理」來執行。

本文將以庫存管理為例，說明在實務上可能遇到的問題，以及如何搭配 bulkRequest + revision，確保資料的一致性。

Bulk Request

bulkRequest 是什麼？可以做什麼？

一次對多個應用程式執行多個 API

bulkRequest 允許你在一次呼叫中，對多個應用程式同時執行多個 kintone REST API。官方文件列出的可執行 API 包含：新增/更新/刪除記錄、更新狀態、更新作業者等。

🔗 官方文件：Bulk Request

上限：最多 20 個 request

一次 bulkRequest 最多可以放 20 個子請求。

失敗就回滾（Rollback）

bulkRequest 的重要特性是：
只要其中一個子請求失敗，後續子請求不會執行，並且整組處理會回滾。

本文後續將介紹的庫存範例，就是靠這個特性確保「出入庫紀錄」與「在庫數」不會只更新一半。

API 端點與注意事項

URL

• 一般網域（非訪客空間）
  https://{subdomain}.cybozu.com/k/v1/bulkRequest.json
• 訪客空間 https://{subdomain}.cybozu.com/k/guest/{GUEST_SPACE_ID}/v1/bulkRequest.json

⚠️ 訪客空間限制

bulkRequest 只能對「同一個訪客空間內」的應用程式做批次處理；不能跨訪客空間、也不能把訪客空間 app 跟一般 app 混在同一次 bulkRequest。

權限與認證重點

所需權限

所有執行子請求 API 所需要的權限。
（本質上就是「你要執行的那些 API 本來就需要的權限」。）

若使用 API Token 操作多個 app

需要準備各 app 的 token，並在 header 一次帶多組 token。

request/response 結構

Request body 格式

bulkRequest 的 body 核心只有一個：requests 陣列，每個元素包含：

• method：HTTP method
• api：要呼叫的 API 路徑（例如 /k/v1/record.json）
• payload：該 API 原本要送的 body

Response 格式與「空物件」的意義

回傳會 results 陣列，陣列中包含每一個請求的 result 物件，順序與 requests 一致。

• 全部成功：每個 result 物件都會有對應 API 的結果
• 只要有一個失敗：
  失敗那個 result 物件會有 error 內容，其他會是 {}（空物件）

範例：可能發生的問題（以庫存管理為例）

假設我們有以下兩個應用程式：

• 「庫存管理」：用來管理每個商品目前的庫存數量
• 「出入庫記錄」：用來記錄每一次的入庫或出庫操作

每次進行出入庫時，實際上都需要同時完成兩件事：

1. 在「出入庫記錄」應用程式新增一筆記錄
2. 更新「庫存管理」應用程式中更新對應商品的庫存數量

問題一：同時更新造成的衝突

假設商品 A 目前的庫存數是 10 個。

正常情況下，如果依序進行以下操作：

• 山田入庫 5 個 → 庫存變成 15
• 鈴木出庫 8 個 → 庫存變成 7

結果是合理的。

但如果兩個人幾乎同時操作，流程可能變成這樣：

1. 山田確認庫存 → 10
2. 鈴木確認庫存 → 10
3. 山田將庫存 +5 → 15
4. 鈴木將庫存 -8 → 2

最終庫存變成 2 個，完全忽略了山田的入庫操作。
這正是典型的「同時更新導致資料被覆蓋」的問題。

問題二：跨 app 更新失敗，資料不一致

再來看另一個常見問題。

一次出入庫操作，實際上包含兩個 API 請求：

1. 新增「出入庫」記錄
2. 更新「庫存」記錄

如果發生以下情況：

• 「出入庫」新增成功
• 但「庫存」更新失敗（例如權限、資料衝突、系統錯誤）

那麼系統就會留下不一致的狀態：
有出入庫記錄，卻沒有正確反映到庫存數量。

對策：bulkRequest + revision

Step 1：先取得庫存資料與其 $revision

在進行更新前，先從「庫存管理」應用程式取得目前的庫存數量。

GET /k/v1/record.json?app={庫存管理AppID}&id=1

回傳結果中，除了實際欄位資料外，還會包含一個特殊欄位：

"$revision": {
  "type": "__REVISION__",
  "value": "17"
}

revision 是什麼？

revision 可以理解為記錄的「版本號碼」：

• 每當該筆記錄被更新一次，revision 就會自動 +1
• 在執行更新記錄的 API 時可以指定 revision：
  • 若 revision 不一致（代表記錄被更新過） → API 直接回傳錯誤
  • 可防止「用舊資料覆蓋新資料」

💡 使用「更新記錄狀態的 API」時，由於包含「執行流程動作」與「更新狀態」兩個操作，revision 會增加 2。詳情請參考 官方文件 說明。

Step 2：使用 bulkRequest 同時執行兩個操作

接著，使用 bulkRequest 一次送出兩個請求：

1. 更新「庫存管理」應用程式的庫存數（指定 revision）
2. 新增「出入庫記錄」應用程式的記錄

API 端點

POST /k/v1/bulkRequest.json

請求主體

{
  "requests": [
    {
      "method": "PUT",
      "api": "/k/v1/record.json",
      "payload": {
        "app": {庫存管理AppID},
        "id": 1,
        "revision": 17,
        "record": {
          "在庫數": {
            "value": "15"
          }
        }
      }
    },
    {
      "method": "POST",
      "api": "/k/v1/record.json",
      "payload": {
        "app": {出入庫記錄AppID},
        "record": {
          "入庫數": {
            "value": "5"
          }
        }
      }
    }
  ]
}

重點說明

bulkRequest 失敗時的回滾（rollback）機制

同前述說明，執行 bulkRequest 時，若有任何一個請求失敗，後續請求便不會執行，並且所有的請求回滾至原先的狀態。

revision 用來處理同時操作

如果在取得庫存資料後，有其他人先更新了該筆記錄，則庫存更新會失敗。
並且因為 bulkRequest 的回滾機制，出入庫記錄也不會被新增。

這樣就能同時解決：

• 庫存數同時更新的衝突問題
• 跨應用程式更新失敗造成的資料不一致問題

結語

本文介紹了如何在 kintone 中：

• 使用 bulkRequest 同時更新多個應用程式的記錄
• 搭配 revision 避免多人同時操作導致的資料覆蓋
• 以「全部成功，否則全部失敗」的方式維持資料整合性

這樣的設計非常適合用在：

• 庫存管理
• 預約申請
• 名額控管、配額管理等場景

不過也要注意，如果同一筆記錄的更新頻率非常高，使用 revision 的方式會讓 API 發生錯誤的機率提高，實務上仍需評估是否適合用 kintone 來實作此類系統。