集合與資料
在 GetMyBot 儲存申請、訂單和課程報名:建立資料表、加入記錄,並在反應中使用。
本頁內容
集合類似資料表:一列可以是一份申請、一張訂單或一次課程報名。機器人可以根據使用者答案新增記錄,你也可以到資料 → 集合查看和修改。
例如要收集諮詢申請,可建立 leads 集合,包含 name、phone、topic 欄位。機器人提問後把姓名、電話和主題存成同一列,之後就能在反應中查找。
什麼是集合
欄位定義資料項目,例如「電話」和「主題」;記錄是一列的所有值。欄位名稱與類型合稱資料結構。內部以 JSON 文件儲存記錄,新增欄位不必重建既有資料。
集合名稱在同一個機器人中須唯一,並供反應動作引用,例如 leads、orders、scores。
欄位類型
| 類型 | 儲存內容 | 例子 |
|---|---|---|
text | 文字 | 姓名、Email、留言 |
number | 數字 | 金額、數量、分數 |
bool | 是或否:true/false | 訂單是否已付款 |
datetime | 日期與時間 | 課程預約時間 |
json | 巢狀物件或清單 | 含商品屬性的訂單內容 |
類型決定編輯器的輸入方式和儲存時的型別轉換。結構不是強制限制:若記錄有未在結構中定義的欄位,它仍會被儲存並顯示為另一欄。
建立集合
- 開啟資料 → 集合,按新增。
- 填寫名稱,建議使用英文字母且不含空格,方便在反應中引用。
- 按欄位新增所需欄位,選擇各欄類型。
- 需要時設定下方的保留規則,然後儲存。
記錄:查看與編輯
集合卡片上的表格圖示會開啟該集合的資料視窗:
- 查看:以最新在前的順序顯示所有列,每個值佔一格。
- 新增記錄:依集合結構開啟表單,例如
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。這個連結只說明欄位用途,不會連帶修改或刪除記錄。
- 在收到文字時使用搜尋集合(
record_search):選products、查詢{{text}}、搜尋欄name、同義詞欄aliases,結果存為search。同義詞可為字串或 JSON 字串陣列。搜尋不區分大小寫或俄文е/ё,標點會轉成空格。 - 加入依結果數量選擇下一步(
branch_result),來源設為search。第一個符合的分支生效;應依序處理結果不完整、找不到、模糊比對、單筆、多筆。模糊比對要請使用者確認;零筆和單筆分支須以完整搜尋結果為前提。 - 多筆結果時,在訊息中選從找到的記錄建立按鈕。選
search、標籤欄name和下一條反應。助手會設定buttons_from.over = search.rows、標籤範本及carry.selected_id = {{item._record_id}}。請確認結果包含標籤欄;仍可使用進階按鈕編輯器。 - 下一條反應用尋找關聯記錄(
record_related),集合設為variants、鍵設為product_id、值為{{ctx.selected_id}},結果存為variants。要讀取所選商品本身,改選products和_record_id。若使用業務識別碼,按鈕與讀取動作都要用相同鍵。 - 再按結果分支:單筆以
{{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類型。