بررسی اجمالی
ویدیوی ما را در مورد این ویژگی تماشا کنید .
اصطلاح “REST API” به طور کلی به یک API اشاره دارد که از طریق پروتکل HTTP در مجموعه از پیش تعریف شده ای از URL های منبع گرا قابل دسترسی است.
از RouterOS v7.1beta4 شروع می شود، به عنوان یک رابط پوشش JSON از API کنسول پیاده سازی می شود . این امکان ایجاد، خواندن، به روز رسانی و حذف منابع و فراخوانی دستورات دلخواه کنسول را فراهم می کند.
برای شروع استفاده از REST API، سرویسwww-ssl یا www(شروع با RouterOS v7.9 ) باید پیکربندی و اجرا شود. وقتی www-sslسرویس (دسترسی HTTPS) فعال است، با اتصال به سرویس REST قابل دسترسی است https://<routers_IP>/rest. وقتی wwwسرویس (دسترسی HTTP) فعال است، با اتصال به سرویس REST قابل دسترسی است http://<routers_IP>/rest.
ما توصیه نمی کنیم دسترسی ( wwwسرویس) HTTP را فعال کنید. خطر اصلی این است که اعتبار احراز هویت را می توان با استراق سمع غیرفعال خواند. شما می توانید آن را فقط هنگام انجام آزمایشات (نه در محیط تولید) و زمانی که مطمئن هستید که کسی نمی تواند به آن گوش دهد (ترافیک شما را بازرسی کند) از آن استفاده کنید!
ساده ترین راه برای شروع استفاده از cURL، wget یا هر سرویس گیرنده HTTP دیگری حتی ابزار واکشی RouterOS است .
$ curl -k -u admin: https://10.155.101.214/rest/system/resource
[{"architecture-name":"tile","board-name":"CCR1016-12S-1S+",
"build-time":"Dec/04/2020 14:19:51","cpu":"tilegx","cpu-count":"16",
"cpu-frequency":"1200","cpu-load":"1","free-hdd-space":"83439616",
"free-memory":"1503133696","platform":"MikroTik",
"total-hdd-space":"134217728","total-memory":"2046820352",
"uptime":"2d20h12m20s","version":"7.1beta4 (development)"}]
احراز هویت
احراز هویت در REST API از طریق HTTP Basic Auth انجام می شود . نام کاربری و رمز عبور خود را مانند کاربر کنسول ارائه دهید (به طور پیش‌فرض “admin” بدون رمز عبور) .
برای استفاده از HTTPS ایمن باید گواهی ها را تنظیم کنید ، اگر از گواهی های خودامضا استفاده می شود، CA باید به ریشه مطمئن وارد شود. با این حال، برای اهداف آزمایشی، امکان اتصال ناامن وجود دارد (برای cUrl استفاده از -k flag، برای wget استفاده از –no-check-certificate ).
فرمت JSON
سرور به طور کلی از استاندارد ECMA-404 پیروی می کند، با نکات زیر:
- در پاسخ‌های JSON، همه مقادیر شی به‌صورت رشته‌ها کدگذاری می‌شوند، حتی اگر داده‌های زیربنایی یک عدد یا یک بولی باشد.
- سرور همچنین اعداد را با فرمت اکتال (با 0 شروع می شود) و هگزادسیمال (با 0x شروع می شود) می پذیرد. اگر اعداد به صورت رشته ای ارسال شوند، در نظر گرفته می شوند که فرمت اعشاری دارند.
- اعداد دارای توان پشتیبانی نمی شوند.
روش های HTTP
در زیر جدولی است که روش های HTTP پشتیبانی شده را خلاصه می کند
| نسخه HTTP | CRUD | ROS | شرح |
|---|---|---|---|
| گرفتن | خواندن | چاپ | برای گرفتن سوابق |
| پچ | به روز رسانی/تغییر | تنظیم | برای به روز رسانی یک رکورد. |
| قرار دادن | ايجاد كردن | اضافه کردن | برای ایجاد یک رکورد جدید. |
| حذف | حذف | برداشتن | برای حذف یک رکورد |
| پست | روش جهانی برای دسترسی به تمام دستورات کنسول. |
فرمت URL
گرفتن
این روش به شما امکان می دهد لیست تمام رکوردها یا یک رکورد واحد را از منوی مشخص شده رمزگذاری شده در URL دریافت کنید.
به عنوان مثال، تمام آدرس های IP (معادل ip/address/printدستور ‘ ‘ از CLI) را دریافت کنید:
$ curl -k -u admin: https://10.155.101.214/rest/ip/address
[{".id":"*1","actual-interface":"ether2","address":"10.0.0.111/24","disabled":"false",
"dynamic":"false","interface":"ether2","invalid":"false","network":"10.0.0.0"},
{".id":"*2","actual-interface":"ether3","address":"10.0.0.109/24","disabled":"true",
"dynamic":"false","interface":"ether3","invalid":"false","network":"10.0.0.0"}]
برای بازگرداندن یک رکورد واحد، شناسه را در انتهای URL اضافه کنید:
$ curl -k -u admin: https://10.155.101.214/rest/ip/address/*1
{".id":"*1","actual-interface":"ether2","address":"10.0.0.111/24","disabled":"false",
"dynamic":"false","interface":"ether2","invalid":"false","network":"10.0.0.0"}
اگر جدول حاوی پارامترهای نامگذاری شده باشد، می توان از name instread ID استفاده کرد، به عنوان مثال، دریافت ether1:
$ curl -k -u ادمین: https://10.155.101.214/rest/interface/ether1
همچنین ممکن است خروجی را فیلتر کنید، به عنوان مثال، فقط آدرس های معتبری را که متعلق به شبکه 10.155.101.0 هستند برگردانید:
$ curl -k -u admin: "https://10.155.101.214/rest/ip/address?network=10.155.101.0&dynamic=true"
[{".id":"*8","actual-interface":"sfp12","address":"10.155.101.214/24","disabled":"false",
"dynamic":"true","interface":"sfp12","invalid":"false","network":"10.155.101.0"}]
مثالی دیگر فقط آدرس‌ها را در رابط کاربری ساختگی و با نظر «test» برمی‌گرداند:
$ curl -k -u admin: 'https://10.155.101.214/rest/ip/address?comment=test&interface=dummy'
[{".id":"*3","actual-interface":"dummy","address":"192.168.99.2/24","comment":"test",
"disabled":"false","dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.99.0"}]
اگر می‌خواهید فقط ویژگی‌های خاصی را برگردانید، می‌توانید از ‘.proplist ‘ و به دنبال آن ‘=’ و لیستی از ویژگی‌های جدا شده با کاما استفاده کنید. به عنوان مثال، برای نشان دادن فقط آدرس و اگر غیرفعال است:
$ curl -k -u admin: https://10.155.101.214/rest/ip/address?.proplist=address,disabled
[{"address":"10.0.0.111/24","disabled":"false"},{"address":"10.0.0.109/24","disabled":"true"}]
پچ
این روش برای به روز رسانی یک رکورد استفاده می شود. بدنه فراخوانی PATCH را به عنوان یک شی JSON تنظیم کنید که حاوی فیلدها و مقادیر ویژگی هایی است که باید به روز شوند. به عنوان مثال، یک نظر اضافه کنید:
$ curl -k -u admin: -X PATCH https://10.155.101.214/rest/ip/address/*3 \
--data '{"comment": "test"}' -H "content-type: application/json"
{".id":"*3","actual-interface":"dummy","address":"192.168.99.2/24","comment":"test",
"disabled":"false","dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.99.0"}
در صورت بروز رسانی موفقیت آمیز، سرور شیء به روز شده را با تمام پارامترهای آن برمی گرداند.
قرار دادن
روشی برای ایجاد رکوردهای جدید در منوی کدگذاری شده در URL استفاده می شود. بدنه باید به‌عنوان یک شی JSON حاوی پارامترهای اعمال‌شده روی رکورد تازه ایجاد شده تنظیم شود.
در صورت موفقیت، سرور شی ایجاد شده را با تمام پارامترهای آن برمی گرداند.
تنها یک منبع را می توان در یک درخواست ایجاد کرد.
به عنوان مثال، یک آدرس IP به یک رابط ساختگی اضافه کنید:
$ curl -k -u admin: -X PUT https://10.155.101.214/rest/ip/address \
--data '{"address": "192.168.111.111", "interface": "dummy"}' -H "content-type: application/json"
{".id":"*A","actual-interface":"dummy","address":"192.168.111.111/32","disabled":"false",
"dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.111.111"}
حذف
این روش برای حذف رکورد با شناسه مشخص شده از منوی کدگذاری شده در URL استفاده می شود. اگر حذف با موفقیت انجام شده باشد، سرور با یک پاسخ خالی پاسخ می دهد. به عنوان مثال، دو بار برای حذف رکورد تماس بگیرید، در روتر تماس دوم، خطای 404 را برمی‌گرداند:
$ curl -k -u admin: -X DELETE https://10.155.101.214/rest/ip/address/*9
$ curl -k -u admin: -X DELETE https://10.155.101.214/rest/ip/address/*9
{"error":404,"message":"Not Found"}
پست
تمام ویژگی های API از طریق این روش در دسترس هستند POST. کلمه فرمان در هدر کدگذاری می شود و پارامترهای اختیاری با فیلدها و مقادیر مربوطه در شی JSON ارسال می شوند. مثلا برای تغییر پسورد کاربر فعال ارسال کنید
POST https://router/rest/password
{"old-password":"old","new-password":"N3w", "confirm-new-password":"N3w"}
پاسخ REST مشابه پاسخ API ساختار یافته است:
- اگر پاسخ حاوی
!reجملات ” ” (سوابق) باشد، پاسخ JSON حاوی لیستی از اشیا خواهد بود. - اگر جمله “
!done” حاوی داده باشد، پاسخ JSON حاوی یک شی با داده خواهد بود. !doneاگر هیچ رکورد یا داده ای در جمله ” ” وجود نداشته باشد ، پاسخ یک لیست خالی خواهد داشت.
دو کلید ویژه وجود دارد: .proplistو .queryکه با printکلمه فرمان استفاده می شود. در مستندات API درباره پاسخ‌های API، فهرست‌های کاربردی و پرس و جوها بیشتر بخوانید .
پروپلیست
‘. proplistکلید ‘ برای ایجاد .proplistکلمه مشخصه استفاده می شود. مقادیر می توانند یک رشته با مقادیر جدا شده با کاما باشند:
POST https://router/rest/interface/print
{".proplist":"name,type"}
یا لیستی از رشته ها:
POST https://router/rest/interface/print
{".proplist":["name","type"]}
به عنوان مثال، آدرس و ویژگی های رابط را از لیست ip/address برگردانید:
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ip/address/print\
--data '{"_proplist": ["address","interface"]}' -H "content-type: application/json"
[{"address":"192.168.99.2/24","interface":"dummy"},
{"address":"172.16.5.1/24","interface":"sfpplus1"},
{"address":"172.16.6.1/24","interface":"sfp2"},
{"address":"172.16.7.1/24","interface":"sfp3"},
{"address":"10.155.101.214/24","interface":"sfp12"},
{"address":"192.168.111.111/32","interface":"dummy"}]
پرس و جو
کلید ” .query” برای ایجاد پشته پرس و جو استفاده می شود. مقدار فهرستی از کلمات پرس و جو است. برای مثال این درخواست POST:
POST https://router/rest/interface/print
{".query":["type=ether","type=vlan","#|!"]}
معادل این جمله API است
/interface/print
?type=ether
?type=vlan
?#|!
برای مثال، بیایید « پرس و جو » و « prolist » را ترکیب کنیم تا ویژگی‌های « .id »، « آدرس » و « اینترفیس » را برای همه رکوردها و رکوردهای پویا با شبکه 192.168.111.111 برگردانیم.
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ip/address/print \
--data '{".proplist": [".id","address","interface"], ".query": ["network=192.168.111.111","dynamic=true","#|"]}'\
-H "content-type: application/json"
[{".id":"*8","address":"10.155.101.214/24","interface":"sfp12"},
{".id":"*A","address":"192.168.111.111/32","interface":"dummy"}]
تایم اوت
اگر دستور به طور نامحدود اجرا شود، زمان آن به پایان می رسد و اتصال با خطا بسته می شود. فاصله زمانی فعلی 60 ثانیه است. برای جلوگیری از خطاهای مهلت زمانی، پارامتری را اضافه کنید که زمان اجرای دستور را به اندازه کافی محدود کند.
مهلت زمانی تحت تأثیر پارامترهای ارسال شده به دستورات قرار نمی گیرد. اگر دستور به مدت یک ساعت اجرا شود، زودتر خاتمه می‌یابد و یک پیغام خطا برمی‌گرداند.
به عنوان مثال، بیایید ببینیم زمانی که دستور ping از بازه زمانی فراتر می رود، چه چیزی دریافت می کنیم و چگونه با افزودن یک پارامتر شمارش از این امر جلوگیری کنیم:
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ping \
--data '{"address":"10.155.101.1"}' \
-H "content-type: application/json"
{"detail":"Session closed","error":400,"message":"Bad Request"}
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ping \
--data '{"address":"10.155.101.1","count":"4"}' \
-H "content-type: application/json"
[{"avg-rtt":"453us","host":"10.155.101.1","max-rtt":"453us","min-rtt":"453us","packet-loss":"0","received":"1","sent":"1","seq":"0","size":"56","time":"453us","ttl":"64"},
{"avg-rtt":"417us","host":"10.155.101.1","max-rtt":"453us","min-rtt":"382us","packet-loss":"0","received":"2","sent":"2","seq":"1","size":"56","time":"382us","ttl":"64"},
{"avg-rtt":"495us","host":"10.155.101.1","max-rtt":"650us","min-rtt":"382us","packet-loss":"0","received":"3","sent":"3","seq":"2","size":"56","time":"650us","ttl":"64"},
{"avg-rtt":"461us","host":"10.155.101.1","max-rtt":"650us","min-rtt":"359us","packet-loss":"0","received":"4","sent":"4","seq":"3","size":"56","time":"359us","ttl":"64"}]
مثال دیگر یک ابزار تست پهنای باند است که می‌تواند با ارائه مدت زمان اجرا محدود شود:
$ curl -k -u admin: -X POST 'https://10.155.101.214/rest/tool/bandwidth-test' \
--data '{"address":"10.155.101.1","duration":"2s"}' \
-H "content-type: application/json"
[{".section":"0","connection-count":"20","direction":"receive","lost-packets":"0",
"random-data":"false","rx-10-second-average":"0","rx-current":"0","rx-size":"1500",
"rx-total-average":"0",
"status":"connecting"},
{".section":"1","connection-count":"20","direction":"receive","duration":"1s",
"lost-packets":"0","random-data":"false","rx-10-second-average":"0","rx-current":"0",
"rx-size":"1500","rx-total-average":"0",
"status":"running"},
{".section":"2","connection-count":"20","direction":"receive","duration":"2s",
"lost-packets":"581175","random-data":"false","rx-10-second-average":"854372352",
"rx-current":"854372352","rx-size":"1500","rx-total-average":"854372352",
"status":"running"},
{".section":"3","connection-count":"20","direction":"receive","duration":"3s",
"lost-packets":"9014","random-data":"false","rx-10-second-average":"891979008",
"rx-current":"929585664","rx-size":"1500","rx-total-average":"891979008",
"status":"done testing"}]
خطاها
موفقیت یا عدم موفقیت تماس های API در کد وضعیت HTTP نشان داده شده است. در صورت خرابی (کد وضعیت 400 یا بزرگتر)، بدنه پاسخ حاوی یک شی JSON با کد خطا، شرح خطا، و جزئیات خطای اختیاری است. به عنوان مثال، تلاش برای حذف یک رابط باز خواهد گشت
{"error":406,"message":"Not Acceptable","detail":"no such command or directory (remove)"}