المجموعات والبيانات
احفظ الطلبات والحجوزات في جدول داخل GetMyBot، ثم استخدم سجلاته في التفاعلات.
في هذه الصفحة
المجموعة تشبه الجدول: يحتوي الصف الواحد على طلب أو حجز واحد. يمكن للبوت إضافة صفوف من أجوبة المستخدمين، ويمكنك مراجعتها وتعديلها في البيانات → المجموعات.
مثلًا، أنشئ مجموعة leads بحقول name وphone وtopic لتسجيل طلبات الاستشارة. بعد الأسئلة يحفظ البوت الاسم والهاتف والموضوع في صف واحد، ويمكنه البحث فيه لاحقًا.
ما المجموعة؟
تحدد الحقول الأعمدة، مثل «الهاتف» و«الموضوع». ويحتوي السجل على قيم صف واحد. تسمى قائمة الحقول وأنواعها «المخطط». يُخزن السجل تقنيًا كمستند JSON، لذا لا تتطلب إضافة حقل جديد إعادة إنشاء الصفوف المحفوظة.
اسم المجموعة فريد داخل البوت ويُستخدم معرّفًا في أفعال التفاعلات، مثل leads أو orders أو scores.
أنواع الحقول
| النوع | ما يخزنه | مثال |
|---|---|---|
text | سطر نصي | الاسم أو البريد أو التعليق |
number | رقم | المبلغ أو العدد أو النقاط |
bool | نعم أو لا: true / false | هل دُفع الطلب؟ |
datetime | التاريخ والوقت | موعد الحجز |
json | كائن أو قائمة متداخلة | منتجات الطلب وخصائصها |
يؤثر النوع في طريقة تعديل الحقل في الواجهة وتحويل قيمته عند الحفظ. المخطط مرن: إذا احتوى السجل على حقل خارج المخطط، يُحفظ ويظهر في عمود مستقل.
إنشاء مجموعة
- افتح البيانات → المجموعات وانقر إضافة.
- اكتب الاسم بحروف لاتينية ودون مسافات، ليسهل استخدامه في التفاعلات.
- أضف الأعمدة بزر حقل واختر نوع كل منها.
- اضبط قواعد الاحتفاظ عند الحاجة ثم احفظ.
عرض السجلات وتعديلها
افتح زر الجدول على بطاقة المجموعة لعرض نافذة البيانات:
- عرض: قائمة بالصفوف تبدأ بالأحدث، وكل قيمة في خليتها.
- إضافة سجل: نموذج بحسب المخطط؛ مفتاح تبديل لـ
boolوحقل JSON لـjson، مثلًا. - تعديل (القلم): يغير صفًا موجودًا.
- حذف (سلة المهملات): يزيل الصف.
تضيف أفعال البوت السجلات تلقائيًا أيضًا. التعديل اليدوي والكتابة التلقائية يعملان في المجموعة نفسها.
الاحتفاظ بالبيانات (retention)
حتى لا تنمو المجموعة باستمرار، يمكنك تحديد:
- الاحتفاظ بحد أقصى من السجلات: تُحذف السجلات الأقدم إذا تجاوز العدد الحد.
- الاحتفاظ لمدة أقصاها (بالأيام): تُحذف السجلات الأقدم من المدة.
مثلًا، يناسب 30 يومًا سجلًا مؤقتًا. يتم التنظيف دوريًا، لا بالضبط عند نهاية المدة. يمكنك الجمع بين الحدين. لا تضبط مدة حذف للطلبات التي لا تزال تحتاجها.
استخدام البيانات في التفاعلات
تتيح أفعال التفاعل:
- إنشاء سجل: يضيف صفًا من الاستبدالات، مثل
{{user_id}}و{{text}}. مفتاح منع التكرار يجعل الاستدعاء الثاني بالمفتاح نفسه يحدّث الصف بدل إنشاء صف جديد؛ مثل طلب واحد محدث لكل شخص. - تحديث سجلات: يغير الصفوف المطابقة لشرط.
- البحث عن سجلات: يقرأ الصفوف إلى سياق التنفيذ كقائمة لتمريرها إلى الخطوات التالية.
- Read collection page (
record_page): يقرأ السجلات على دفعات، مثل بطاقتين مع زر الصفحة التالية. - Aggregate whole collection (
record_aggregate): يحسب العدد والمجاميع لجميع السجلات المطابقة ضمن قواعد الاحتفاظ. لا يقتصر الحساب على الصفحة الأولى المحمّلة. - Atomic collection transaction (
collection_transaction): يفحص الشروط ويحفظ عدة تغييرات معًا، مثل حجز آخر مقعد وإنشاء طلب. إذا تعارضت عملية، تُلغى التغييرات السابقة معها. - حذف سجلات: يحذف الصفوف وفق شرط.
- حلقة على قائمة (for-each): تمر على قائمة من السياق وتنفذ أفعالًا لكل عنصر، مثل تحديث كل صف أو حساب الإجمالي أو إرساله إلى خدمة خارجية.
هكذا يمكن للبوت إدارة علاقات العملاء والطلبات والنقاط والتقارير دون قاعدة بيانات خارجية. تعرض تمارين عملية متابعة الكتالوج وحساب إجمالي جميع الطلبات المطابقة وحجز آخر مكان. صفحة القائمة المحمّلة وصفحة المجموعة والإجمالي الكلي نتائج مختلفة، وتوضح التمارين ما يصل إلى الخطوة التالية.
الحلقة ليست أداة إرسال جماعي. تعالج حتى 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}}، وعدة خيارات كأزرار. ينقل كل زر المعرّف وتُقرأ البيانات الحالية بعد الضغط. لا تضع البطاقة أو غيرها من الحقول القابلة للتغيير في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 ميبيبايت من البيانات؛ تظهر الحدود الفعلية في الرد. يعود افتراضيًا حتى 100 صف، وبحد أقصى 10 000.
الفحص والتفسير
في محرر البحث افتح فحص البحث وأدخل نصًا أو معرّفًا محددًا للتجربة. هذه قراءة فقط؛ لا تُشغَّل التفاعلات أو الرسائل أو الأفعال التالية. استبدل الرموز في الفلاتر الإضافية بقيم فعلية قبل الفحص. يعرض الاختبار الصفوف ونوع التطابق وعدد السجلات المفحوصة والحدود. تختفي النتيجة القديمة إذا تغير المشروع أو المجموعة أو الإعدادات أو حقوق الوصول.
يعرض سجل التنفيذ حقول البحث ونوع التطابق وأعداد الصفوف المفحوصة والعائدة والحد والفرع المختار. وتُبيّن خريطة التفاعل كل الشروط المؤدية إلى التفاعل نفسه. عند مراجعة سجل التنفيذ، يمكنك فتح الحدث المعني لرؤية تفسير البحث إذا كنت تملك حق الاطلاع على محتواه.
ينشئ مساعد الأزرار حتى 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: أدخل المعرّف والحقول المتوقعة والقيم الجديدة. يتم الفحص والتعديل معًا لسجل واحد. عالج النتيجة updated أو conflict أو not_found عبر branch_value. يختلف ذلك عن تحديث كل الصفوف المطابقة دون شرط. الإعدادات والحدود والأمثلة.
يشرح درس تأكيد الحجز مرة واحدة فحص الحالة والمالك والردود المنفصلة للحالات updated وconflict وnot_found.
الوصول من Mini App
يمكن لتطبيق Telegram Mini App الخاص بالبوت قراءة سجلات المجموعة باسمها مع الفلاتر وحد العدد. وهكذا يرى المستخدم طلباته أو تاريخه أو لوحة الصدارة داخل Telegram.
نصائح
- استخدم أسماء حقول قصيرة بحروف لاتينية، مثل
emailوtotalوpaid، لتسهيل إدراجها في قوالب التفاعل. - لمنع إنشاء صف جديد عند إعادة الفعل، استخدم مفتاح منع التكرار. تسمى هذه الخاصية «ثبات نتيجة التكرار» أو idempotency.
- اضبط مدة احتفاظ (
retention) للسجلات المؤقتة التي لم تعد لازمة. - يفيد نوع
jsonعندما لا تكون بنية القيمة محددة مسبقًا.