پایگاه دانش GetMyBot

مجموعه‌ها و داده‌ها

درخواست‌ها، سفارش‌ها و رزروها را در GetMyBot نگه دارید: جدول بسازید، داده اضافه کنید و در واکنش‌ها به کار ببرید.

در این صفحه

مجموعه شبیه جدول است: هر ردیف یک درخواست، سفارش یا رزرو را نگه می‌دارد. بات می‌تواند پاسخ‌های کاربران را به ردیف تبدیل کند و شما می‌توانید در داده‌ها → مجموعه‌ها آنها را ببینید و تغییر دهید.

برای مثال، برای رزرو مشاوره مجموعهٔ leads با فیلدهای name، phone و topic بسازید. پس از پرسیدن سؤال‌ها، بات نام، تلفن و موضوع را در یک ردیف ذخیره می‌کند. بعداً می‌توانید آن را پیدا و در واکنش به کار ببرید.

مجموعه چیست

فیلدها ستون‌هایی مانند «تلفن» و «موضوع» را تعریف می‌کنند. رکورد مقدارهای یک ردیف است. فهرست فیلدها و نوع آنها طرح داده یا schema نام دارد. از نظر فنی، رکورد یک سند JSON است؛ افزودن فیلد تازه نیاز ندارد ردیف‌های قبلی دوباره ساخته شوند.

نام مجموعه در هر بات یکتا است و در اقدام‌های واکنش به‌عنوان شناسه به کار می‌رود، مانند leads، orders و scores.

نوع فیلدها

هنگام ساخت مجموعه، برای هر فیلد نوع را انتخاب کنید:

نوعدادهنمونه
textمتننام، ایمیل یا نظر
numberعددمبلغ، تعداد یا امتیاز
boolبله یا خیر: true / falseآیا سفارش پرداخت شده است؟
datetimeتاریخ و زمانزمان کلاس
jsonشیء یا فهرست تو در توکالاهای سفارش و ویژگی‌های آنها

نوع فیلد تعیین می‌کند مقدار در رابط چگونه ویرایش و هنگام ذخیره چگونه تبدیل شود. طرح داده سخت‌گیرانه نیست: فیلد خارج از طرح نیز در رکورد ذخیره و به‌صورت ستون جدا نمایش داده می‌شود.

ساخت مجموعه

  1. داده‌ها → مجموعه‌ها را باز کنید و افزودن را بزنید.
  2. نام را با حروف لاتین و بدون فاصله وارد کنید تا در واکنش‌ها آسان‌تر به آن ارجاع دهید.
  3. با فیلد ستون‌ها را اضافه و نوع هر کدام را انتخاب کنید.
  4. در صورت نیاز قانون‌های نگهداری زیر را تعیین و ذخیره کنید.

دیدن و ویرایش رکوردها

در کارت مجموعه، دکمهٔ دارای نماد جدول پنجرهٔ داده‌ها را باز می‌کند:

  • مشاهده: ردیف‌ها را از جدیدترین به قدیمی‌ترین نشان می‌دهد؛ هر فیلد در یک خانه.
  • افزودن رکورد: فرم مطابق طرح مجموعه باز می‌کند؛ برای bool کلید روشن و خاموش و برای json کادر JSON دارد.
  • ویرایش (مداد): ردیف موجود را تغییر می‌دهد.
  • حذف (سطل): ردیف را پاک می‌کند.

اقدام‌های بات نیز می‌توانند رکوردها را خودکار اضافه کنند. ویرایش دستی و ثبت خودکار روی یک مجموعه کار می‌کنند.

مدت نگهداری (retention)

برای جلوگیری از رشد بی‌پایان مجموعه، پاک‌سازی خودکار بگذارید:

  • حداکثر رکوردهای ذخیره‌شده: پس از عبور از سقف، قدیمی‌ترین رکوردها حذف می‌شوند.
  • نگهداری حداکثر (روز): رکوردهای قدیمی‌تر از مدت انتخاب‌شده حذف می‌شوند.

برای دفتر موقت، ۳۰ روز ممکن است کافی باشد. پاک‌سازی دوره‌ای انجام می‌شود، نه دقیقاً در لحظهٔ پایان مدت. هر دو قانون را می‌توانید با هم روشن کنید. برای سفارش‌هایی که هنوز لازم‌اند، مدت نگهداری تعیین نکنید.

کار با داده در واکنش‌ها

