GetMyBot 知识库

集合与数据

在 GetMyBot 中建立数据表,保存申请、订单与预约,并在反应中查询和修改。

本页内容

集合类似数据表:每一行是一份申请、一笔订单或一次课程预约。机器人可根据用户回答添加记录,您也可以在数据 → 集合中查看和编辑。

例如,为咨询预约建立 leads 集合,添加 name、phone、topic 字段。机器人提问后,将姓名、电话和主题保存到同一行,之后还可在反应中查找。

什么是集合

字段是列,例如“电话”和“主题”;记录是一行的值。字段名称和类型组成集合结构。记录实际以 JSON 文档保存,因此添加字段不需要重建已有记录。

集合名在同一机器人内唯一,也是反应动作中引用它的标识符,例如 leads、orders、scores。

字段类型

类型保存内容示例
text文本姓名、电子邮件或备注
number数字金额、数量或积分
bool是或否:true / false订单是否已付款
datetime日期和时间课程预约时间
json嵌套对象或列表含商品属性的订单明细

类型决定界面如何编辑字段,以及保存时如何转换值。结构不是严格限制:结构中没有的字段也会保存,并显示为单独一列。

创建集合

  1. 打开数据 → 集合,点击添加。
  2. 输入名称,建议使用无空格的拉丁字母名称,方便在反应中引用。
  3. 点击字段添加所需列,逐一选择类型。
  4. 如有需要,设置下方的保存规则,然后保存。

查看与编辑记录

集合卡片上的表格图标会打开该集合的数据窗口:

  • 查看:逐行显示记录,最新的排在前面。
  • 添加记录:按字段类型填写表单;bool 使用开关,json 使用 JSON 输入框等。
  • 编辑(铅笔图标):修改已有记录。
  • 删除(垃圾桶图标):删除记录。

机器人反应也能自动写入记录;手动编辑和自动写入使用同一个集合。

保存期限(retention)

可以设置自动清理,避免集合无限增长:

  • 最多保留记录数:超出时删除最旧的记录。
  • 最长保留天数:删除超过指定天数的记录。

例如,临时日志可保留 30 天。清理会定期执行,并非恰好在到期时运行;两种限制可同时使用。仍需处理的订单不要设置会提前删除它们的期限。

在反应中处理数据

  • 创建记录:以 {{user_id}}、{{text}} 等替换内容填写一行。可设置去重键,使同键的再次调用更新原记录,例如每个用户只保留一份当前申请。
  • 更新记录:修改符合条件的行。
  • 查询记录:把记录作为数组载入 ctx,供后续遍历。
  • 读取集合页面(record_page):分批读取记录,例如一次显示两张卡片,并提供“下一页”按钮。
  • 汇总整个集合(record_aggregate):按保存规则允许访问的所有匹配记录计算数量和金额;只加载了第一页也不会限制此计算。
  • 集合原子事务(collection_transaction):检查条件并一起保存多项更改,例如占用名额并创建申请;发生冲突时,之前的更改也会回滚。
  • 删除记录:按条件删除行。
  • 循环(for-each):遍历上下文中的数组,逐项更新、计算或向外部服务发送数据。

这样可以在 GetMyBot 内管理客户资料、申请、积分和报表,不必另建数据库。集合练习展示目录续页、整个集合的订单汇总与最后名额的预订。已载入列表的一页、集合的一页与整个集合的汇总,分别解决不同问题。

循环不能代替群发。 单次循环最多处理 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}}。确认返回字段包含 name;仍可在高级按钮编辑器中调整。
  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,或拥有 collections:read 权限的 MCP 工具 search_records、related_records 使用。请求仅针对当前项目和区域。REST 测试需传具体值;反应动作才会解析模板替换内容。

处理结果与有条件修改

list_transform 可筛选、排序、去重或分页处理集合结果;list_aggregate 可对已载入的行计算命名汇总,也可分组。这些动作也适用于 HTTP 响应中的普通列表,不要求使用集合。

为避免两个同时运行的流程重复变更状态,可用 record_update_if 指定记录 ID、预期字段和新值。单条记录的检查与修改以原子操作完成,结果 updated、conflict 或 not_found 可交给 branch_value 分支处理。这与无条件修改所有符合筛选条件的行不同。详见设置、限制与示例及只确认一次申请的练习。

从 Mini App 读取

机器人的 Telegram Mini App 可按集合名、筛选条件和数量上限读取记录,向用户展示订单、历史或排行榜。

使用建议

  • 字段使用简短的拉丁字母名称(email、total、paid),方便在反应模板中使用。
  • 用去重键防止重复动作创建多条记录;这称为幂等性。
  • 给临时日志和不再需要的数据设置保存期限(retention)。
  • 值的结构不固定时可用 json 类型。