ماشین مجازی

پیش‌نیازها

برای این راهنما، متغیرهای محیطی شروع سریع، یک پروژه و توکن همان پروژه لازم است؛ ساخت سرور به حساب فعال و شمارهٔ تأییدشده نیاز دارد.

برای ورود با کلید، ابتدا کلید عمومی SSH را در بخش امنیت پروژه در کنسول یا با راهنمای کلید SSH ثبت کنید و شناسهٔ عددی آن را برای متغیر ABRBIT_SSH_KEY_ID بردارید؛ کلید خصوصی را هرگز به API ارسال نکنید.

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

انتخاب مشخصات

درخواست زیر موقعیت‌ها، سیستم‌عامل‌ها و بسته‌های فعال را برمی‌گرداند؛ شناسه‌ها و قیمت‌ها را از پاسخ همان زمان بردارید.

curl --fail-with-body --silent --show-error \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/catalog/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN" | jq '{locations, images, packages}'

پاسخ 200 یک شیء شامل locations، images و packages است؛ برای هر بسته، آرایه‌های location_codes و image_codes ترکیب‌های قابل انتخاب را نشان می‌دهند. فیلدهای price_per_hour و price_per_month قیمت بسته بر حسب تومان هستند؛ قیمت را در برنامه ثابت نکنید.

ساخت سرور

مقادیر زیر را با ترکیب فعال، کلید ثبت‌شده و نام یکتای سرور آزمایشی خود جایگزین کنید؛ نمونه از ابزار jq برای تولید JSON استفاده می‌کند.

export ABRBIT_VM_NAME='my-api-demo'
export ABRBIT_VM_LOCATION='LOCATION_CODE'
export ABRBIT_VM_IMAGE='IMAGE_CODE'
export ABRBIT_VM_PACKAGE_ID='PACKAGE_ID'
export ABRBIT_SSH_KEY_ID='SSH_KEY_ID'

jq -n --arg name "$ABRBIT_VM_NAME" --arg location "$ABRBIT_VM_LOCATION" \
  --arg image "$ABRBIT_VM_IMAGE" --argjson package "$ABRBIT_VM_PACKAGE_ID" \
  --argjson key "$ABRBIT_SSH_KEY_ID" \
  '{name:$name,datacenter:$location,template:$image,package_id:$package,public_key_id:$key}' | \
  curl --fail-with-body --silent --show-error \
    "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/" \
    --header "Authorization: Bearer $ABRBIT_TOKEN" \
    --header 'Content-Type: application/json' --data-binary @-

پاسخ 200 شیء سرور است و شروع ساخت را نشان می‌دهد، نه آماده بودن آن؛ مقدار عددی id را برای عملیات بعدی ذخیره کنید. مقدار public_key_data ارسالی در درخواست ساخت استفاده نمی‌شود؛ از شناسهٔ کلید ثبت‌شده استفاده کنید.

پیگیری و اتصال

نام سرور برای دریافت جزئیات و فهرست عملیات استفاده می‌شود؛ شناسهٔ عددی برای درخواست‌های تغییر وضعیت و حذف است.

curl --fail-with-body --silent --show-error \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/$ABRBIT_VM_NAME/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN" | jq '{id,name,status,ipv4,username}'

curl --fail-with-body --silent --show-error \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/$ABRBIT_VM_NAME/operations/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN" | jq '.items'

پاسخ تاریخچه، حداکثر ۱۰۰ عملیات اخیر را در items دارد؛ وضعیت‌های عملیات شامل PENDING، RUNNING، SUCCEEDED و FAILED است. وضعیت ساخت ناموفق سرور PROVISIONING_FAILED است؛ پس از آماده شدن، نشانی ipv4 و نام کاربری username را از جزئیات بردارید و با کلید خصوصی خود متصل شوید.

ssh -i /path/to/private-key USERNAME@SERVER_IPV4

برای دریافت کنسول مرورگر، شناسهٔ عددی را جایگزین کنید؛ نشانی و شناسهٔ کنسول محرمانه‌اند و نباید به دیگران فرستاده شوند.

