اخبارمدیریت سرور

راهنمای استفاده از وب سرویس RESET API سرودیتا

rest-api-web-service

مقدمه

از جمله امکانات با ارزشی که هر سرویس دهنده ای می تواند ارائه کند، وب سرویس API است که با هدف خودکار کردن فعالیت ها و ارائه آزادی عمل بیشتر به کاربران و به جهت استفاده توسط توسعه دهندگان و برنامه نویسان منتشر می شود. از جمله کاربری های وب سرویس API سرودیتا می توان به امکان خرید سرور مجازی، تغییر سیستم عامل، خاموش، روشن، ریستارت کردن و سایر موارد مدیریتی اشاره کرد. کلمه API که سرواژه سازی شده عبارت Application Programming Interface می باشد، به برنامه نویسان امکان تبادل اطلاعات با وب سرویس سرودیتا و درخواست انجام عملیات مختلف بر روی سرور های مجازی و سایر سرویس های دیگر از آن را مهیا می کند.

از جمله انواع مختلف API ها که می تواند از نوع SOAP ، REST و یا سایر موارد باشد، REST API ها به علت خوانایی بیشتر و سادگی استفاده از محبوبیت بالایی برخوردار هستند. از این رو تیم فنی سرودیتا نیز پروتکل REST را به جهت ارائه وب سرویس API به کاربران انتخاب نموده است. برنامه نویسان جهت استفاده از وب سرویس REST API سرودیتا که مبتنی بر پروتکل HTTP(s) و فرمت JSON می باشد، نیاز به یک توکن محرمانه دارند که با ثبت نام در پورتال کاربری و فعال کردن وب سرویس ها، می توانند آن را دریافت کنند. برای این کار مطابق تصویر، بر روی گزینه وب سرویس API کلیک میکنیم تا وارد صفحه مدیریت API شویم، در صورتی که وب سرویس API برای شما فعال نباشد، با صفحه ای مواجه می شوید که از شما درخواست فعال سازی آن را می کند. در این صورت مواجه شدن با این صفحه، روی دکمه تایید و ادامه کلیک کنید تا این امکان برای حساب کاربری شما فعال شود.

راهنمای استفاده از وب سرویس RESET API سرودیتا

پس از فعال شدن امکان وب سرویس API برای حساب کاربری، با صفحه زیر روبرو می شویم که از دو بخش اصلی تنظیمات API و لیست فراخوانی ها تشکیل شده است. در بخش تنظیمات API به توکن محرمانه خود دسترسی داریم که می توانیم آن را جهت استفاده توسط API کپی کنیم. همچنین امکان غیر فعال کردن وب سرویس API و همینطور تغییر توکن محرمانه در این بخش فراهم است که با کلیک بر روی دکمه مربوط به هر یک می توانیم عملیات مربوطه را انجام دهیم. لازم است توجه داشته باشید که توکن ها به صورت تصادفی تولید شده و امکان وارد کردن دستی آن فراهم نیست، همینطور با تغییر توکن، دسترسی اسکریپت ها و نرم افزارهایی که از توکن قبلی استفاده می کردند قطع شده و توکن جدید را باید برای آن ها فراهم کرد. در قسمت دوم با عنوان لیست فراخوانی ها، فراخوانی های API گذشته که قبلا توسط اسکریپت های شما انجام شده، به ترتیب تاریخ به صورت نزولی قابل مشاهده است.

راهنمای استفاده از وب سرویس RESET API سرودیتا

 

در ادامه به معرفی لیست انواع API ها، کارکرد و چگونگی استفاده از هر یک می پردازیم.

احراز هویت، محل قرار گیری توکن محرمانه و ساختار درخواست ها

از آنجایی که دسترسی به وب سرویس API از نوع REST می باشد، تمامی درخواست ها بر بستر پروتکل HTTPS انجام خواهد شد. جهت احراز هویت درخواست های خود، ضروری است تا توکن محرمانه ای که دریافت نموده اید را در سرآیند (Header) درخواست های خود با نام ApiToken قرار دهید. به مثال زیر که برای تایید توکن و دریافت اطلاعات حساب مالک توکن به کار می رود دقت کنید. در این فراخوانی که با ابزار CURL انجام شده است، توکن محرمانه خود را به جای عبارت YOURTOKEN قرار می دهیم.

