בסיס הידע של 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}}. מפתח מניעת כפילויות גורם להפעלה חוזרת עם אותו מפתח לעדכן את השורה במקום ליצור חדשה. למשל, כך שומרים פנייה עדכנית אחת לכל אדם.
  • עדכן רשומות: משנה שורות שעומדות בתנאי.
  • חפש רשומות: קוראת שורות להקשר הביצוע כרשימה לעיבוד בהמשך.
  • 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. הקישור מתאר את תפקיד השדה, אך אינו מעדכן או מוחק רשומות קשורות באופן מדורג.

  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}}. ודאו ששדה הכיתוב נכלל בתוצאה. עורך הכפתורים המתקדם נשאר זמין.
  4. בתגובה הבאה הוסיפו מציאת רשומות קשורות (record_related): האוסף variants, המפתח product_id, הערך {{ctx.selected_id}} ושם התוצאה variants. לקריאת המוצר שנבחר עצמו השתמשו ב־products ובמפתח _record_id. אם הקשרים נשמרים במפתח עסקי, בחרו אותו גם בעוזר הכפתורים וגם בפעולת הקריאה.
  5. שוב בחרו ענף לפי התוצאה. הציגו רשומה אחת ככרטיס באמצעות {{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 MiB נתונים; התשובה מציינת את ההגבלות שחלו בפועל. כברירת מחדל חוזרות עד 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 מתאים כשמבנה הערך אינו קבוע מראש.