API: ماشین‌های مجازی

ساخت، فهرست و کنترل ماشین‌ها: روشن، خاموش، راه‌اندازی مجدد، تغییر اندازه، نصب مجدد، بازیابی، حذف و کنسول.

در API به ماشین مجازی «سفارش» (order) گفته می‌شود. عملیات ناهمگام هستند: بلافاصله با 202 و وضعیت در جریان پاسخ می‌دهند و شما GET /orders/{order} را تا پایان کار می‌پرسید. قراردادهای API را ببینید.

فهرست ماشین‌های شما

GET /orders

ماشین‌های شما را برمی‌گرداند، با امکان فیلتر بر اساس وضعیت.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای query

فیلد	نوع	مقادیر
`status`	string	`pending`, `provisioning`, `running`, `failed`, `deleting`, `resizing`, `reinstalling`, `terminated`, `stopped`, `starting`, `stopping`, `rebooting`, `restoring`, `resetting_password`
`per_page`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (فهرستی از Order).

نمونه

curl -X GET https://veneshcloud.ir/api/orders \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

ساخت ماشین مجازی

POST /orders

یک ماشین روی یک پلن سفارش می‌دهد. هزینهٔ ماه اول از کیف پول کسر می‌شود. اگر موجودی حداقل لازم را پوشش ندهد، درخواست رد می‌شود و خطا نیاز را توضیح می‌دهد. ماشین در پس‌زمینه ساخته می‌شود.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`customer_plan_id`	integer	بله
`os_image`	string	بله
`region`	string	خیر
`hostname`	string	خیر
`ssh_public_key`	string	خیر
`password`	string	خیر
`login_method`	string	خیر	`generated_key`, `own_key`, `password`
`ssh_password_auth`	boolean	خیر
`disk_gb`	integer	خیر
`assign_public_ip`	boolean	خیر
`bandwidth_mbps`	integer	خیر
`open_ports`	فهرستی از integer	خیر
`user_data`	string	خیر
`description`	string	خیر
`assign_ipv6`	boolean	خیر
`data_disk_gb`	integer	خیر
`tags`	object	خیر
`join_private_network_id`	integer	خیر
`source_snapshot_id`	integer	خیر
`install_monitoring_agent`	boolean	خیر

پاسخ‌ها

200 موفق. برمی‌گرداند Order.
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/orders \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"customer_plan_id":1,"os_image":"ubuntu-22.04"}'

دریافت یک ماشین

GET /orders/{order}

یکی از ماشین‌های شما و وضعیت آن را برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند Order.

نمونه

curl -X GET https://veneshcloud.ir/api/orders/ORDER_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

دریافت دسترسی کنسول

GET /orders/{order}/console

جزئیات کنسول ماشین را برمی‌گرداند. قالب آن به ارائه‌دهنده بستگی دارد (راهنمای سریال یا پیوند VNC) و پیوندها ممکن است ظرف چند ثانیه منقضی شوند؛ درست پیش از استفاده بگیرید.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: console (OrderConsole).
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
502 خطای ارائه‌دهنده
503 موقتاً در دسترس نیست

نمونه

curl -X GET https://veneshcloud.ir/api/orders/ORDER_ID/console \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

حذف ماشین

POST /orders/{order}/actions/delete

ماشین را از بین می‌برد. وقتی در حال اجرا یا ناموفق است مجاز است. قابل بازگشت نیست.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد. برمی‌گرداند Order.
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/delete \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

تغییر اندازهٔ ماشین

POST /orders/{order}/actions/resize

ماشین را به پلن دیگری روی همان ارائه‌دهنده و منطقه می‌برد. ماشین باید در حال اجرا باشد. ماشین‌های OVHcloud را نمی‌توان کوچک کرد.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`customer_plan_id`	integer	بله

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد. برمی‌گرداند Order.
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/resize \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"customer_plan_id":1}'

گزینه‌های تغییر اندازه

GET /orders/{order}/resize-options

پلن‌هایی را که می‌توانید به آن‌ها تغییر اندازه دهید و مقادیر متمایز vCPU و RAM آن‌ها را برای ساخت دو انتخاب‌گر مستقل برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند ResizeOptions.
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X GET https://veneshcloud.ir/api/orders/ORDER_ID/resize-options \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

نصب مجدد سیستم‌عامل

POST /orders/{order}/actions/reinstall