curl -H "ApiToken: YOURTOKEN" -X GET https://portal.sarvdata.com/api/whoami

پاسخی که انتظار می رود تا دریافت کنیم، مشابه پاسخ زیر خواهد بود:

{
"Succeed":true,
"Data":{
"FirstName":"Ali",
"LastName":"Ahmadi",
"PhoneNumber":"09391234567",
"Email":"[email protected]"
}
}

تمامی پاسخ هایی که از وب سرویس API دریافت خواهند شد، شامل ساختاری مشابه هستند. فیلد اول با نام Succeed که مقداری از نوع boolean دارد، بیانگر این است که فراخوانی API موفق بوده است یا نه، فیلد دوم با نام Exception که در مثال بعدی قابل مشاهده است، در صورتی پدیدار می شود که خطایی رخ دهد و یا به عبارتی دیگر مقدار فیلد Succeed برابر false باشد. فیلد Exception شامل توضیحاتی درباره خطای صورت گرفته است. فیلد Data زمانی ظاهر می شود که API فراخوانی شده اطلاعاتی برای بازگرداندن داشته باشد. همینطور به پاسخ زیر که شامل فیلد Exception بوده و هنگامی رخ می دهد که توکن نامعتبری برای فراخوانی ارائه شود دقت کنید.

{"Succeed":false,"Exception":"Token is invalid"}

حال که با ساختار کلی درخواست ها و پاسخ ها آشنا شدیم، آماده ایم تا از انواع فراخوانی های مختلف استفاده کنیم. در لحظه فعلی، لیست از انواع عملیات ابتدایی که صرفا متعلق به سرور های مجازی هستند قابل استفاده هستند که در ادامه توضیح داده شده اند

 

دریافت لیست سرورهای مجازی تحت اختیار

جهت دریافت لیست سرور مجازی هایی که در اختیار حساب کاربری شماست می تواند از فراخوانی زیر استفاده کنید

curl -H "ApiToken: YOURTOKEN" -X GET https://portal.sarvdata.com/api/vm/list

پاسخ دریافتی در فیلد Data شامل لیست VPS ها و اطلاعات مربوط به هریک است. پاسخ زیر به عنوان مثال واضح کننده ساختار دریافتی است:

{
"Succeed": true,
"Data": [
{
"Id": 1000,
"DiskName": "Ubuntu 16.04.3 x86 LTS",
"ExternalIPAddress": "80.82.70.11",
"DefaultUserName": "root",
"DefaultPassword": "coMQDJNKt79863",
"ExpireMoment": "2020-10-25T17:33:35.27",
"PlanName": "پلن کاج",
"StartupMemory": 512,
"CpuCores": 1,
"DiskSizeGB": 30,
"State": "Installed"
},]
}

خاموش کردن سرور مجازی

جهت خاموش کردن سرور مجازی، کافی است تا از فراخوانی زیر استفاده کنیم:

curl -H "ApiToken: YOURTOKEN" -X GET https://portal.sarvdata.com/api/vm/stop/{VMId}

گفتنی است که عبارت {VMId} را باید با شناسه سرور مجازی مورد نظر که قبلا با استفاده از فراخوانی دریافت لیست VPS ها به دست آورده ایم جایگزین کنیم.

پاسخ این فراخوانی شامل فیلد Data نبوده و صرفا اعلام موفقیت یا شکست عملیات با فیلدهای Succeed و Exception (در صورت بروز خطا) دریافت خواهد شد.

روشن کردن سرور مجازی

جهت روشن کردن سرور مجازی، کافی است تا از فراخوانی زیر استفاده کنیم:

curl -H "ApiToken: YOURTOKEN" -X GET https://portal.sarvdata.com/api/vm/start/{VMId}

گفتنی است که عبارت {VMId} را باید با شناسه سرور مجازی مورد نظر که قبلا با استفاده از فراخوانی دریافت لیست VPS ها به دست آورده ایم جایگزین کنیم.

پاسخ این فراخوانی شامل فیلد Data نبوده و صرفا اعلام موفقیت یا شکست عملیات با فیلدهای Succeed و Exception (در صورت بروز خطا) دریافت خواهد شد.

راه اندازی مجدد سرور مجازی

جهت خاموش کردن سرور مجازی، کافی است تا از فراخوانی زیر استفاده کنیم:

curl -H "ApiToken: YOURTOKEN" -X GET https://portal.sarvdata.com/api/vm/restart/{VMId}

