Cơ sở kiến thức GetMyBot

Bộ sưu tập và dữ liệu

Lưu yêu cầu, đơn hàng và lượt đăng ký ngay trong GetMyBot: tạo bảng, thêm dữ liệu và dùng trong phản ứng.

Trên trang này

Bộ sưu tập giống một bảng dữ liệu: mỗi dòng là một yêu cầu, đơn hàng hoặc lượt đăng ký lớp học. Bot có thể thêm dòng từ câu trả lời của người dùng; bạn xem và sửa chúng tại Dữ liệu → Bộ sưu tập.

Ví dụ, để nhận đăng ký tư vấn, tạo bộ sưu tập leads với các trường name, phone, topic. Sau khi đặt câu hỏi, bot lưu tên, số điện thoại và chủ đề trong một dòng. Sau này bạn có thể tìm và sử dụng dòng đó trong phản ứng.

Bộ sưu tập là gì?

Trường là cột, như “Điện thoại” và “Chủ đề”. Bản ghi là một dòng chứa các giá trị. Danh sách trường và kiểu dữ liệu gọi là lược đồ. Về mặt kỹ thuật, bản ghi là tài liệu JSON; thêm trường mới không buộc bạn tạo lại các dòng đã lưu.

Tên bộ sưu tập phải duy nhất trong một bot và được dùng làm mã định danh trong hành động, ví dụ leads, orders hoặc scores.

Các kiểu trường

Khi tạo bộ sưu tập, chọn trường và kiểu cho từng trường:

KiểuLưu gìVí dụ
textChuỗi văn bảnTên, email, ghi chú
numberSốTổng tiền, số lượng, điểm
boolCó/không: true / falseĐơn hàng đã thanh toán
datetimeNgày và giờGiờ đăng ký lớp học
jsonĐối tượng hoặc danh sách lồng nhauCác mặt hàng trong đơn

Kiểu dữ liệu ảnh hưởng cách sửa trong giao diện và chuyển đổi khi lưu. Lược đồ không cứng: trường chưa khai báo vẫn được lưu và hiển thị thành cột riêng.

Tạo bộ sưu tập

  1. Mở Dữ liệu → Bộ sưu tập và nhấn Thêm.
  2. Nhập tên bằng chữ Latin, không có khoảng trắng để dễ gọi trong phản ứng.
  3. Nhấn Trường để thêm cột và chọn kiểu.
  4. Nếu cần, đặt quy tắc lưu trữ bên dưới rồi lưu.

Xem và sửa bản ghi

Biểu tượng bảng trên thẻ bộ sưu tập mở cửa sổ Dữ liệu của bộ sưu tập đó:

  • Xem: các dòng hiển thị từ mới nhất, mỗi trường trong một ô.
  • Thêm bản ghi: biểu mẫu theo lược đồ; kiểu bool dùng công tắc, json có ô nhập JSON, v.v.
  • Sửa (biểu tượng bút): thay đổi dòng đã có.
  • Xóa (biểu tượng thùng rác): xóa dòng.

Hành động trong phản ứng cũng có thể tự thêm dữ liệu. Cách nhập thủ công và tự động dùng chung một bộ sưu tập.

Lưu trữ (retention)

Để bộ sưu tập không tăng mãi, đặt quy tắc tự dọn:

  • Số bản ghi tối đa: khi vượt ngưỡng, các dòng cũ nhất bị xóa.
  • Lưu không quá (ngày): xóa các dòng cũ hơn thời hạn.

Ví dụ, 30 ngày phù hợp cho nhật ký tạm: dòng cũ hơn được xóa tự động. Việc dọn diễn ra định kỳ, không nhất thiết đúng giây hết hạn. Có thể bật cả hai giới hạn cùng lúc. Đừng đặt hạn cho đơn hàng vẫn cần xử lý.

Dùng dữ liệu trong phản ứng

Bộ sưu tập gắn trực tiếp với trình tạo phản ứng. Các hành động gồm:

  • Tạo bản ghi: thêm dòng, nhận giá trị từ biến thay thế như {{user_id}} hoặc {{text}}. Khóa chống trùng giúp không tạo bản sao: gọi lại với cùng khóa sẽ cập nhật dòng cũ. Ví dụ, khóa theo ID người dùng giữ một yêu cầu hiện tại cho mỗi người.
  • Cập nhật bản ghi: đổi các dòng khớp điều kiện.
  • Tìm bản ghi: đọc dòng thành danh sách trong ngữ cảnh để dùng ở bước sau.
  • Đọc một trang bộ sưu tập (record_page): đọc từng phần, ví dụ hai thẻ sản phẩm kèm nút trang tiếp.
  • Tính trên toàn bộ bộ sưu tập (record_aggregate): đếm và tính tổng trên tất cả bản ghi phù hợp trong thời hạn lưu trữ. Chỉ tải trang đầu không giới hạn phép tính này.
  • Giao dịch bộ sưu tập nguyên tử (collection_transaction): kiểm tra điều kiện và lưu nhiều thay đổi cùng lúc, chẳng hạn giữ chỗ và tạo đơn đăng ký. Nếu xung đột, những thay đổi trước đó cũng được hoàn tác.
  • Xóa bản ghi: xóa các dòng khớp điều kiện.
  • Vòng lặp qua danh sách: duyệt mảng trong ngữ cảnh và chạy hành động cho từng phần tử, như cập nhật dòng, tính tổng hoặc gửi từng bản ghi tới dịch vụ ngoài.