اقدام‌های واکنش به مجموعه‌ها دسترسی دارند:

  • ایجاد رکورد: ردیفی با مقدارهایی مثل {{user_id}} و {{text}} اضافه می‌کند. کلید جلوگیری از تکرار مانع ردیف‌های یکسان می‌شود: فراخوانی دوباره با همان کلید، ردیف موجود را به‌روز می‌کند. مثلاً با ID کاربر، فقط یک درخواست تازه برای هر فرد نگه دارید.
  • به‌روزرسانی رکوردها: ردیف‌های مطابق شرط را تغییر می‌دهد.
  • جستجوی رکوردها: ردیف‌ها را به‌صورت فهرست در زمینهٔ اجرا می‌گذارد.
  • Read collection page (record_page): رکوردها را بخش‌بخش می‌خواند، مثلاً دو کارت با دکمهٔ صفحهٔ بعد.
  • Aggregate whole collection (record_aggregate): تعداد و جمع همهٔ رکوردهای مطابق در محدودهٔ قانون‌های نگهداری را حساب می‌کند؛ خواندن فقط صفحهٔ اول، این محاسبه را محدود نمی‌کند.
  • Atomic collection transaction (collection_transaction): شرط‌ها را بررسی و چند تغییر را با هم ذخیره می‌کند، مثلاً یک صندلی را رزرو و درخواست را ثبت می‌کند. در تعارض، تغییرهای قبلی همان تراکنش نیز برگردانده می‌شوند.
  • حذف رکوردها: ردیف‌های مطابق شرط را پاک می‌کند.
  • حلقه روی لیست: فهرست موجود در زمینه را طی می‌کند و برای هر عضو اقدام درونی انجام می‌دهد، مانند به‌روزرسانی، جمع زدن یا فرستادن به سرویس بیرونی.

به این ترتیب بات می‌تواند درخواست‌ها، امتیازها و گزارش‌ها را بدون پایگاه دادهٔ بیرونی اداره کند.

درس‌های کاربردی ادامهٔ کاتالوگ، جمع کل سفارش‌های مطابق و رزرو آخرین جا را نشان می‌دهند. صفحهٔ فهرست بارگیری‌شده، صفحهٔ مجموعه و نتیجهٔ کل مجموعه سه کار متفاوت دارند؛ درس‌ها نشان می‌دهند گام بعد چه داده‌ای می‌گیرد.

حلقه ابزار ارسال همگانی نیست. در یک اجرا حداکثر ۵۰۰ عضو را می‌گیرد و تمام رویداد حداکثر ۵۰ پیام می‌فرستد. اگر در حلقه پیام بفرستید، ۵۰ پیام اول امکان ارسال دارند و بقیه رد می‌شوند. برای پیام به افراد مجموعه، بخشی از مخاطبان بسازید و ارسال همگانی را اجرا کنید؛ سرعت، مکث و ثبت ارسال دارد. سقف یک رویداد.

کاتالوگ: جست‌وجو، انتخاب و کارت

برای شروع درس جست‌وجوی کلاس را بخوانید. توضیح می‌دهد چه مجموعه‌هایی آماده کنید، اقدام‌ها را به چه ترتیبی بچینید و نتیجهٔ خالی، چند نتیجه و فشار دکمهٔ قدیمی را چگونه بررسی کنید.

داده‌های کاتالوگ را جدا از واکنش‌ها نگه دارید. مثلاً 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}} را می‌گذارد. بررسی کنید name در فیلدهای نتیجه باشد. ویرایشگر پیشرفتهٔ دکمه همچنان در دسترس است.
  4. در واکنش بعدی یافتن رکوردهای مرتبط (record_related) را بگذارید: مجموعهٔ variants، کلید product_id، مقدار {{ctx.selected_id}} و نتیجهٔ variants. برای خواندن خودِ رکورد انتخاب‌شده، از products و کلید _record_id استفاده کنید. اگر ارتباط با کلید کاری دیگری ثبت شده، همان کلید را در راهنمای دکمه و اقدام خواندن برگزینید.
  5. دوباره بر اساس نتیجه شاخه انتخاب کنید. یک رکورد را با {{ctx.variants.first.card}} به‌صورت کارت نشان دهید؛ چند گزینه را با دکمه. هر دکمه ID را می‌فرستد و دادهٔ روز پس از فشار خوانده می‌شود. کارت یا فیلدهای تغییرپذیر را در carry نگه ندارید.

نتیجهٔ خواندن