دیسک را پاک می‌کند و تصویر انتخابی را نصب می‌کند. ماشین باید در حال اجرا باشد. پلن تغییر نمی‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`os_image`	string	بله

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد. برمی‌گرداند Order.
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/reinstall \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"os_image":"ubuntu-22.04"}'

روشن کردن ماشین

POST /orders/{order}/actions/start

ماشین متوقف را روشن می‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد. برمی‌گرداند Order.
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/start \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

خاموش کردن ماشین

POST /orders/{order}/actions/stop

ماشین در حال اجرا را خاموش می‌کند. دیسک آن حفظ می‌شود.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد. برمی‌گرداند Order.
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/stop \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

راه‌اندازی مجدد ماشین

POST /orders/{order}/actions/reboot

ماشین در حال اجرا را از نو راه‌اندازی می‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد. برمی‌گرداند Order.
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/reboot \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

بازنشانی رمز root

POST /orders/{order}/actions/reset-root-password

از راه حالت نجات ارائه‌دهنده یک رمز root جدید می‌گذارد (و در صورت تمایل یک کلید عمومی SSH اضافه می‌کند). ماشین دو بار راه‌اندازی مجدد می‌شود. فقط OVHcloud؛ ماشین باید در حال اجرا یا متوقف باشد.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`password`	string	بله
`ssh_public_key`	string	خیر

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد. برمی‌گرداند Order.
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/reset-root-password \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"password":"your-password"}'

بازیابی از اسنپ‌شات

POST /orders/{order}/actions/restore

دیسک ماشین را با یکی از اسنپ‌شات‌های تکمیل‌شدهٔ خودش جایگزین می‌کند. ماشین باید در حال اجرا یا متوقف باشد. قابل بازگشت نیست.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`snapshot_id`	integer	بله

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد. برمی‌گرداند Order.
403 مجاز نیست، این منبع متعلق به شما نیست
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/restore \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id":1}'

تمدید ماشین مجازی

POST /orders/{order}/renew

دورهٔ ۳۰ روزهٔ بعد را همین حالا از کیف پول می‌پردازد (قیمت پلن به‌علاوهٔ دیسک داده). وقتی ماشین معوق یا معلق است یا تا ۷ روز به تاریخ تمدید مانده مجاز است. ماشینی که برای عدم پرداخت خاموش شده دوباره روشن می‌شود. اگر موجودی کافی نباشد 422 با پیام خوانا برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`order`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (Order).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/renew \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

اشیاء

فهرست فیلدهای اشیایی که در بالا برگردانده می‌شوند.

CustomerPlan

فیلد	نوع	مقادیر
`id`	integer
`name`	string
`provider`	string
`plan_name`	string
`region`	string
`os_options`	فهرستی از string
`specs`	object
`usd_equivalent_price`	string
`rial_price`	integer
`fx`	object
`active`	boolean
`available`	boolean

Order

فیلد	نوع	مقادیر
`billing`	`OrderBilling`
`id`	integer
`status`	string	`pending`, `provisioning`, `running`, `failed`, `deleting`, `resizing`, `reinstalling`, `terminated`, `stopped`, `starting`, `stopping`, `rebooting`, `restoring`, `resetting_password`
`customer_plan`	`CustomerPlan`
`region`	string
`os_image`	string
`hostname`	string
`price_usd`	string
`price_rial`	integer
`external_instance_id`	string
`failure_reason`	string
`source_snapshot_id`	integer
`ipv4_address`	string
`ipv6_address`	string
`has_live_instance`	boolean
`login`	object
`created_at`	string
`provisioned_at`	string

OrderBilling

فیلد	نوع	مقادیر
`state`	string	`active`, `overdue`, `suspended`
`paid_until`	string
`next_renewal_at`	string
`suspended_at`	string
`renewal_price_usd`	string
`renewal_price_rial`	integer
`data_disk_gb`	integer
`auto_renew`	boolean
`daily_accrual_usd`	string
`daily_accrual_rial`	integer
`wallet_balance_rial`	integer
`delete_at_balance_rial`	integer
`rial_until_deletion`	integer
`wallet_balance_usd`	string
`delete_at_balance_usd`	number
`usd_until_deletion`	number

ResizeOptions

فیلد	نوع	مقادیر
`provider`	string
`region`	string
`current`	object
`cpu_options`	فهرستی از integer
`ram_options`	فهرستی از integer
`plans`	فهرستی از object