#P1535

GET /asterisk/action/execute

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/asterisk/action/execute	AsteriskAmiController@executeAction	authWithJwt	اجرای دستور دلخواه AMI با نام Action و پارامترهای متغیر برای مدیران سیستم

منطق عملکرد تابع

تابع executeAction یک رابط عمومی برای ارسال دستورات خام به سرور Asterisk AMI است. پارامتر اصلی ورودی آن action می‌باشد که نوع دستور AMI را مشخص می‌کند (برای مثال CoreShowChannels، DongleShowDevices، Reload). تمام آرگومان‌های اختیاری در فیلد arguments به صورت آرایه کلید–مقدار ارسال می‌شوند. تابع پس از ارسال دستور به AMI، پاسخ خام (متن و وضعیت دستور) را برمی‌گرداند و در صورت فعال بودن حالت debug، در لاگ ami_action_logs ثبت می‌نماید.

اعتبارسنجی وجود پارامتر action.
بررسی حق دسترسی کاربر (فقط admin/developer).
ارسال درخواست به AMI با متد Service Ami::action().
دریافت پاسخ و تبدیل به آرایه قابل خواندن.
ثبت در لاگ در صورت فعال بودن گزینه‌ی debug.

پارامترهای ورودی

نام	محل	نوع	الزامی	توضیح
action	Body	string	بله	نام دستور AMI مثلاً `CoreShowChannels`
arguments	Body	object	خیر	پارامترهای ورودی دستور به صورت کلید–مقدار

ساختار خروجی

{
  "status": true,
  "message": "AMI Action executed successfully",
  "data": {
    "response": "Success",
    "message_id": "1732362901.954",
    "details": {
      "Action": "CoreShowChannels",
      "Result": [
        "Channel: SIP/301-000004F2",
        "CallerID: 09132223344",
        "State: Up"
      ]
    }
  }
}

نکات امنیتی

مجاز تنها برای کاربران با نقش system_admin یا developer.
اجرای هرگونه Action غیردر لیست سفید (AMI_WHITEACTIONS) ممنوع و موجب بازگشت کد ۴۰۳ می‌شود.
امکان فعال/غیرفعال سازی انتشار رویداد خروجی در وب‌سوکت وجود دارد.

عملکرد

میانگین پاسخ AMI : ۵۰–۱۳۰ میلی‌ثانیه بسته به نوع Action.
در صورت عددموفقیّت، تابع در ۵۰۰ بازگشت داده می‌شود به همراه خطای خام AMI.

Dependencies

use App\Services\Ami;
use App\Models\AmiActionLog;
use Illuminate\Support\Facades\Auth;
use Carbon\Carbon;

کدهای خطا

کد	شرح	منبع
400	پارامتر `action` ارسال نشده است	Validation
403	عدم دسترسی به دستور درخواستی	Authorization
422	Action نامعتبر یا غیرفعال در AMI	AMI Validation
500	خطای داخلی AMI در حین اجرا	AMI Service

پیشنهادهای امنیتی

تعریف لیست سفید از Actions مجاز در کانفیگ سیستم.
ثبت IP کاربر در لاگ در هر درخواست.
محدودسازی مقدار آرگومان‌ها به ۵ کلید جهت پرهیز از استفاده غیرمجاز.

پیشنهادهای توسعه‌ای

افزودن پارامتر dry_run برای شبیه‌سازی بدون اجرای واقعی.
گزارش مصور از پاسخ AMI در پنل مدیریت.
افزودن histogram زمان پاسخ Actions برای تحلیل پرفورمنس.

ممیزی و لاگ‌ها

ثبت در ami_action_logs شامل user_id، action، payload و پاسخ.
در صورت فعال بودن debug، پاسخ کامل AMI ذخیره می‌شود.

جمع‌بندی

executeAction ابزاری انعطاف‌پذیر برای مدیران سیستم است تا هر فرمان AMI را با کنترل امنیت و لاگ‌گیری کامل اجرا کنند. قابلیت استفاده برای Debug، مدیریت داخلی و توسعه‌ی ابزارهای مانیتور بر پایه‌ی Asterisk را دارد.

#P1535

GET /asterisk/action/execute

Route Info

منطق عملکرد تابع

پارامترهای ورودی

ساختار خروجی

نکات امنیتی