قالب‌های پیام و توکن‌ها

ایده

به‌جای یک متن ثابت، یک «قالب» انتخاب می‌کنید که جای خالی دارد: {1} تا {4}. متغیر اول به‌طور پیش‌فرض نام سرویس است و سه متغیر بعدی هر چیزی می‌توانند باشند که شما بخواهید؛ معمولاً مقدارهایی از همان داده‌ای که سیستم‌تان می‌فرستد (مثلاً «علت»، «نام سرور»، «درصد فضای خالی»).

نتیجه یک پیام خوانا و یکدست است. هر کانال (بله و تلگرام، پیامک، تماس صوتی، ایمیل، Push) متن مخصوص خودش را دارد، ولی همه از همان قالب و همان مقدارها ساخته می‌شوند. قالب‌ها را «سیاست هشدار» و «کلید فراخوانی» هر دو استفاده می‌کنند.

قالب‌های آماده

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

نمونه‌ی داده و فیلدها

سیستم نمی‌تواند حدس بزند شما چه می‌فرستید؛ پس فرم از خودتان می‌پرسد. بعد از انتخاب قالب، یک نمونه از همان JSON که سیستم‌تان می‌فرستد را در کادر «داده‌ای که سیستم شما می‌فرستد» بچسبانید:

{"status":"disk full","server":"db-1","meta":{"region":"thr"}}

• فیلدهای نمونه (حتی تودرتو مثل meta.region) خودکار پیدا و به‌صورت برچسب نشان داده می‌شوند.
• برای هر متغیر قالب، از یک فهرست فیلدهای خودتان انتخاب می‌کنید، نه اینکه مسیر را از حفظ بنویسید. «نام سرویس»، «متن ثابت» و «مسیر دلخواه» هم در همان فهرست هستند.
• اگر متغیری به فیلدی اشاره کند که در نمونه نیست، فرم هشدار می‌دهد؛ در پیام «-» می‌نشیند تا نمونه را کامل کنید.
• پایین فرم، «بدنه‌ای که باید بفرستید» را دقیقاً با همان فیلدها می‌بینید؛ همان را به سیستم خودتان بدهید. نمونه همراه سیاست یا کلید ذخیره می‌شود و دفعه‌ی بعد دوباره باز می‌شود.

متن هر کانال

یک متن برای همه‌ی کانال‌ها مناسب نیست؛ پیامک کوتاه است، تماس باید گفتنی باشد، ایمیل موضوع دارد و Push یک عنوان کوتاه. پس هر قالب برای هر کانال متنی جدا دارد و فرم پیش‌نمایش هر کدام را در تب‌های جدا نشان می‌دهد:

در «کلید فراخوانی» فقط کانال‌هایی که کلید می‌تواند بفرستد (بله/تلگرام، پیامک، تماس) پیش‌نمایش داده می‌شوند. مدیر سامانه می‌تواند متن هر کانال هر قالب را از «مدیریت ← قالب‌های پیام» ویرایش کند.

هر متغیر از کجا پر شود؟

• اگر فیلدی در داده‌ی شما نباشد، به‌جایش «-» می‌نشیند (پیام هرگز خالی یا شکسته نمی‌شود).
• هر مقدار حداکثر ۱۰۰ نویسه است؛ خط‌های جدید به فاصله تبدیل می‌شوند.
• مسیر فیلد فقط حرف انگلیسی، عدد و زیرخط دارد و با نقطه تودرتو می‌شود (اندیس آرایه پشتیبانی نمی‌شود).
• فیلدهایی که به هیچ متغیری نگاشته نشده‌اند، در پیام نمی‌آیند.

در سیاست هشدار

1. «سیاست‌ها» ← سیاست جدید (یا ویرایش).
2. پایین فرم، بخش «قالب پیام هشدار»: یک قالب انتخاب کنید و برای هر متغیر منبع را تعیین کنید.
3. برای مانیتور وب‌هوک خطا، نمونه‌ی JSON خودتان را بچسبانید و هر متغیر را به یک فیلد وصل کنید. پیش‌نمایش هر کانال زنده عوض می‌شود؛ ذخیره کنید.

از این به بعد هر قطعی که با این سیاست باز شود، پیام را از همین قالب می‌سازد؛ لینک «توقف اعلان‌ها (Ack)» همچنان به پیام بله/تلگرام/ایمیل اضافه می‌شود. بدون انتخاب قالب، پیام پیش‌فرض سیستم می‌رود.

در کلید فراخوانی

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

# قالب «سرویس + دو توضیح»: {2} ← status، {3} ← server
curl -X POST https://statly.ir/api-backend/trigger/<KEY> \
  -H "Content-Type: application/json" \
  -d '{"status":"disk full","server":"db-1","extra":"ignored"}'

کلیدی که «پیام ثابت» دارد مثل قبل کار می‌کند. هر دو حالت بدنه‌ی JSON تا ۴ کیلوبایت می‌پذیرند و فیلدهای نگاشت‌نشده نادیده گرفته می‌شوند. در صفحه‌ی «کلیدهای فراخوانی»، نمونه‌ی curl هر کلید با فیلدهای همان نگاشت ساخته شده است.

پیامک و توکن‌ها

پیامک فقط از «الگوی تأییدشده‌ی اپراتور» می‌رود. هر قالب آماده یک الگوی اختصاصی دارد که متغیرها را به‌ترتیب می‌گیرد؛ اگر یک قالب هنوز الگو نداشته باشد، پیام آن قالب با الگوی عمومی ارسال می‌شود (فرم، یک یادداشت کوچک نشان می‌دهد).

• متغیرهای ۱ تا ۳ در پیامک فاصله، خط جدید و زیرخط ندارند (به «-» تبدیل می‌شوند)؛ متغیر ۴ حداکثر چهار فاصله می‌پذیرد. هر متغیر حداکثر ۱۰۰ نویسه.
• پس برای پیامک، مقدارهای کوتاه بفرستید: «db-1»، «disk-full»، «۳٪». جمله‌ی طولانی در یک متغیر خوانا نمی‌ماند.
• هزینه‌ی پیامک و تماس از اعتبار رایگان ماهانه‌ی پلن و بعد کیف پول کسر می‌شود؛ بله و تلگرام رایگان‌اند (پلن و کیف پول).

مثال کامل

بکاپ شبانه: «سرویس + دو توضیح»

• مانیتور وب‌هوک خطا با نام «بکاپ دیتابیس».
• سیاست: قالب «سرویس + دو توضیح»؛ {2} ← فیلد reason، {3} ← فیلد server.
• در اسکریپت بکاپ:

curl -fsS -X POST https://statly.ir/api-backend/error-reports/<MONITOR_ID>/report \
  -H "Content-Type: application/json" \
  -d '{"reason":"فضای دیسک پر شد","server":"db-1"}'

پیام در بله: «🔴 هشدار سرویس بکاپ دیتابیس ⏎ فضای دیسک پر شد ⏎ db-1» و در تماس: «هشدار سرویس بکاپ دیتابیس. فضای دیسک پر شد. db-1.»