Nhờ vậy bot có thể quản lý khách hàng, yêu cầu, điểm thưởng và báo cáo mà không cần cơ sở dữ liệu ngoài.

Các bài thực hành hướng dẫn xem tiếp danh mục, tính tổng của mọi đơn phù hợp và đặt chỗ cuối cùng. Trang của danh sách đã tải, trang bộ sưu tập và phép tổng hợp toàn bộ bộ sưu tập giải quyết ba việc khác nhau; các bài học chỉ rõ dữ liệu nào đi sang bước sau.

Vòng lặp không phải cách gửi hàng loạt. Mỗi lượt xử lý tối đa 500 phần tử, nhưng cả sự kiện chỉ gửi tối đa 50 tin nhắn. Nếu gửi trong vòng lặp, 50 tin đầu có thể đi, phần còn lại bị từ chối. Để nhắn cho người trong bộ sưu tập, tạo nhóm đối tượng và dùng gửi hàng loạt, có tốc độ, tạm dừng và nhật ký. Xem Hành động: giới hạn một sự kiện.

Danh mục: tìm, chọn và hiển thị

Bắt đầu bằng bài học tìm lớp học. Bài này nêu bộ sưu tập cần chuẩn bị, thứ tự hành động và cách kiểm tra khi không có, có nhiều kết quả hoặc người dùng nhấn nút cũ.

Tách dữ liệu danh mục khỏi phản ứng. Ví dụ products lưu name và aliases; variants lưu product_id, name và card. Trong trình sửa trường variants.product_id, bật Liên kết với bộ sưu tập khác, chọn products, khóa _record_id và trường nhãn name. Liên kết này mô tả ý nghĩa của trường; nó không tự lan truyền việc sửa hoặc xóa bản ghi.

  1. Trong phản ứng nhận văn bản, thêm Tìm trong bộ sưu tập (record_search). Chọn products, truy vấn {{text}}, trường tìm name, trường tên thay thế aliases và tên kết quả search. Tên thay thế có thể là chuỗi hoặc mảng chuỗi JSON. Tìm kiếm không phân biệt chữ hoa/thường và coi hai chữ Nga е, ё như nhau; dấu câu được thay bằng khoảng trắng.
  2. Thêm Chọn bước tiếp theo (branch_result) với nguồn search. Chỉ nhánh khớp đầu tiên chạy. Xử lý kết quả chưa đầy đủ trước bằng cách xin truy vấn cụ thể hơn; sau đó đến không tìm thấy, khớp gần đúng, một bản ghi, nhiều bản ghi. Hỏi xác nhận khi khớp gần đúng. Muốn kết luận không có hoặc chỉ một kết quả thì danh sách phải đầy đủ.
  3. Với nhiều kết quả, dùng Nút từ bản ghi tìm thấy trong tin nhắn. Chọn nguồn search, trường nhãn name và phản ứng tiếp theo. Trợ lý thiết lập buttons_from.over = search.rows, mẫu chữ và carry.selected_id = {{item._record_id}}. Kiểm tra trường nhãn có mặt trong kết quả. Trình sửa nút nâng cao vẫn dùng được.
  4. Trong phản ứng tiếp theo, thêm Tìm bản ghi liên quan (record_related): bộ sưu tập variants, khóa product_id, giá trị {{ctx.selected_id}}, tên kết quả variants. Muốn đọc chính sản phẩm đã chọn, dùng products và _record_id. Nếu quan hệ dựa trên khóa nghiệp vụ khác, dùng cùng khóa ở trợ lý nút và bước đọc.
  5. Lại phân nhánh theo kết quả. Với một bản ghi, hiển thị thẻ bằng {{ctx.variants.first.card}}; với nhiều bản ghi, hiển thị nút. Nút chỉ truyền ID và đọc dữ liệu mới sau khi được nhấn. Đừng lưu thẻ hoặc giá trị có thể thay đổi trong carry.

Kết quả đọc

