Koleksiyonlar ve veriler
Başvuruları, siparişleri ve ders kayıtlarını GetMyBot'ta saklayın: tablo oluşturun, veri ekleyin ve tepkilerde kullanın.
Bu sayfada
Koleksiyon bir tablo gibidir: her satır bir başvuruyu, siparişi veya ders kaydını temsil eder. Bot, kişilerin yanıtlarından satır ekleyebilir. Siz de bunları Veriler → Koleksiyonlar bölümünde görebilir ve düzenleyebilirsiniz.
Örneğin danışmanlık başvuruları için name, phone, topic alanlarına sahip leads koleksiyonu oluşturun. Bot soruları sorduktan sonra adı, telefonu ve konuyu tek satıra kaydeder. Sonra bu kayıtları bulup tepkilerde kullanabilirsiniz.
Koleksiyon nedir?
Alanlar «Telefon» ve «Konu» gibi sütunları tanımlar. Kayıt, bir satırın değerlerini içerir. Alanların ve türlerinin listesine şema denir. Teknik olarak her kayıt JSON belgesidir; yeni alan eklemek için mevcut satırları yeniden oluşturmanız gerekmez.
Koleksiyon adı bir bot içinde benzersizdir ve tepki eylemlerinde kimlik olarak kullanılır: leads, orders, scores gibi.
Alan türleri
Koleksiyonu oluştururken alanları ve her alanın türünü seçersiniz:
| Tür | Sakladığı değer | Örnek |
|---|---|---|
text | Metin | Ad, e-posta, yorum |
number | Sayı | Tutar, adet, puan |
bool | Evet/hayır: true / false | Sipariş ödendi mi? |
datetime | Tarih ve saat | Ders zamanı |
json | İç içe nesne veya liste | Ürün özellikleriyle sipariş içeriği |
Tür, arayüzde düzenlemeyi ve kaydederken değer dönüşümünü etkiler. Şema katı değildir: kayıtta şema dışı bir alan varsa yine saklanır ve ayrı bir sütunda görünür.
Koleksiyon oluşturma
- Veriler → Koleksiyonlar bölümünü açıp Ekle düğmesine basın.
- Ad girin. Tepkilerde kolay kullanmak için Latin harfleri ve boşluksuz ad tercih edin.
- Alan düğmesiyle sütunları ekleyin ve türlerini seçin.
- Gerekirse saklama kurallarını aşağıdaki gibi ayarlayıp kaydedin.
Kayıtları görme ve düzenleme
Koleksiyon kartındaki tablo simgeli düğme, kayıtların bulunduğu Veriler penceresini açar:
- Görüntüle: tüm satırlar, en yenisi önce gelecek şekilde alanlarıyla listelenir.
- Kayıt ekle: koleksiyon şemasına göre form açar;
booliçin anahtar,jsoniçin JSON giriş alanı gibi türe uygun düzenleme sağlar. - Düzenle (kalem): mevcut satırı değiştirir.
- Sil (çöp kutusu): satırı kaldırır.
Bot tepkilerindeki eylemler de aynı koleksiyona otomatik kayıt ekleyebilir. Elle düzenleme ile otomatik kayıt aynı veriler üzerinde çalışır.
Saklama süresi (retention)
Koleksiyonun sınırsız büyümemesi için otomatik temizleme kuralları ayarlayın:
- En fazla şu kadar kayıt sakla: sınır aşılırsa en eski kayıtlar silinir.
- Şu kadar günden uzun saklama: daha eski kayıtlar silinir.
Örneğin geçici bir günlük için 30 gün seçebilirsiniz. Temizleme, sürenin dolduğu anda değil, düzenli aralıklarla yapılır. İki sınırı birlikte kullanabilirsiniz. Hâlâ gereken siparişlerde saklama süresi belirlemeyin.
Tepkilerden verilerle çalışma
Koleksiyonlar tepki oluşturucuya bağlıdır. Şu eylemler kullanılabilir:
- Kayıt oluştur:
{{user_id}}ve{{text}}gibi yerleştirmelerden alınan değerlerle satır ekler. Tekilleştirme anahtarı yinelenen satırları önler: aynı anahtarla tekrar çağrıldığında mevcut satır güncellenir. Kullanıcı ID'siyle kişi başına tek güncel başvuru tutabilirsiniz. - Kayıtları güncelle: koşula uyan satırları değiştirir.
- Kayıtları sorgula: satırları, sonraki adımlarda kullanılacak dizi olarak yürütme bağlamına okur.
- Koleksiyon sayfasını oku (
record_page): kayıtları parça parça okur; örneğin ikişer kart ve sonraki sayfa düğmesi. - Tüm koleksiyonun toplamları (
record_aggregate): saklama kuralları içindeki bütün eşleşen kayıtların sayısını ve toplamlarını hesaplar. Yalnızca ilk sayfayı yüklemek bu hesabı sınırlamaz. - Koleksiyonların atomik işlemi (
collection_transaction): koşulları kontrol edip birkaç değişikliği birlikte kaydeder; örneğin bir yer ayırır ve başvuru oluşturur. Çakışma halinde önceki değişiklikler de geri alınır. - Kayıtları sil: koşula uyan satırları kaldırır.
- Döngü (for-each): bağlamdaki dizinin her öğesi için iç eylemleri çalıştırır; örneğin her satırı günceller, toplam hesaplar veya dış hizmete gönderir.
Böylece bot, harici veritabanı olmadan CRM tutabilir, başvuruları biriktirebilir, puan verebilir ve rapor oluşturabilir.
Uygulamalı dersler, katalogda sonraki sayfayı, tüm uygun siparişlerin toplamını ve son boş yeri ayırmayı gösterir. Yüklenmiş liste sayfası, koleksiyon sayfası ve bütün koleksiyonun toplamı farklı amaçlara hizmet eder; derslerde sonraki adımın hangi veriyi aldığı açıklanır.
Döngüyü toplu gönderim için kullanmayın. Tek döngü en fazla 500 öğe işler; olayın tamamı en fazla 50 mesaj gönderebilir. Döngü içinden mesaj gönderirseniz ilk 50 teslim edilir, sonrakiler reddedilir. Koleksiyondaki kişilere yazmak için segment oluşturup toplu gönderim yapın. Bu özellikte hız, duraklatma ve teslimat takibi vardır. Sınırlar: Eylemler → Bir olayın bütçesi.
Katalog: arama, seçim ve ürün kartı
Başlamak için ders arama örneğini izleyin. Hangi koleksiyonların gerektiğini, eylemlerin sırasını ve boş sonuç, birden fazla eşleşme veya eski düğmeye basma durumlarını nasıl deneyeceğinizi gösterir.
Katalog verilerini tepkilerden ayrı saklayın. Örneğin products koleksiyonunda name ve aliases; variants koleksiyonunda product_id, name ve card bulunur. variants.product_id alanında Başka koleksiyonla ilişki seçeneğini açın: products, _record_id anahtarı ve name görünen alanını seçin. Bu ilişki alanın amacını belirtir; kayıtları otomatik olarak değiştirmez veya silmez.
- Gelen metin tepkisine Koleksiyonda ara (
record_search) ekleyin.productskoleksiyonunu,{{text}}sorgusunu,namearama alanını,aliaseseş anlamlı alanını seçip sonucusearcholarak saklayın. Eş anlamlılar tek metin veya JSON metin dizisi olabilir. Arama büyük/küçük harfi ve Rusça е/ё harflerini ayırt etmez; noktalama işaretleri boşluğa dönüşür. - Kaynak olarak
searchseçip Sonraki adımı seç (branch_result) ekleyin. İlk eşleşen dal çalışır. Önce Eksik sonuç için soruyu netleştirme önerisi verin, ardından Sonuç yok, Yakın eşleşme, Tek kayıt ve Birden fazla kayıt dallarını ayarlayın. Yakın eşleşmede onay isteyin. Boş veya tekil sonuca güvenmek için tam sonuç gerekir. - Birden fazla sonuç için mesajda Bulunan kayıtlardan düğmeler bölümünü açın. Kaynak
search, düğme yazısınameve sonraki tepkiyi seçin. Yardımcıbuttons_from.over = search.rows, yazı şablonunu vecarry.selected_id = {{item._record_id}}değerini doldurur. Yazı alanının sonuç alanları arasında bulunduğunu kontrol edin. Gelişmiş düğme düzenleyicisi de kullanılabilir. - Sonraki tepkiye İlgili kayıtları bul (
record_related) ekleyin:variantskoleksiyonu,product_idanahtarı,{{ctx.selected_id}}değeri vevariantssonuç adı. Seçilmiş ürünün kendisini okumak içinproductsve_record_idanahtarını kullanın. İlişkiler başka bir iş anahtarıyla tutuluyorsa aynı anahtarı düğme yardımcısında ve okuma eyleminde seçin. - Sonuca göre yeniden dal seçin. Tek kaydı
{{ctx.variants.first.card}}ile kart olarak gösterin; birden fazla çeşidi düğmelerle sunun. Her düğme ID iletir, güncel bilgiler tıklamadan sonra okunur. Kartı veya değişebilir başka alanlarıcarryiçinde saklamayın.
Okuma sonucu
search.rows düz kayıt listesini, search.count yüklenen satır sayısını, search.first ilk kaydı, search.first.name ise o kaydın alanını içerir. Her satıra _record_id, _score ve _match_type eklenir; bu adlar ayrılmıştır. Kayıt yoksa önceki ilk kayıt ve alanları temizlenir.
search.total, incelenmiş adaylardaki eşleşmeleri sayar. total_exact = false, koleksiyonun tamamının incelenmediği; truncated = true ise sonucun sınırlandığı anlamına gelir. Böyle bir sonucu tam saymayın veya koleksiyonun en iyi eşleşmesinin bulunduğunu varsaymayın. Bir istekte en fazla 10.000 kayıt ve 16 MiB veri incelenir; yanıt gerçek sınırları bildirir. Varsayılan en fazla 100, üst sınır 10.000 satırdır.
Aramayı sınama ve açıklama
Arama düzenleyicisinde Aramayı test et bölümünü açıp belirli bir test metni veya ID girin. Bu işlem yalnızca okur: sonraki tepkiler, mesajlar ve başka eylemler çalışmaz. Ek filtrelerdeki yerleştirmeleri önceden somut değerlerle değiştirin. Test, satırları, eşleşme türünü, incelenen kayıt sayısını ve sınırları gösterir. Proje, koleksiyon, ayarlar veya erişim hakları değişince eski sonuçlar gizlenir.
Çalıştırma günlüğü arama alanlarını, eşleşme türünü, incelenen ve dönen satır sayılarını, sonuç sınırını ve seçilen dalı gösterir. Tepki şemasında aynı tepkiye giden bütün koşullar etiketlenir. Kaydedilmiş bir çalıştırmayı yeniden açtığınızda, içeriğine erişme hakkınız varsa ilgili olayın arama açıklamasını da görebilirsiniz.
Düğme yardımcısı varsayılan olarak en fazla 20 düğme oluşturur. En fazla düğme değerini 1 ile 100 arasında değiştirebilirsiniz. Bu bir sınırdır, sayfalama değildir. Boş liste düğme oluşturmaz. Daha çok sonuç için sorguyu daraltan bir dal ekleyin.
Hesaplama eylemindeki Yüklenmiş liste işlemi yardımcısı; kayıt sayısı, ilk kayıt, bir alanın toplamı ve etiket listesi için formüller oluşturur. Hesap yalnızca yüklenen satırlarda yapılır; eksik sonuçta bütün koleksiyonun toplamı değildir.
API ve MCP
Aynı işlemler POST /api/bots/{botID}/collections/{name}/search, /related ve collections:read yetkisiyle search_records, related_records MCP araçları üzerinden kullanılabilir. Çağrılar mevcut proje ve bölgeyle sınırlıdır. REST testinde somut değerler gönderilir; şablon yerleştirmeleri tepki eylemlerinde işlenir.
Sonucu işleme ve koşullu değişiklikler
Koleksiyon sonucunu list_transform eylemine vererek satırları filtreleyebilir, sıralayabilir, tekilleştirebilir veya bir sayfa alabilirsiniz. list_aggregate, yüklenmiş satırlarda isteğe bağlı gruplamayla adlandırılmış toplamlar hesaplar. İki eylem, koleksiyon olmadan HTTP yanıtındaki normal listelerle de çalışır.
Aynı durum geçişini iki eşzamanlı çalıştırmanın tekrar uygulamaması için record_update_if kullanın: ID'yi, beklenen alanları ve yeni değerleri girin. Kontrol ve değişiklik tek kayıt için atomik yapılır. Kaydedilen updated, conflict veya not_found durumunu branch_value ile işleyin. Bu, filtreye uyan bütün satırları koşulsuz değiştirmekten farklıdır.
Ayarlar, sınırlar ve örnekler.
Uygulama: başvuruyu ikinci kez kaydetmeden onaylama, durum ve sahip kontrolünü, ayrıca updated, conflict ve not_found için ayrı yanıtları açıklar.
Mini App erişimi
Botunuzun Telegram Mini App uygulaması koleksiyon kayıtlarını okuyabilir: ön yüz, koleksiyon adı, filtreler ve sınırla veri ister. Böylece kişiye siparişlerini, geçmişini veya sıralama tablosunu doğrudan Telegram'da gösterebilirsiniz.
İpuçları
- Alanlara
email,total,paidgibi kısa teknik adlar verin; tepki şablonlarında kullanmaları kolaydır. - Eylemin tekrarı yeni satır oluşturmamalıysa tekilleştirme anahtarı kullanın. Bu özelliğe idempotentlik denir.
- Artık gerekmeyen günlükler ve geçici veriler için saklama süresi (
retention) ayarlayın. - Değerin yapısı önceden belli değilse
jsontürü uygundur.