部落格>介紹鍵值儲存庫：無需重新部署即可修改關注清單

介紹鍵值儲存庫：無需重新部署即可修改關注清單

Key-Value Store 為您的資料管線在Quicknode 上提供了一個持久且可更新的狀態層。您可透過 REST API 更新觀察清單，無需修改篩選器程式碼或重新部署Streams 。

Quicknode

2026年9月14日 — 閱讀時間 6 分鐘

新增為首選來源

觀察名單會變動。每當有人註冊，投資組合追蹤工具就會新增一個地址。合規流程則依循一份制裁名單，而該名單的更新時程由他人決定。

如果該清單存放在您的 `Streams ` 篩選器中，那麼每次變更都會變成程式碼變更。有人編輯陣列並更新篩選器；或者您將資料存放在獨立的資料庫中，並在每個區塊中查詢資料，這便會讓您必須額外維護和同步另一個系統。

鍵值儲存系統將該變動狀態移出篩選器。

它提供兩種資料類型：

清單用來存放具有名稱的字串項目集合，例如錢包地址、白名單或篩選條件。
值會保存一項您希望隨時間追蹤的狀態，例如您最近處理過的區塊。

Streams 篩選器可同時讀取和寫入資料。受支援的 Webhook 範本可透過名稱參照鍵值儲存庫中的清單。後端、腳本或agent 皆可透過 REST API 存取相同資料。

對於觀察清單而言，這意味著只需一次 API 呼叫，即可變更正在執行的篩選器所匹配的項目，而無需變更或重新部署篩選器本身。

避免更換篩選器僅是其中一項好處。更重要的是，無論誰擁有這份觀察清單，都不再需要在資料變更時每次都修改篩選邏輯。使用者介面、後端或腳本皆可直接進行更新。

所有Quicknode 方案均提供鍵值儲存服務。

閱讀「鍵值儲存庫」的文件

在不調整篩選條件的情況下更新觀察清單

在Streams 篩選器中，您可以使用 qnLib.qnContainsListItems 將多個項目與清單進行比對：

終端機

async function main(payload) {
  const addresses = payload.data.flatMap(block =>
    block.transactions.flatMap(tx => [tx.from, tx.to])
  );
  const hits = await qnLib.qnContainsListItems(
    "watched_wallets",
    addresses
  );
  return hits.some(Boolean) ? payload.data : null;
}

此方法接受一個項目陣列，並針對每個項目回傳一個布林值，其順序與輸入陣列一致。篩選器亦可使用 Go 語言編寫，其中對應的方法為 qn.ContainsListItems，且以同步方式執行，無需使用 await 關鍵字。

關鍵在於 `watched_wallets` 的位置：位於篩選器之外。

在清單中新增或移除一個地址後，正在執行的篩選器會直接使用更新後的觀察清單，無需重新部署。

只要篩選邏輯保持不變，而其處理的資料發生變化，這種模式在任何地方都適用。

篩選條件也可以位於篩選器之外

清單不一定要包含錢包地址。

它們也可以包含用來決定哪些事件重要的標準。例如，一個訂單監控應用程式可能會讓使用者選擇想要追蹤哪些訂單狀態。

與其將這些狀態硬編碼到篩選器中，不如將它們儲存於清單中。當使用者變更選項時，更新該清單，執行中的篩選器便會開始採用新的篩選條件。

同樣的原則也適用於白名單、黑名單、路由準則、受監控的合約，或是其他與您的過濾邏輯獨立變動的值集。

如果要變更某項內容時，無需變更篩選器本身，那麼這項內容就是關鍵值儲存庫的理想候選對象。

Values 會處理非清單的狀態

價值觀展現了同一概念的另一面。

舉例來說，一個需要記住上次處理到哪裡的濾波器，可以在執行結束時寫入一個「lastProcessedBlock」值，並在處理恢復時再次讀取該值。

濾波器無需將變動的狀態嵌入應用程式邏輯中，而是可透過鍵值儲存庫來讀取及更新該狀態。

在將它放入熱路徑之前

在濾鏡中使用鍵值儲存庫之前，有幾點值得了解。

比對時會區分大小寫

鍵值儲存庫中的項目會區分大小寫。

對於區塊鏈地址，請確保值的儲存與檢查方式保持一致。否則，使用不同大小寫的地址可能無法如預期般匹配。

當前狀態可透過Streams 、Webhooks 以及 REST API 在全球範圍內取得

「鍵值儲存庫」可讓您的篩選器存取清單的當前內容，因此當當前狀態至關重要時，這項功能便非常適合——這正是許多觀察清單和動態篩選規則的應用情境。

當您更新清單時，正在執行的篩選器會讀取更新後的內容。

存取 REST API 需要 API 金鑰

Streams 過濾器可透過Streams 執行階段存取鍵值儲存庫。

直接透過 REST API 發出的請求（無論是讀取或寫入），均需使用Quicknode API 金鑰。

發貨前請先了解使用方法

在Streams 篩選器中對鍵值儲存庫進行讀取和比對操作，不會消耗 API 配額。使用鍵值儲存庫清單搭配 Webhook 亦屬免費。

寫入操作有所不同。無論是透過Streams 篩選器，還是透過 REST API 進行寫入，新增清單項目或建立值都會消耗 API 配額。

以下使用方式會消耗 API 配額：

每新增一項清單項目或建立一項值，即可獲得20 個 API 積分
每月每項儲存項目可獲得10 個 API 額度
每次對鍵值儲存庫 REST API 的請求，可獲得5 個 API 積分

目前的大小限制包括：每個清單項目最多 128 個字元，每個值最多800,000 個字元。

在規劃生產環境的使用規模之前，請參閱 Key-Value Store 文件，以了解最新的定價與限制。

查看當前鍵值儲存庫的定價與限制

建立清單並保持其最新狀態

若要將現有的陣列移入鍵值儲存庫，需變更一個篩選器。

首先，建立清單並為其設定初始值：

終端機

curl -X POST "https://api.quicknode.com/kv/rest/v1/lists" \
 -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"key":"watched_wallets","items":["0x8f3c...","0x41be..."]}'

您可以透過單一請求來建立清單並為其預先填充資料。

接著將篩選器設定為從該清單讀取資料，並更新一次。

此後，觀察清單的變更將透過鍵值儲存庫（Key-Value Store）進行，而非透過篩選器。

對於持續性或批次變更，endpoint 的「更新清單」功能可在單一 PATCH 請求中新增或移除多個項目。這使得使用者介面、後端、腳本或持續整合 (CI) 工作都能輕鬆地將清單保持為最新狀態，而無需調整篩選條件。

閱讀「更新清單」API 文件

Key-Value Store 的資料範圍限於Quicknode 帳戶，而非單一專案或endpoint ，因此Streams 篩選器、Webhooks 以及應用程式均可基於相同的底層資料運作。