search.rows là danh sách bản ghi; search.count là số dòng đã tải; search.first là bản ghi đầu; search.first.name là trường cụ thể của bản ghi đó. Mỗi dòng có thêm _record_id, _score và _match_type; ba tên này được dành riêng. Nếu không tìm thấy, bản ghi đầu của lần trước và các trường của nó được xóa khỏi kết quả.

search.total đếm kết quả trong các ứng viên đã kiểm tra. total_exact = false nghĩa là chưa quét toàn bộ bộ sưu tập; truncated = true cho biết kết quả bị giới hạn. Đừng coi kết quả này là đầy đủ hoặc bảo đảm đã tìm được kiểu khớp tốt nhất trong toàn bộ dữ liệu. Mỗi truy vấn xem tối đa 10.000 bản ghi và 16 MiB; phản hồi ghi giới hạn thực tế. Mặc định trả tối đa 100 dòng, mức tối đa là 10.000.

Kiểm tra và giải thích

Trong trình sửa tìm kiếm, mở Kiểm tra tìm kiếm và nhập văn bản hoặc ID cụ thể. Thử nghiệm chỉ đọc: không chạy phản ứng sau, không gửi tin hoặc thực hiện hành động khác. Nếu bộ lọc bổ sung có biến thay thế, hãy đổi thành giá trị cụ thể trước. Kết quả thử hiển thị dòng tìm được, kiểu khớp, số bản ghi đã kiểm tra và giới hạn. Khi đổi dự án, bộ sưu tập, cấu hình hoặc quyền truy cập, kết quả cũ sẽ bị ẩn.

Nhật ký chạy cho biết các trường tìm kiếm, kiểu khớp, số dòng đã kiểm tra và trả về, giới hạn và nhánh được chọn. Sơ đồ phản ứng ghi mọi điều kiện dẫn tới cùng một phản ứng. Khi xem lại một lần chạy, giải thích tìm kiếm có trong sự kiện tương ứng nếu bạn có quyền xem nội dung đó.

Trợ lý tạo nút mặc định tạo tối đa 20 nút. Có thể đổi Số nút tối đa từ 1 đến 100; đây là giới hạn, không phải phân trang. Danh sách rỗng không tạo nút. Với nhiều kết quả hơn, hãy thêm nhánh xin người dùng tìm cụ thể hơn.

Trong hành động Tính toán, trợ lý Thao tác trên danh sách đã tải tạo công thức đếm bản ghi, lấy bản ghi đầu, tính tổng một trường và lấy danh sách nhãn. Phép tính chỉ dùng các dòng đã tải, nên nếu kết quả chưa đầy đủ, nó không phải tổng của cả bộ sưu tập.

API và MCP

Những thao tác này cũng có qua POST /api/bots/{botID}/collections/{name}/search và /related, hoặc công cụ MCP search_records, related_records với quyền collections:read. Yêu cầu được giới hạn theo dự án và khu vực hiện tại. Phép thử REST dùng giá trị cụ thể; biến thay thế trong mẫu được xử lý ở hành động của phản ứng.

Xử lý kết quả và thay đổi có điều kiện

Truyền kết quả bộ sưu tập cho list_transform để lọc, sắp xếp, bỏ trùng hoặc lấy một trang. list_aggregate tính các chỉ số có tên trên những dòng đã tải, có thể nhóm. Các hành động này cũng dùng được với danh sách thông thường trong phản hồi HTTP mà không cần bộ sưu tập.

Để hai lượt chạy đồng thời không áp dụng một chuyển trạng thái hai lần, dùng record_update_if: chỉ định ID, giá trị trường đang mong đợi và giá trị mới. Kiểm tra và thay đổi diễn ra nguyên tử cho một bản ghi. Kết quả updated, conflict hoặc not_found có thể phân nhánh bằng branch_value. Cách này khác với cập nhật vô điều kiện tất cả dòng khớp bộ lọc.

Xem cấu hình, giới hạn và ví dụ. Bài thực hành xác nhận yêu cầu đúng một lần chỉ cách kiểm tra trạng thái, chủ sở hữu và trả lời riêng cho updated, conflict, not_found.

Truy cập từ Mini App

Ứng dụng Telegram Mini App của bot có thể đọc bản ghi bộ sưu tập: giao diện yêu cầu dữ liệu theo tên bộ sưu tập, bộ lọc và giới hạn. Bạn có thể hiển thị đơn hàng, lịch sử hoặc bảng xếp hạng ngay trong Telegram.

Mẹo sử dụng

  • Đặt tên trường ngắn, dễ xử lý như email, total, paid để chèn vào mẫu phản ứng.
  • Dùng khóa chống trùng để chạy lại hành động không tạo thêm dòng. Tính chất này gọi là idempotency.
  • Đặt thời hạn lưu (retention) cho nhật ký và dữ liệu tạm không còn cần nữa.
  • Dùng kiểu json khi cấu trúc giá trị không cố định từ trước.