گفتنی است که عبارت {VMId} را باید با شناسه سرور مجازی مورد نظر که قبلا با استفاده از فراخوانی دریافت لیست VPS ها به دست آورده ایم جایگزین کنیم.

پاسخ این فراخوانی شامل فیلد Data نبوده و صرفا اعلام موفقیت یا شکست عملیات با فیلدهای Succeed و Exception (در صورت بروز خطا) دریافت خواهد شد.

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

جهت متوقف کردن سرور مجازی، کافی است تا از فراخوانی زیر استفاده کنیم:

curl -H "ApiToken: YOURTOKEN" -X GET https://portal.sarvdata.com/api/vm/pause/{VMId}

گفتنی است که عبارت {VMId} را باید با شناسه سرور مجازی مورد نظر که قبلا با استفاده از فراخوانی دریافت لیست VPS ها به دست آورده ایم جایگزین کنیم.

منظور از توقف سرور مجازی، عملیاتی است که طی آن، تمامی فعالیت های سرور مجازی فریز شده، اما با این حال منابع از جمله رم تخصیص داده شده در حالت رزرو قرار داشته و با ادامه دادن سرور مجازی، به صورت آنی سرور مجازی در دسترس قرار میگیرد.

پاسخ این فراخوانی شامل فیلد Data نبوده و صرفا اعلام موفقیت یا شکست عملیات با فیلدهای Succeed و Exception (در صورت بروز خطا) دریافت خواهد شد.

ذخیره کردن سرور مجازی

جهت ذخیره کردن سرور مجازی، کافی است تا از فراخوانی زیر استفاده کنیم:

curl -H "ApiToken: YOURTOKEN" -X GET https://portal.sarvdata.com/api/vm/save/{VMId}

گفتنی است که عبارت {VMId} را باید با شناسه سرور مجازی مورد نظر که قبلا با استفاده از فراخوانی دریافت لیست VPS ها به دست آورده ایم جایگزین کنیم.

منظور از ذخیره سرور مجازی، عملیاتی است که طی آن، تمامی فعالیت های سرور مجازی فریز شده، حالتی مانند خواب زمستانی (Hibernate) که تمامی اطلاعات حافظه رم در دیسک ذخیره شده و با ادامه دادن سرور مجازی، اطلاعات مجددا از دیسک بر روی حافظه رم بارگذاری گردیده و سپس سرور مجازی در دسترس قرار میگیرد.

پاسخ این فراخوانی شامل فیلد Data نبوده و صرفا اعلام موفقیت یا شکست عملیات با فیلدهای Succeed و Exception (در صورت بروز خطا) دریافت خواهد شد.

بررسی وضعیت سرور مجازی در مجازی ساز

جهت بررسی وضعیت سرور مجازی، کافی است تا از فراخوانی زیر استفاده کنیم:

curl -H "ApiToken: YOURTOKEN" -X GET https://portal.sarvdata.com/api/vm/check/{VMId}

گفتنی است که عبارت {VMId} را باید با شناسه سرور مجازی مورد نظر که قبلا با استفاده از فراخوانی دریافت لیست VPS ها به دست آورده ایم جایگزین کنیم.

با فراخوانی این API، وضعیت سرور مجازی معنی خاموش بودن، روشن بودن، متوقف بودن و در حالت ذخیره بودن و سایر موارد به شکل زیر پاسخ داده می شود.

{
"Succeed": true,
"Data": "Running"
}
فیلد Data می تواند شامل عبارات روبرو باشد: Stopped, Running, Paused, Unknown, Identifying, Saved, Saving

امکانات بیشتر

در لحظه فعلی، فراخوانی های API در دسترس بیشتر از موارد معرفی شده نیست. اما طی مدت زمان کوتاهی، مواردی نظیر خرید سرور مجازی جدید، تغییر سیستم عامل و تمدید آن ها به مجموعه API های موجود اضافه خواهد شد.

با سپاس فراوان از وقتی که برای خواند این نوشتار صرف کردید.

محسن اکبری شهپر

محسن اکبری هستم، برنامه نویس، طراح، مدیر شبکه و نویسنده سرودیتا! دانشجوی کارشناسی ارشد گرایش رایانش امن دانشگاه تبریز هستم و تکنولوژی بخش جدایی ناپذیر دنیای منه :)

نوشته های مشابه

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *