# POST /asterisk/action/execute

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 96%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td dir="ltr">POST</td><td dir="ltr">/api/v2/asterisk/action/execute</td><td dir="ltr">AsteriskAmiController@executeAction</td><td dir="ltr">authWithJwt</td><td dir="rtl">اجرای دستور دلخواه AMI با نام <span dir="ltr">Action</span> و پارامترهای متغیر برای مدیران سیستم</td></tr></tbody></table>

</div>### منطق عملکرد تابع

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

<div id="bkmrk-%D8%A7%D8%B9%D8%AA%D8%A8%D8%A7%D8%B1%D8%B3%D9%86%D8%AC%DB%8C%E2%80%AF%D9%88%D8%AC%D9%88%D8%AF%E2%80%AF%D9%BE%D8%A7%D8%B1%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">1. اعتبارسنجی وجود پارامتر `action`.
2. بررسی حق دسترسی کاربر (فقط admin/developer).
3. ارسال درخواست به AMI با متد Service `Ami::action()`.
4. دریافت پاسخ و تبدیل به آرایه قابل خواندن.
5. ثبت در لاگ در صورت فعال بودن گزینه‌ی debug.

</div>### پارامترهای ورودی

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%85%D8%AD%D9%84-%D9%86%D9%88%D8%B9-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%AA" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام</td><td>محل</td><td>نوع</td><td>الزامی</td><td>توضیح</td></tr><tr><td>action</td><td>Body</td><td>string</td><td>بله</td><td>نام دستور AMI مثلاً `CoreShowChannels`</td></tr><tr><td>arguments</td><td>Body</td><td>object</td><td>خیر</td><td>پارامترهای ورودی دستور به صورت کلید–مقدار</td></tr></tbody></table>

</div>### ساختار خروجی

```
{
  "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"
      ]
    }
  }
}
```

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### نکات امنیتی

<div id="bkmrk-%D9%85%D8%AC%D8%A7%D8%B2%E2%80%AF%D8%AA%D9%86%D9%87%D8%A7%E2%80%AF%D8%A8%D8%B1%D8%A7%DB%8C%E2%80%AF%DA%A9%D8%A7%D8%B1%D8%A8%D8%B1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- مجاز تنها برای کاربران با نقش `system_admin` یا `developer`.
- اجرای هرگونه Action غیردر لیست سفید (`AMI_WHITEACTIONS`) ممنوع و موجب بازگشت کد ۴۰۳ می‌شود.
- امکان فعال/غیرفعال سازی انتشار رویداد خروجی در وب‌سوکت وجود دارد.

</div>### عملکرد

<div id="bkmrk-%D9%85%DB%8C%D8%A7%D9%86%DA%AF%DB%8C%D9%86%E2%80%AF%D9%BE%D8%A7%D8%B3%D8%AE%E2%80%AFami%E2%80%AF%3A%E2%80%AF%DB%B5" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- میانگین پاسخ AMI : ۵۰–۱۳۰ میلی‌ثانیه بسته به نوع Action.
- در صورت عددموفقیّت، تابع در ۵۰۰ بازگشت داده می‌شود به همراه خطای خام AMI.

</div>### Dependencies

<div id="bkmrk-use%E2%80%AFapp%5Cservices%5Cami" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use App\\Services\\Ami;
- use App\\Models\\AmiActionLog;
- use Illuminate\\Support\\Facades\\Auth;
- use Carbon\\Carbon;

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-400-%D9%BE%D8%A7%D8%B1%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح</td><td>منبع</td></tr><tr><td>400</td><td>پارامتر `action` ارسال نشده است</td><td>Validation</td></tr><tr><td>403</td><td>عدم دسترسی به دستور درخواستی</td><td>Authorization</td></tr><tr><td>422</td><td>Action نامعتبر یا غیرفعال در AMI</td><td>AMI Validation</td></tr><tr><td>500</td><td>خطای داخلی AMI در حین اجرا</td><td>AMI Service</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%D8%AA%D8%B9%D8%B1%DB%8C%D9%81%E2%80%AF%D9%84%DB%8C%D8%B3%D8%AA%E2%80%AF%D8%B3%D9%81%DB%8C%D8%AF%E2%80%AF%D8%A7%D8%B2%E2%80%AFa" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- تعریف لیست سفید از Actions مجاز در کانفیگ سیستم.
- ثبت IP کاربر در لاگ در هر درخواست.
- محدودسازی مقدار آرگومان‌ها به ۵ کلید جهت پرهیز از استفاده غیرمجاز.

</div>### پیشنهادهای توسعه‌ای

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86%E2%80%AF%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%E2%80%AFdry_r" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن پارامتر `dry_run` برای شبیه‌سازی بدون اجرای واقعی.
- گزارش مصور از پاسخ AMI در پنل مدیریت.
- افزودن histogram زمان پاسخ Actions برای تحلیل پرفورمنس.

</div>### ممیزی و لاگ‌ها

<div id="bkmrk-%D8%AB%D8%A8%D8%AA%E2%80%AF%D8%AF%D8%B1%E2%80%AFami_action_lo" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- ثبت در `ami_action_logs` شامل `user_id`، `action`، `payload` و پاسخ.
- در صورت فعال بودن debug، پاسخ کامل AMI ذخیره می‌شود.

</div>### جمع‌بندی

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

<div id="bkmrk-asterisk-action-execute" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>