GetMyBot 知識庫

集合與資料

在 GetMyBot 儲存申請、訂單和課程報名:建立資料表、加入記錄,並在反應中使用。

本頁內容

集合類似資料表:一列可以是一份申請、一張訂單或一次課程報名。機器人可以根據使用者答案新增記錄,你也可以到資料 → 集合查看和修改。

例如要收集諮詢申請,可建立 leads 集合,包含 name、phone、topic 欄位。機器人提問後把姓名、電話和主題存成同一列,之後就能在反應中查找。

什麼是集合

欄位定義資料項目,例如「電話」和「主題」;記錄是一列的所有值。欄位名稱與類型合稱資料結構。內部以 JSON 文件儲存記錄,新增欄位不必重建既有資料。

集合名稱在同一個機器人中須唯一,並供反應動作引用,例如 leads、orders、scores。

欄位類型

類型儲存內容例子
text文字姓名、Email、留言
number數字金額、數量、分數
bool是或否:true/false訂單是否已付款
datetime日期與時間課程預約時間
json巢狀物件或清單含商品屬性的訂單內容

類型決定編輯器的輸入方式和儲存時的型別轉換。結構不是強制限制:若記錄有未在結構中定義的欄位,它仍會被儲存並顯示為另一欄。

建立集合

  1. 開啟資料 → 集合,按新增。
  2. 填寫名稱,建議使用英文字母且不含空格,方便在反應中引用。
  3. 按欄位新增所需欄位,選擇各欄類型。
  4. 需要時設定下方的保留規則,然後儲存。

記錄:查看與編輯

集合卡片上的表格圖示會開啟該集合的資料視窗:

  • 查看:以最新在前的順序顯示所有列,每個值佔一格。
  • 新增記錄:依集合結構開啟表單,例如 bool 用開關、json 用 JSON 輸入欄。
  • 編輯(鉛筆):修改現有列。
  • 刪除(垃圾桶):移除列。

反應動作也會自動寫入同一個集合,因此手動編輯與機器人資料會一同顯示。

保留規則(retention)

可設定自動清理,避免集合無限增長:

  • 最多保留記錄數:超過上限時刪除最舊的記錄。
  • 最長保留天數:刪除超過指定日數的記錄。

例如臨時記錄可保留 30 天。清理會定期執行,並非恰好在到期瞬間執行。兩個限制可以同時使用;仍需處理的訂單不應設定過短的保留期。

從反應使用資料

反應動作可直接操作集合:

  • 建立記錄:新增一列,值可用 {{user_id}}、{{text}} 等變數替換。去重鍵使相同鍵的重複操作更新既有列,例如每位使用者只保留一份目前申請。
  • 更新記錄:修改符合條件的列。
  • 查詢記錄:將列讀入執行情境的陣列,供後續逐筆處理。
  • 讀取集合頁面(record_page):分批讀取,例如一次顯示兩張卡片,再提供「下一頁」按鈕。
  • 彙總整個集合(record_aggregate):對保留規則範圍內的所有符合記錄計算數量和總額,不受目前載入頁面的限制。
  • 集合原子交易(collection_transaction):先檢查條件,再一起儲存多項變更,例如預留席位並建立申請。若有衝突,先前的變更也會回滾。
  • 刪除記錄:按條件移除列。
  • 逐項處理清單:對情境中的陣列逐項執行巢狀動作,例如更新記錄、計算總數或逐筆呼叫外部服務。

這樣即可在平台內管理客戶資料、申請、積分與報表。集合實作教學展示目錄下一頁、整個集合的訂單彙總及預留最後席位,並區分「已載入清單的一頁」、「集合的一頁」與「整個集合的彙總」。

迴圈不適合群發。 一次最多處理 500 個項目,而整個事件最多傳送 50 則訊息。若在迴圈中逐項傳訊,前 50 則可能送出,其餘會失敗。要聯絡集合中的使用者,請建立受眾群組並使用群發,其速度、暫停和傳送結果由專門流程管理。詳見單一事件預算。

目錄:搜尋、選擇與展示卡片

可先閱讀搜尋課程教學,按照步驟準備集合、設定動作,並測試零筆、多筆及舊按鈕的情況。