export ABRBIT_VM_ID='VM_ID'
curl --fail-with-body --silent --show-error --request POST \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/$ABRBIT_VM_ID/console/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN"

پاسخ 200 شامل console_id و console_url است؛ نشانی را در مرورگر خود باز کنید.

روشن، خاموش و راه‌اندازی مجدد

برای هر عملیات یکی از مسیرهای poweron، poweroff یا reboot را انتخاب کنید؛ مثال زیر سرور آزمایشی را خاموش می‌کند.

curl --fail-with-body --silent --show-error --request POST \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/$ABRBIT_VM_ID/poweroff/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN"

پاسخ موفق 200 شامل {"message":"ok"} است؛ تاریخچه و جزئیات سرور را برای نتیجه بررسی کنید. روشن کردن و راه‌اندازی مجدد با جایگزینی poweroff با poweron یا reboot انجام می‌شود.

تغییر بسته

ابتدا بسته‌های فعال سازگار با همان سرور را دریافت کنید؛ این فهرست objects و meta دارد و از offset و limit پشتیبانی می‌کند.

curl --fail-with-body --silent --show-error --get \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/packages/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN" \
  --data-urlencode "vm_id=$ABRBIT_VM_ID"

برای تغییر بسته، شناسهٔ بستهٔ جدید را جایگزین کنید؛ تغییر اندازه می‌تواند هزینه را تغییر دهد. این عملیات تعداد پردازنده و حافظه را تغییر می‌دهد و نباید آن را افزایش خودکار دیسک فرض کنید.

export ABRBIT_NEW_PACKAGE_ID='PACKAGE_ID'
jq -n --argjson package "$ABRBIT_NEW_PACKAGE_ID" '{package_id:$package}' | \
  curl --fail-with-body --silent --show-error \
    "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/$ABRBIT_VM_ID/rescale/" \
    --header "Authorization: Bearer $ABRBIT_TOKEN" \
    --header 'Content-Type: application/json' --data-binary @-

پاسخ موفق 200 شامل {"message":"ok"} است؛ نتیجه را در تاریخچه و مشخصات سرور بررسی کنید.

نصب مجدد و حذف

توجه: نصب مجدد می‌تواند داده‌های سرور را از بین ببرد؛ پیش از ادامه نسخهٔ پشتیبان تهیه کنید. درخواست زیر فقط با تأیید خودتان و روی سرور آزمایشی اجرا شود.

jq -n --arg image "$ABRBIT_VM_IMAGE" '{template:$image}' | \
  curl --fail-with-body --silent --show-error \
    "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/$ABRBIT_VM_ID/reinstall/" \
    --header "Authorization: Bearer $ABRBIT_TOKEN" \
    --header 'Content-Type: application/json' --data-binary @-

پاسخ 200 شیء سرور است و پایان نصب مجدد را تضمین نمی‌کند؛ تاریخچهٔ عملیات را تا نتیجهٔ نهایی بررسی کنید.

توجه: حذف، سرور و داده‌های آن را از دسترس خارج می‌کند؛ شناسه را پیش از اجرای دستور دوباره بررسی کنید.

curl --fail-with-body --silent --show-error --request DELETE \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/$ABRBIT_VM_ID/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN"

پاسخ موفق 200 شامل {"message":"object deleted"} است. درخواست ناموفق یا قطع اتصال را بدون بررسی وضعیت و تاریخچه تکرار نکنید.

فهرست سرورها و خطاها

برای مشاهدهٔ سرورها از مسیر زیر استفاده کنید؛ پاسخ با پوشش objects و meta و پارامترهای offset و limit برمی‌گردد.

curl --fail-with-body --silent --show-error \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/vmmachine/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN"

برای خطای 400، مقادیر و سازگاری بسته و تصویر را بررسی کنید؛ برای 401 و 403، توکن و عضویت پروژه را بررسی کنید. برای 404، نام یا شناسهٔ مناسب همان مسیر را کنترل کنید؛ اطلاعات بیشتر در راهنمای خطاها و مرجع API آمده است.