Skip to main content
#P1535

GET /asterisk/action/execute

Route Info

Method Endpoint Controller Middleware Purpose
GETPOST /api/v2/asterisk/websocket/testaction/execute AsteriskAmiController@testWebSocketConnectionAsteriskAmiController@executeAction authWithJwt تست اجرای دستور دلخواه AMI با نام Action و بررسی سلامت اتصال وب‌سوکت به سیستم AMI و محاسبه تاخیر (Ping/Pong Latency)پارامترهای متغیر برای مدیران سیستم

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

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

  1. اعتبارسنجی وجود پارامتر action.
  2. بررسی حق دسترسی کاربر (فقط admin/developer).
  3. ارسال پینگ (پیام ping:testدرخواست به AMI با متد Service Ami::action() به کانال داخلی asterisk_socket.
  4. دریافت پاسخ از سرویس (پیام pong) و محاسبه‌ی اختلاف زمان بین ارسال و دریافت.تبدیل به آرایه قابل خواندن.
  5. بازگرداندن نتیجه به صورت JSON همراه با فیلد latency_ms برحسب میلی‌ثانیه.
  6. ثبت در لاگ در صورت خطا در اتصال وب‌سوکت، کد ۵۰۴ برگردانده می‌شود.فعال بودن گزینه‌ی debug.

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

نام محل نوع الزامی توضیح
noneaction -Body -string -بله این مسیر نیازی نام دستور AMI مثلاً CoreShowChannels
argumentsBodyobjectخیرپارامترهای ورودی دستور به ورودی ندارد.صورت کلید–مقدار

ساختار خروجی

{
  "status": true,
  "message": "WebSocketAMI connectionAction healthy"executed successfully",
  "data": {
    "ping_sent"response": "2025-11-23T15:20:42.002+03:30"Success",
    "pong_received"message_id": "2025-11-23T15:20:42.135+03:30"1732362901.954",
    "latency_ms"details": 133{
      "Action": "CoreShowChannels",
      "Result": [
        "Channel: SIP/301-000004F2",
        "CallerID: 09132223344",
        "State: Up"
      ]
    }
  }
}

نکات امنیتی

  • این متد صرفاً مجاز تنها برای کاربران با نقش system_monitor، system_admin یا developer در دسترس است.
  • در صورت تشخیص تعداد درخواست‌های متوالی (بیش از ۵ بار در ۳۰ ثانیه)، به مدت ۶۰ ثانیه از دسترسی به این مسیر جلوگیری می‌شود (Throttle Policy).
  • هیچ اطلاعات حساس از سرویس اجرای هرگونه Action غیردر لیست سفید (AMI_WHITEACTIONS) ممنوع و موجب بازگشت کد ۴۰۳ می‌شود.
  • امکان فعال/غیرفعال سازی انتشار رویداد خروجی در پاسخ برگردانده نمی‌شود.وب‌سوکت وجود دارد.

عملکرد

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

Dependencies

  • use App\Services\WebSocketGateway;Ami;
  • use App\Helpers\Functions;Models\AmiActionLog;
  • use Illuminate\Support\Facades\Auth;
  • use Carbon\Carbon;

کدهای خطا

کد شرح منبع
401400 توکن JWT نامعتبر یا منقضیپارامتر action ارسال نشده است AuthenticationValidation
403 کاربر فاقد مجوز برای عدم دسترسی به تست وب‌سوکتدستور درخواستی Authorization
504422 عدم پاسخ از وب‌سوکت Action نامعتبر یا غیرفعال در بازه‌ی ۲ ثانیهAMI Connection TimeoutAMI Validation
500خطای داخلی AMI در حین اجراAMI Service

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

  • فعال سازی TLS برای کانال وب‌سوکت wss:// جهت رمزنگاری پینگ/پُنگ.تعریف لیست سفید از Actions مجاز در کانفیگ سیستم.
  • افزودن Signaling Token منحصربه‌فرد برای تست‌های برخط.ثبت IP کاربر در لاگ در هر درخواست.
  • محدودسازی مقدار آرگومان‌ها به ۵ کلید جهت پرهیز از استفاده غیرمجاز.

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

  • امکان نمایش نمودار زمان افزودن پارامتر dry_run برای شبیه‌سازی بدون اجرای واقعی.
  • گزارش مصور از پاسخ (Log Latency Chart) AMI در داشبورد DevOps.پنل مدیریت.
  • افزودن پارامتر اختیاری count برای اجرای تست تکرارشونده (مانند ۵ بار پیاپی).
  • ذخیره میانگین تاخیر در Redis histogram زمان پاسخ Actions برای تحلیل پایداری شبکه.پرفورمنس.

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

  • ثبت در جدول ami_websocket_logsami_action_logs به‌صورت روزانه با فیلدهای شامل operator_iduser_id، latencyaction، ip_addresspayload. و پاسخ.
  • نمایش تاریخچه پینگ‌ها در پنل پشتیبان زیر منوی Monitoring >صورت فعال بودن debug، پاسخ کامل AMI Ping.ذخیره می‌شود.

جمع‌بندی

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

Back to top