以商品目錄為例,products 集合存 name 和 aliases;variants 集合存 product_id、name、card。在 variants.product_id 欄位啟用連結到其他集合,選 products、鍵 _record_id 及標籤欄 name。這個連結只說明欄位用途,不會連帶修改或刪除記錄。

  1. 在收到文字時使用搜尋集合(record_search):選 products、查詢 {{text}}、搜尋欄 name、同義詞欄 aliases,結果存為 search。同義詞可為字串或 JSON 字串陣列。搜尋不區分大小寫或俄文 е/ё,標點會轉成空格。
  2. 加入依結果數量選擇下一步(branch_result),來源設為 search。第一個符合的分支生效;應依序處理結果不完整、找不到、模糊比對、單筆、多筆。模糊比對要請使用者確認;零筆和單筆分支須以完整搜尋結果為前提。
  3. 多筆結果時,在訊息中選從找到的記錄建立按鈕。選 search、標籤欄 name 和下一條反應。助手會設定 buttons_from.over = search.rows、標籤範本及 carry.selected_id = {{item._record_id}}。請確認結果包含標籤欄;仍可使用進階按鈕編輯器。
  4. 下一條反應用尋找關聯記錄(record_related),集合設為 variants、鍵設為 product_id、值為 {{ctx.selected_id}},結果存為 variants。要讀取所選商品本身,改選 products 和 _record_id。若使用業務識別碼,按鈕與讀取動作都要用相同鍵。
  5. 再按結果分支:單筆以 {{ctx.variants.first.card}} 顯示卡片,多筆則顯示選項按鈕。按鈕只傳 ID,按下後重新讀取最新資料;不要把可能變動的卡片或價格存進 Carry。

讀取結果

search.rows 是記錄清單,search.count 是已載入筆數,search.first 是第一筆,search.first.name 是該筆的欄位。每筆記錄另有 _record_id、_score 和 _match_type,這些名稱保留供系統使用。沒有結果時,之前的第一筆及其欄位會清空。

search.total 只計算已檢查候選記錄中的符合數。total_exact = false 表示未檢查完整集合;truncated = true 表示結果受限,不能假設已找到整個集合中最好的比對。每次最多檢查 10,000 筆和 16 MiB 資料,回應會列出實際限制。預設最多回傳 100 筆,上限 10,000 筆。

檢查與說明

在搜尋編輯器按檢查搜尋,輸入具體測試文字或 ID。這是唯讀操作,不會執行後續反應、傳訊或動作。其他篩選器中的變數須先換成具體值。檢查結果會顯示記錄、比對類型、已檢查筆數和限制;切換專案、集合、設定或權限後,舊結果會隱藏。

執行記錄會顯示搜尋欄、比對類型、已檢查及回傳筆數、結果限制和選中的分支。反應圖會標示通往同一反應的所有條件。重新查看執行記錄時,須開啟對應事件且有權閱讀內容,才能看到搜尋說明。

按鈕助手預設最多建立 20 顆按鈕,按鈕數上限可設為 1 至 100;這只是截斷,不是分頁。空清單不會產生按鈕,較多結果應提供縮小搜尋的分支。

計算動作的對已載入清單執行操作助手可產生記錄數、第一筆、欄位總和及標籤清單公式。它只計算已載入的列,結果不完整時不代表整個集合的總數。

API 與 MCP

相同操作也可透過 POST /api/bots/{botID}/collections/{name}/search 和 /related,或 MCP 的 search_records、related_records 使用,須有 collections:read 權限。呼叫限於目前專案及區域。REST 測試請求須提供具體值;變數替換會在反應動作中進行。

處理結果與條件式修改

集合結果可交給 list_transform 篩選、排序、去重或擷取一頁。list_aggregate 可對已載入的列計算命名的彙總值,亦可分組。兩者也適用於 HTTP 回應中的一般清單。

若兩次同時執行不能重複變更同一狀態,請用 record_update_if 指定記錄 ID、預期欄位及新值。單筆記錄的檢查與變更會以原子方式執行;儲存的 updated、conflict 或 not_found 狀態可交給 branch_value 分支處理。這與不檢查狀態、直接更新所有符合條件的記錄不同。詳見設定與範例及申請確認實作。

從 Mini App 存取

機器人的 Telegram Mini App 可按名稱、篩選器及筆數限制讀取集合記錄,在 Telegram 內顯示使用者的訂單、歷史或排行榜。

建議

  • 欄位採用簡短的英文識別碼,例如 email、total、paid,方便在反應中使用。
  • 防止重複執行產生新列時,設定去重鍵;這稱為冪等性。
  • 為不再需要的記錄及臨時資料設定保留期限(retention)。
  • 值的結構不固定時,可選 json 類型。