وب سرویس VPS منطقه‌ای

VPSهای منطقه‌ای (مثل ریجن iran-1) وب سرویس خودشان را دارند: سفارش سرور، روشن و خاموش کردن، نصب مجدد، تغییر پلن، تغییر رمز root، کنسول مرورگر و ترافیک. دستورهای arianet vps regional روی همین وب سرویس ساخته شده‌اند.

• آدرس پایه: https://api.ariaservice.net/vps/v1
• قالب: JSON روی HTTPS
• احراز هویت: توکن شخصی API که به صورت Bearer ارسال می‌شود (احراز هویت و توکن)
• OpenAPI 3.1: https://api.ariaservice.net/vps/v1/openapi.json که در مرجع تعاملی قابل مرور است

کدام وب سرویس؟

VPSهایی که از /api/v1/servers سفارش داده می‌شوند (دستورهای arianet vps) در وب سرویس VPS توضیح داده شده‌اند. این صفحه درباره VPSهای منطقه‌ای است که در پنل هم در کنار بقیه VPSها دیده می‌شوند. هر دو وب سرویس همان توکن را می‌پذیرند.

شروع سریع

1. در پنل، در cloud.ariaservice.net/users/api-tokens توکنی با دسترسی‌های vps:servers:read و vps:servers:write بسازید.
2. وب سرویس را صدا بزنید:

export ARIANET_TOKEN="paste-your-token-here"
BASE=https://api.ariaservice.net/vps/v1
AUTH="Authorization: Bearer $ARIANET_TOKEN"

curl -s $BASE/datacenters -H "$AUTH"
curl -s "$BASE/plans?datacenter=thr-1" -H "$AUTH"
curl -s "$BASE/images?datacenter=thr-1" -H "$AUTH"
curl -s -X POST $BASE/servers -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"datacenter":"thr-1","plan_id":4,"image":"ubuntu-24.04","hostname":"web-1","billing_mode":"hourly"}'

پاسخ سفارش، سرور و یک action را برمی‌گرداند. اگر password نفرستید، رمز root ساخته می‌شود و فقط یک بار در همین پاسخ برمی‌گردد. عملیات را با GET /actions/{id} تا رسیدن state به success یا error دنبال کنید.

احراز هویت و دسترسی‌ها

دسترسی (scope)	اجازه
vps:servers:read	دیدن دیتاسنترها، پلن‌ها، ایمیج‌ها، سرورها، ترافیک و عملیات
vps:servers:write	همه تغییرات: سفارش، حذف، روشن و خاموش، نصب مجدد، تغییر پلن، تغییر رمز و کنسول

توکن بدون هیچ دسترسی، بدون محدودیت است. برای عضو تیم، سیاست‌های IAM سرورهای VPS حساب هم اعمال می‌شوند.

ریجن‌ها

ریجن با هدر Arianet-Region انتخاب می‌شود؛ بدون آن درخواست به ریجن پیش‌فرض (امروز iran-1) می‌رود. ریجن ناشناخته پاسخ 404 region_not_found می‌گیرد. درخواست‌های این ریجن از مسیر ارتباطی امن بین ریجن‌ها عبور می‌کنند، بنابراین stream رویدادها (text/event-stream) در آن پشتیبانی نمی‌شود و پاسخ 501 streaming_unsupported می‌گیرد؛ وضعیت را با GET /actions/{id} دنبال کنید.

منابع

متد و مسیر	کاربرد
GET /datacenters ، GET /plans ، GET /images	کاتالوگ ریجن
GET /servers ، POST /servers	فهرست و سفارش سرور
GET /servers/{id} ، DELETE /servers/{id}	جزئیات و حذف (هزینه تا همان لحظه تسویه می‌شود)
POST /servers/{id}/actions/{op}	start، stop (خاموش کردن عادی)، restart، kill (قطع برق)
POST /servers/{id}/reinstall	نصب مجدد از ایمیج ({"image":"..."})؛ دیسک پاک می‌شود
POST /servers/{id}/resize	انتقال به پلن دیگر ({"plan_id":5})؛ دیسک فقط بزرگ می‌شود
POST /servers/{id}/reset-password	تغییر رمز root
POST /servers/{id}/console	آدرس یک‌بارمصرف کنسول مرورگر
GET /servers/{id}/traffic	ترافیک و سهمیه دوره (from، to، granularity)
PUT /servers/{id}/traffic-settings	روشن یا خاموش کردن پرداخت ترافیک مازاد ({"overage_billing": true})؛ خاموش یعنی مازاد هرگز حساب نمی‌شود و پس از تمام شدن سهمیه دوره، شبکه تا دوره بعد قطع می‌شود. برای عضو تیم به دسترسی IAM vps:manage نیاز دارد
GET /servers/{id}/actions ، GET /actions ، GET /actions/{id}	عملیات ناهمگام

خطاها

خطاها JSON به شکل {"error": "...", "code": "..."} هستند.

HTTP	code
400	invalid_input، invalid_region
401	unauthorized
402	موجودی کافی نیست
403	forbidden، insufficient_scope
404	not_found، region_not_found
409	وضعیت سرور الان اجازه نمی‌دهد
429	rate_limit_exceeded
501	streaming_unsupported
503	vps_unavailable، region_unavailable
504	gateway_timeout: ریجن به‌موقع پاسخ نداد؛ ممکن است درخواست اجرا شده باشد، قبل از تکرار وضعیت را بررسی کنید