search.rows فهرست رکوردها، search.count تعداد ردیف‌های بارگیری‌شده، search.first نخستین رکورد و search.first.name یک فیلد آن است. هر ردیف _record_id، _score و _match_type هم دارد؛ این سه نام رزرو شده‌اند. وقتی رکوردی نیست، مقدار قبلی نخستین رکورد و فیلدهایش پاک می‌شود.

search.total تعداد تطابق‌ها در میان موارد بررسی‌شده است. total_exact = false یعنی کل مجموعه بررسی نشده؛ truncated = true یعنی نتیجه محدود شده است. در این حالت نباید نتیجه را کامل یا بهترین نوع تطابق در کل مجموعه بدانید. هر درخواست تا ۱۰٬۰۰۰ رکورد و ۱۶ MiB داده را بررسی می‌کند و پاسخ، محدودیت‌های واقعی را نشان می‌دهد. پیش‌فرض تا ۱۰۰ ردیف برمی‌گردد، حداکثر ۱۰٬۰۰۰.

بررسی و توضیح نتیجه

در ویرایشگر جست‌وجو آزمایش جست‌وجو را باز و متن یا ID مشخص وارد کنید. این فقط خواندن است: واکنش، پیام یا اقدام بعدی اجرا نمی‌شود. جایگزینی‌های فیلترهای دیگر را از پیش با مقدار واقعی عوض کنید. آزمایش ردیف‌ها، نوع تطابق، تعداد رکوردهای بررسی‌شده و محدودیت‌ها را نشان می‌دهد. با تغییر پروژه، مجموعه، تنظیمات یا مجوز، نتیجهٔ قدیمی پنهان می‌شود.

گزارش اجرا فیلدهای جست‌وجو، نوع تطابق، تعداد رکوردهای بررسی‌شده و برگشتی، محدودیت و شاخهٔ انتخاب‌شده را نشان می‌دهد. در نمودار واکنش، همهٔ شرط‌هایی که به یک واکنش می‌رسند نوشته شده‌اند. هنگام باز کردن دوبارهٔ گزارش، توضیح جست‌وجو در رویداد مربوط دیده می‌شود، اگر اجازهٔ دیدن محتوایش را داشته باشید.

راهنمای دکمه به‌طور پیش‌فرض تا ۲۰ دکمه می‌سازد. بیشترین تعداد دکمه را می‌توانید از ۱ تا ۱۰۰ تغییر دهید؛ این سقف تعداد است، نه صفحه‌بندی. فهرست خالی دکمه نمی‌سازد. برای نتیجهٔ بزرگ، شاخه‌ای برای دقیق‌تر کردن جست‌وجو اضافه کنید.

در اقدام محاسبه، راهنمای عملیات روی فهرست بارگیری‌شده فرمول‌های تعداد، نخستین رکورد، جمع یک فیلد و فهرست عنوان‌ها را می‌سازد. محاسبه فقط روی ردیف‌های بارگیری‌شده است و در نتیجهٔ ناقص، جمع کل مجموعه نیست.

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 را با ID، فیلدهای مورد انتظار و مقدارهای تازه به کار ببرید. بررسی و تغییر برای یک رکورد اتمی است. وضعیت ذخیره‌شدهٔ updated، conflict یا not_found را می‌توانید با branch_value جداگانه مدیریت کنید. این با تغییر بی‌شرط همهٔ ردیف‌های مطابق فیلتر فرق دارد.

تنظیمات، محدودیت‌ها و نمونه‌ها.

تمرین تأیید درخواست بدون ثبت دوباره بررسی وضعیت و مالک و پاسخ‌های جدا برای updated، conflict و not_found را توضیح می‌دهد.

دسترسی از Mini App

Telegram Mini App بات می‌تواند رکوردهای مجموعه را بخواند: رابط با نام مجموعه، فیلترها و سقف تعداد، داده را درخواست می‌کند. به این ترتیب کاربر سفارش‌ها، سابقه یا جدول امتیاز را در خود Telegram می‌بیند.

نکته‌ها

  • برای فیلدها نام کوتاه لاتین بگذارید (email، total، paid) تا گذاشتن آنها در الگوهای واکنش آسان شود.
  • اگر اجرای دوبارهٔ یک اقدام نباید ردیف تازه بسازد، از کلید جلوگیری از تکرار استفاده کنید؛ این ویژگی idempotency نام دارد.
  • برای گزارش‌ها و دادهٔ موقتی که دیگر لازم نیستند، مدت نگهداری (retention) بگذارید.
  • وقتی ساختار مقدار از پیش مشخص نیست، از json استفاده کنید.