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

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

مقدمه

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

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

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

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

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

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

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

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

تمامی پاسخ هایی که از وب سرویس 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 ها و اطلاعات مربوط به هریک است. پاسخ زیر به عنوان مثال واضح کننده ساختار دریافتی است:

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

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

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، وضعیت سرور مجازی معنی خاموش بودن، روشن بودن، متوقف بودن و در حالت ذخیره بودن و سایر موارد به شکل زیر پاسخ داده می شود.

خرید سرور مجازی

جهت خرید سرور مجازی می‌توانید از API زیر که با متد POST فراخوانی می‌شود استفاده نمایید:

[box type=”note” align=”aligncenter” class=”” width=””]curl -H “ApiToken: YOURTOKEN” -H “Content-Type: application/json” -X POST -d ‘{“LocationId”: “value”, “PlanId”: “value”, “PeriodType”: “value”, “DiskId”: “value”, “Count”: “value”, “Coupon”: “value”}’ https://portal.sarvdata.com/api/vm/create[/box]

دقت شود که مقادیر متغیر ها بایستی با مقادیر به دست آمده از صدا زدن API هایی که در ادامه ذکر می‌شود جایگزین شود.

همچنین مقدار متغیر Count تعداد دوره هایی که انتخاب نموده‌اید را مشخص می‌کند. برای مثال اگر PeriodType انتخابی شما Monthly باشد، با وارد کردن مقدار 6 برای متغیر Count، مدت ارائه خدمات سرودیتا به سرور خریداری شده‌ی شما 6 ماه خواهد بود.

تابع API مذکور به شکل زیر می‌باشد:

[HttpPost]
[Route("api/vm/create")]
public class CreateVMDTO
}
public int LocationId { get; set; }
public int PlanId { get; set; }
public PeriodType PeriodType { get; set; }
public int DiskId { get; set; }
public int Count { get; set; }
public string Coupon { get; set; }
{

دقت نمایید آبجکت هایی که پس از هر آدرس نوشته شده است بایستی در body به صورت json ارسال شوند.

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

هنگام خرید سرور مجازی می‌توانید از فراخوانی API زیر به منظور دریافت لیست لوکیشن های موجود استفاده نمایید:

[box type=”note” align=”aligncenter” class=”” width=””]curl -H “ApiToken: YOURTOKEN” -X GET https://portal.sarvdata.com/api/locations[/box]

دریافت لیست پلن های سرور مجازی

همچنین می‌توانید به هنگام انجام پروسه خرید از فراخوانی API زیر به منظور دریافت لیست پلن های سرور مجازی مربوطه استفاده نمایید:

[box type=”note” align=”aligncenter” class=”” width=””]curl -H “ApiToken: YOURTOKEN” -X GET https://portal.sarvdata.com/api/locations/{locationId}/plans/{periodType}[/box]

توجه شود که مقدار locationId رو بایستی پس اجرا نمودن API قبلی در url این API وارد نمایید.

همچنین مقدار متغیر periodType عبارت است از مقادیر Hourly, Daily, Weekly, Monthly که با توجه به نیاز خودتان میتوانید یکی از مقادیر را انتخاب نموده و برای متغیر periodType وارد نمایید.

دریافت لیست سیستم عامل ها و ایمیج های در دسترس برای سرور های مجازی

به منظور دریافت سیستم عامل ها و ایمیج های در دسترس نیز می‌توانید از فراخوانی API زیر استفاده نمایید:

[box type=”note” align=”aligncenter” class=”” width=””]curl -H “ApiToken: YOURTOKEN” -X GET https://portal.sarvdata.com/api/locations/{locationId}/plans/{planId}/disks/{periodType}[/box]

توجه شود که مقدار locationId رو بایستی پس اجرا نمودن API مربوط به دریافت لیست لوکیشن های سرور های مجازی در url این API وارد نمایید. همچنین مقدار planId پس از صدا زدن API دریافت لیست پلن های سرور مجازی به دست می‌آید که بایستی در url این API وارد گردد.

تمدید پلن سرور مجازی

جهت تمدید پلن سرور مجازی خود نیز می‌توانید API زیر را فراخوانی نمایید:

[box type=”note” align=”aligncenter” class=”” width=””]curl -H “ApiToken: YOURTOKEN” -H “Content-Type: application/json” -X POST -d ‘{“VMId”: “value”, “PeriodType”: “value”, “Count”: “value”, “Coupon”: “value”}’ https://portal.sarvdata.com/api/vm/renew[/box]

دقت شود که مقادیر متغیر ها بایستی با مقادیر به دست آمده از صدا زدن API هایی که ذکر شد جایگزین شود.

تابع API مذکور به شکل زیر می‌باشد:

[HttpPost]
[Route("api/vm/renew")]
public class RenewVMDTO
}
public int VMId { get; set; }
public PeriodType PeriodType { get; set; }
public int Count { get; set; }
public string Coupon { get; set; }
{

API مذکور با متد POST فراخوانی می شود و آبجکت هایی که پس از هر آدرس نوشته شده است بایستی در body به صورت json ارسال شوند.

تغییر سیستم عامل سرور مجازی

همچنین جهت تغییر سیستم عامل سرور از طریق فراخوانی API می توانید از روش زیر استفاده نمایید:

[box type=”note” align=”aligncenter” class=”” width=””]curl -H “ApiToken: YOURTOKEN” -H “Content-Type: application/json” -X POST -d ‘{“VMId”: “value”, “DiskId”: “value”, “Coupon”: “value”}’ https://portal.sarvdata.com/api/vm/reload[/box]

تابع API مذکور به شکل زیر می‌باشد:

[HttpPost]
[Route("api/vm/reload")]
public class ReloadVMDTO
}
public int VMId { get; set; }
public int DiskId{ get; set; }
public string Coupon { get; set; }
{


API مذکور نیز با متد POST فراخوانی می شود و آبجکت هایی که پس از هر آدرس نوشته شده است بایستی در body به صورت json ارسال شوند.

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