Kolekcje i dane
Jak przechowywać zgłoszenia, zamówienia i zapisy na zajęcia w GetMyBot: utworzyć tabelę, dodać dane i wykorzystać je w reakcjach.
Na tej stronie
Kolekcja przypomina tabelę: jeden wiersz to jedno zgłoszenie, zamówienie lub zapis na zajęcia. Bot może dodawać wiersze na podstawie odpowiedzi użytkowników, a Ty możesz je przeglądać i zmieniać w sekcji Dane → Kolekcje.
Na przykład do zapisów na konsultacje utwórz kolekcję leads z polami name, phone i topic. Po zadaniu pytań bot zapisze imię, telefon i temat w jednym wierszu. Później możesz wyszukać te rekordy i użyć ich w reakcji.
Czym jest kolekcja
Pola to kolumny, na przykład „Telefon” i „Temat”. Rekord zawiera wartości jednego wiersza. Lista pól i ich typów to schemat. Technicznie rekord jest dokumentem JSON: dodanie nowego pola nie wymaga ponownego tworzenia zapisanych wierszy.
Nazwa kolekcji jest unikalna w obrębie bota i służy jako identyfikator w akcjach reakcji, na przykład leads, orders lub scores.
Typy pól
Podczas tworzenia kolekcji wybierasz pola i ich typy:
| Typ | Co przechowuje | Przykład |
|---|---|---|
text | tekst | Imię, email lub komentarz |
number | liczbę | Kwotę, liczbę sztuk lub punkty |
bool | tak lub nie: true / false | Czy zamówienie opłacono |
datetime | datę i godzinę | Termin zajęć |
json | zagnieżdżony obiekt lub listę | Produkty i ich właściwości w zamówieniu |
Typ wpływa na edycję pola w panelu i sposób przekształcenia wartości przy zapisie. Schemat nie jest sztywny: pole spoza schematu również zostanie zapisane i pojawi się jako osobna kolumna.
Tworzenie kolekcji
- Otwórz Dane → Kolekcje i kliknij Dodaj.
- Wpisz nazwę alfabetem łacińskim, bez spacji, żeby łatwo odwoływać się do niej w reakcjach.
- Przyciskiem Pole dodaj kolumny i wybierz ich typy.
- W razie potrzeby ustaw zasady przechowywania (niżej) i zapisz kolekcję.
Rekordy: przeglądanie i edycja
Przycisk z ikoną tabeli w karcie kolekcji otwiera okno Dane z jej rekordami:
- Przeglądanie: wszystkie wiersze są na liście, od najnowszych, z osobną komórką dla każdego pola.
- Dodaj rekord: otwiera formularz zgodny ze schematem kolekcji. Pole
boolma przełącznik,jsonpole do wpisania JSON i tak dalej. - Edytuj (ołówek): zmienia istniejący wiersz.
- Usuń (kosz): usuwa wiersz.
Rekordy mogą też powstawać automatycznie przez akcje bota opisane poniżej. Edycja ręczna i automatyczna dotyczą tej samej kolekcji.
Przechowywanie (retention)
Żeby kolekcja nie rosła bez ograniczeń, ustaw automatyczne czyszczenie:
- Przechowuj najwyżej tyle rekordów: po przekroczeniu limitu najstarsze są usuwane.
- Przechowuj nie dłużej niż (dni): rekordy starsze od wskazanego okresu są usuwane.
Na przykład 30 dni może wystarczyć dla tymczasowego dziennika. Starsze wiersze będą usuwane automatycznie, ale czyszczenie odbywa się okresowo, nie dokładnie w chwili upływu terminu. Oba ograniczenia mogą działać jednocześnie. Nie ustawiaj krótkiego okresu dla zamówień, które są nadal potrzebne.
Używanie danych w reakcjach
Kolekcje są połączone bezpośrednio z edytorem reakcji. Dostępne akcje:
- Utwórz rekord: dodaje wiersz z wartościami z podstawień, na przykład
{{user_id}}i{{text}}. Klucz deduplikacji zapobiega duplikatom: ponowne wywołanie z tym samym kluczem aktualizuje istniejący wiersz. Klucz oparty na ID użytkownika pozwala zachować jedno aktualne zgłoszenie na osobę. - Aktualizuj rekordy: zmienia wiersze spełniające warunek.
- Pobierz rekordy: odczytuje wiersze do kontekstu wykonania jako tablicę.
- Read collection page (odczytaj stronę kolekcji) (
record_page): pobiera rekordy partiami, na przykład dwie karty z przyciskiem następnej strony. - Aggregate whole collection (podsumowanie całej kolekcji) (
record_aggregate): liczy rekordy i sumy we wszystkich pasujących wierszach objętych zasadami przechowywania. Wczytanie tylko pierwszej strony nie ogranicza obliczenia. - Atomic collection transaction (atomowa transakcja kolekcji) (
collection_transaction): sprawdza warunki i zapisuje kilka zmian razem, na przykład rezerwuje miejsce i tworzy zgłoszenie. W razie konfliktu wcześniejsze zmiany też są cofane. - Usuń rekordy: usuwa wiersze spełniające warunek.
- Pętla (for-each): przechodzi po tablicy z kontekstu i wykonuje zagnieżdżone akcje dla każdego elementu: aktualizuje wiersze, liczy wynik lub przekazuje rekordy do usługi zewnętrznej.
Dzięki temu bot może prowadzić CRM, zbierać zgłoszenia, przyznawać punkty i tworzyć raporty bez zewnętrznej bazy danych.
Ćwiczenia praktyczne pokazują paginację katalogu, podsumowanie wszystkich pasujących zamówień i rezerwację ostatniego miejsca. Strona wczytanej listy, strona kolekcji i podsumowanie kolekcji służą do różnych zadań; ćwiczenia pokazują też, jakie dane otrzymuje następny krok.
Pętla nie służy do wysyłek. W jednym przebiegu obsługuje najwyżej 500 elementów, a całe zdarzenie może wysłać najwyżej 50 wiadomości. Pętla z akcją wysyłania dostarczy pierwsze 50 i otrzyma odmowę dla pozostałych. Aby napisać do osób z kolekcji, utwórz na jej podstawie segment i uruchom wysyłkę, która obsługuje tempo, pauzę i liczenie wysłanych wiadomości. Więcej w Akcje → Budżet jednego zdarzenia.
Katalog: wyszukiwanie, wybór i karta
Na początek przejdź ćwiczenie wyszukiwania zajęć. Pokazuje, jakie kolekcje przygotować, w jakiej kolejności dodać akcje oraz jak sprawdzić pusty wynik, kilka trafień i kliknięcie starego przycisku.
Do katalogu wystarczy przechowywać dane oddzielnie od reakcji. Na przykład kolekcja products ma pola name i aliases, a variants pola product_id, name i card. W edytorze pola variants.product_id włącz Relację z inną kolekcją, wybierz products, klucz _record_id i pole etykiety name. Relacja opisuje przeznaczenie pola; nie powoduje kaskadowej edycji ani usuwania rekordów.
- W reakcji na przychodzący tekst dodaj Przeszukaj kolekcję (
record_search). Wybierzproducts, zapytanie{{text}}, pole wyszukiwanianame, pole synonimówaliasesi zapis wyniku wsearch. Synonimy mogą być tekstem lub tablicą tekstów JSON. Wyszukiwanie nie rozróżnia wielkości liter ani rosyjskich liter „е” i „ё”; znaki interpunkcyjne zamienia na spacje. - Dodaj Wybierz następny krok (
branch_result) ze źródłemsearch. Wykonuje się pierwsza pasująca gałąź. Najpierw obsłuż Niepełny wynik prośbą o doprecyzowanie, potem Nic nie znaleziono, Niedokładne dopasowanie, Jeden rekord i Kilka rekordów. Przy niedokładnym dopasowaniu poproś o potwierdzenie. Pusty i pojedynczy wynik wymagają pełnego wyszukiwania. - Dla kilku wyników w wiadomości otwórz Przyciski z znalezionych rekordów. Wybierz źródło
search, etykietęnamei następną reakcję. Pomocnik ustawibuttons_from.over = search.rows, szablon etykiety icarry.selected_id = {{item._record_id}}. Sprawdź, czy pole etykiety jest w wynikach. Nadal możesz użyć zaawansowanego edytora przycisku. - W kolejnej reakcji dodaj Znajdź powiązane rekordy (
record_related): kolekcjavariants, kluczproduct_id, wartość{{ctx.selected_id}}, wynikvariants. Aby odczytać sam wybrany produkt, użyjproductsi klucza_record_id. Jeśli relacja opiera się na kluczu biznesowym, wybierz go zarówno w pomocniku przycisków, jak i w akcji odczytu. - Ponownie wybierz gałąź na podstawie wyniku. Jeden wariant pokaż jako kartę przez
{{ctx.variants.first.card}}, kilka wariantów jako przyciski. Każdy przycisk przekazuje ID, a aktualne dane są pobierane po kliknięciu. Nie przechowuj karty ani innych zmiennych pól wcarry.
Wynik odczytu
search.rows zawiera płaską listę rekordów, search.count liczbę wczytanych wierszy, search.first pierwszy rekord, a search.first.name jego pole. Każdy wiersz ma dodatkowe _record_id, _score i _match_type; te nazwy są zarezerwowane. Jeśli nie ma rekordów, poprzednia wartość pierwszego rekordu i jego pól zostaje wyczyszczona.
search.total liczy trafienia wśród sprawdzonych kandydatów. total_exact = false oznacza, że nie sprawdzono całej kolekcji; truncated = true ostrzega o ograniczonej odpowiedzi. Takiego wyniku nie można uznać za pełny ani zagwarantować najlepszego rodzaju dopasowania w całej kolekcji. Jedno zapytanie sprawdza najwyżej 10 000 rekordów i 16 MiB danych; odpowiedź podaje rzeczywiste ograniczenia. Domyślnie zwraca do 100 wierszy, maksymalnie 10 000.
Testowanie i wyjaśnienie
W edytorze wyszukiwania otwórz Przetestuj wyszukiwanie i wpisz konkretny tekst lub ID. To operacja tylko do odczytu: dalsze reakcje, wiadomości i akcje się nie uruchamiają. Podstawienia w dodatkowych filtrach zastąp wcześniej konkretnymi wartościami. Test pokazuje wiersze, rodzaj dopasowania, liczbę sprawdzonych rekordów i ograniczenia. Po zmianie projektu, kolekcji, ustawień lub uprawnień stare wyniki są ukrywane.
Dziennik wykonania pokazuje pola wyszukiwania, rodzaj dopasowania, liczbę sprawdzonych i zwróconych rekordów, ograniczenie wyników i wybraną gałąź. Na diagramie reakcji opisane są wszystkie warunki prowadzące do tej samej reakcji. Przy ponownym oglądaniu zapisu wykonania wyjaśnienie wyszukiwania jest dostępne po otwarciu odpowiedniego zdarzenia, jeśli masz prawo zobaczyć jego treść.
Pomocnik przycisków tworzy domyślnie do 20 przycisków. Maksymalną liczbę przycisków możesz ustawić od 1 do 100. Jest to ograniczenie, nie podział na strony. Pusta lista nie tworzy przycisków. Dla większej liczby wyników dodaj gałąź z prośbą o doprecyzowanie.
W akcji Obliczenie pomocnik Operacja na wczytanej liście tworzy formuły liczby rekordów, pierwszego rekordu, sumy pola i listy etykiet. Oblicza wynik tylko z wczytanych wierszy; gdy wyszukiwanie było niepełne, nie jest to podsumowanie całej kolekcji.
API i MCP
Te same operacje są dostępne przez POST /api/bots/{botID}/collections/{name}/search i /related oraz narzędzia MCP search_records i related_records z uprawnieniem collections:read. Wywołania są ograniczone do bieżącego projektu i regionu. Test przez REST przyjmuje konkretne wartości, a podstawienia szablonowe są wykonywane w akcjach reakcji.
Przetwarzanie wyników i zmiany warunkowe
Wynik kolekcji można przekazać do list_transform, aby odfiltrować i uporządkować wiersze, usunąć duplikaty lub wybrać stronę. list_aggregate oblicza nazwane podsumowania z wczytanych wierszy, opcjonalnie z grupowaniem. Te same akcje działają na zwykłej liście z odpowiedzi HTTP, bez kolekcji.
Jeśli dwie reakcje uruchomione jednocześnie nie powinny ponowić tej samej zmiany stanu, użyj record_update_if: podaj ID, oczekiwane wartości pól i nowe wartości. Sprawdzenie i zmiana jednego rekordu są wykonywane atomowo. Zapisany wynik updated, conflict lub not_found można obsłużyć przez branch_value. To inna operacja niż bezwarunkowa zmiana wszystkich wierszy spełniających filtr.
Konfiguracja, ograniczenia i przykłady.
Ćwiczenie: potwierdzenie zgłoszenia bez ponownego zapisu wyjaśnia sprawdzanie stanu i właściciela oraz osobne odpowiedzi dla updated, conflict i not_found.
Dostęp z Mini App
Rekordy kolekcji można czytać z Telegram Mini App Twojego bota: aplikacja pobiera dane kolekcji według nazwy, z filtrami i limitem. Dzięki temu pokażesz użytkownikowi jego zamówienia, historię lub tabelę wyników bez wychodzenia z Telegrama.
Wskazówki
- Nadawaj polom krótkie nazwy techniczne, na przykład
email,total,paid: łatwiej używać ich w szablonach reakcji. - Aby powtórzenie akcji nie tworzyło nowego wiersza, użyj klucza deduplikacji. Takie zachowanie nazywa się idempotencją.
- Ustaw okres przechowywania (
retention) dla dzienników i tymczasowych danych, które później nie są potrzebne. - Typ
jsonprzyda się, gdy struktura wartości nie jest znana z góry.