پرش به محتویات

تابع چیست؟

تابع دستورالعملی است که چند مقدار نام‌دار (پارامترهایش) را به یک فرمان شِل تبدیل می‌کند. هر دکمه در منوی شما دقیقاً نام یک تابع را در فیلد function خود دارد.

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

با لمس دکمه چه رخ می‌دهد

  1. ربات تابع نام‌برده‌شده در فیلد function دکمه را پیدا می‌کند.
  2. مقادیر نوشته‌شده روی دکمه را جمع می‌کند.
  3. از آن مقادیر یک فرمان شِل می‌سازد.
  4. فرمان را در Shell اجرا می‌کند و خروجی را به‌شکل بلوک کد به گفتگو می‌فرستد.

اگر تابع وجود نداشته باشد یا مقدار موردنیاز آن گم شده باشد، ربات اصلاً شروع نمی‌شود: validate ابتدا مشکل را گزارش می‌کند.

یک نمونهٔ کامل

تابع command توکار و همیشه موجود است. هرچه در فیلد command دکمه بنویسید اجرا می‌کند.

استفاده از تابع توکار command

دکمهٔ Uptime
- name: Uptime
  type: button
  function: command
  command: "uptime"

Uptime را بزنید؛ ربات uptime را روی سرور اجرا می‌کند و خروجی را برمی‌گرداند.

فرستادن مقادیر از دکمه

هر مقدار را مستقیم روی دکمه بنویسید. دو راه وجود دارد:

  1. از فیلدهای میانبر command، path و args استفاده کنید. هرکدام پارامتری با همان نام را پر می‌کنند.
  2. برای هر پارامتر دیگر، نام آن را به‌عنوان کلیدی روی دکمه به کار ببرید.

فرستادن URL با نام پارامتر

دکمهٔ بررسی API
- name: Check API
  type: button
  function: curl-url
  url: "https://example.com/health"

اینجا url با پارامتر url تعریف‌شده توسط curl-url مطابقت دارد. همین قاعده برای نام‌هایی مانند host، unit و lines برقرار است.

مقادیر را درون params: نگذارید

params: در فایل تابع سفارشی قرار می‌گیرد و مقادیر پذیرفته‌شده توسط تابع را تعریف می‌کند. روی دکمه، هر مقدار را مستقیم بنویسید:

مقادیر مستقیم روی دکمه قرار می‌گیرند
- name: Nginx logs
  type: button
  function: journal-unit
  unit: "nginx.service"
  lines: 100

مقادیر عددی YAML نیازی به نقل‌قول ندارند.

validate هر کلید را با پارامترهای تابع انتخاب‌شده می‌سنجد. غلط املایی یا نام تعریف‌نشده اعتبارسنجی را ناموفق می‌کند. مقادیر تعریف‌شده با int یا bool را نیز بررسی می‌کند. اگر دکمه مقدار اختیاری نداشته باشد، مقدار پیش‌فرض استفاده می‌شود.

دو نوع تابع

توابع یا همراه برنامه‌اند یا از فایل YAML روی سرور می‌آیند. پس از استفاده در دکمه، هر دو نوع رفتار یکسانی دارند.

توکار سفارشی
منشأ همراه برنامه فایل YAML نوشته‌شده توسط شما
آیا فایل می‌سازید؟ خیر بله، یک فایل برای هر تابع
نام‌ها رزروشده (command، script) هر نام رزرو‌نشده
همیشه موجود؟ بله فقط با تنظیم function_directory
قابل ویرایش؟ خیر بله، فایل‌های شما هستند

می‌توانید هر دو نوع را آزادانه در یک منو ترکیب کنید. بیشتر منوها فقط با دکمه‌های command شروع می‌شوند؛ وقتی یک فرمان را با تغییری کوچک تکرار می‌کنید، به تابع سفارشی بروید.

توابع توکار

دو تابع حتی بدون تنظیم function_directory همیشه بارگذاری می‌شوند. فیلدهای command، path و args آن‌ها مستقیم روی دکمه قرار می‌گیرند.

تابع کار الزامی اختیاری
command اجرای یک فرمان شِل همان‌گونه که نوشته شده command —
script اجرای فایل اسکریپت با آرگومان‌ها path args

هر دو نام رزرو شده‌اند. فایل تابع سفارشی نمی‌تواند از آن‌ها استفاده کند؛ بارگذار با خطایی مانند function name "command" is reserved متوقف می‌شود و ربات شروع نمی‌شود.

توابع سفارشی

تابع سفارشی یک فایل YAML است که فرمانی قابل استفادهٔ دوباره را توصیف می‌کند. فایل‌ها را در پوشه‌ای نگه دارید و function_directory را به آن اشاره دهید.

معرفی محل فایل‌های تابع به ربات

config.yaml
function_directory: "./functions"

ربات هنگام شروع پوشه و زیردایرکتوری‌های آن را می‌خواند و همهٔ فایل‌های .yaml و .yml را برمی‌دارد. فایل‌های دیگر نادیده گرفته می‌شوند.

بایگانی نسخه پوشهٔ functions/ با پنج نمونهٔ آماده دارد:

تابع کار مقادیر دکمه
اسکریپت اکو اجرای اسکریپت از طریق Bash path، args اختیاری
مسیر دیسک نمایش استفاده از دیسک path اختیاری
URL با curl دریافت URL url
پینگ میزبان پینگ میزبان host، count اختیاری
واحد journal نمایش گزارش‌های اخیر سرویس unit، lines اختیاری

برای نوشتن تابع خودتان از ساختار فایل شروع کنید یا راهنمای گام‌به‌گام را دنبال کنید.

بررسی موارد بارگذاری‌شده

فهرست همهٔ توابع قابل مشاهده برای ربات
./telegram-commander list-functions --config config.yaml

توابع توکار source=builtin نشان می‌دهند؛ توابع سفارشی فایل منشأ را.

نکات ایمنی

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

فرمان‌ها با دسترسی حسابی اجرا می‌شوند که ربات را اجرا کرده است. اگر root باشد (تنظیم پیش‌فرض سرویس)، دکمه‌ها می‌توانند هر کاری روی میزبان انجام دهند. فقط کاربران مجاز مورداعتماد را بیفزایید.

مقادیر پارامتر به‌شکل متن وارد فرمان می‌شوند. با آن‌ها مانند ورودی شِل رفتار کنید: مقادیر ثابت روی دکمه را ترجیح دهید و برای کارهای مخرب confirm: true بیفزایید.

خروجی بلند نگه داشته و سپس تحویل می‌شود

فرمان‌ها در timeout متوقف می‌شوند و ربات حداکثر max_output_bytes از خروجی را نگه می‌دارد. اینکه چه چیزی به گفتگو برسد — چند پیام یا یک فایل .txt — با output تعیین می‌شود. کنترل خروجی را ببینید.

مرتبط