وب سرویس ابر آریانت

وب سرویس ابر، منابع ابر آریانت را مدیریت می‌کند: سرورها، دیسک‌ها (Volume)، شبکه‌های خصوصی، NAT gateway، فایروال‌ها، IPهای شناور، elastic و اصلی، لود بالانسرها، ایمیج‌ها، اسنپ‌شات‌ها و پشتیبان‌ها. دستورهای arianet cloud و پرووایدر Terraform روی همین وب سرویس ساخته شده‌اند.

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

VPS یا ابر؟

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

شروع سریع

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

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

curl -s $BASE/datacenters -H "$AUTH"                  # datacenter codes, e.g. ovh
curl -s "$BASE/plans?datacenter=ovh" -H "$AUTH"       # plan ids and prices
curl -s "$BASE/images?type=system" -H "$AUTH"         # image slugs, e.g. ubuntu-24.04

curl -s -X POST $BASE/servers -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"web-1","datacenter":"ovh","plan_id":3,"image":"ubuntu-24.04","ssh_key_ids":[5],"labels":{"role":"web"}}'

پاسخ ساخت 201 است و سرور، action_id عملیات ساخت و یک root_password را برمی‌گرداند که فقط یک بار نمایش داده می‌شود (و هرگز به صورت خوانا ذخیره نمی‌شود). با count (۱ تا ۱۰) چند سرور در یک درخواست ساخته می‌شود. عملیات را تا پایان دنبال کنید (بخش عملیات ناهمگام).

احراز هویت

Authorization: Bearer <token>

دسترسی (scope)	اجازه
cloud:servers:read	همه GETها
cloud:servers:write	همه POST، PUT، PATCH و DELETEها

منابع همیشه متعلق به حساب صاحب توکن هستند. توکن نبود، نامعتبر یا باطل‌شده پاسخ 401 می‌گیرد؛ توکن بدون دسترسی لازم یا استفاده از IP خارج از فهرست مجاز توکن، پاسخ 403 می‌گیرد.

لیست قیمت عمومی

لیست قیمت به توکن نیاز ندارد و از هر origin قابل فراخوانی است (یک دقیقه کش می‌شود):

curl -s https://api.ariaservice.net/cloud/v1/public/pricing
curl -s "https://api.ariaservice.net/cloud/v1/public/pricing?datacenter=ovh"

{
  "pricing": {
    "vat_included": false,
    "hours_per_month": 730,
    "server_types": [
      {
        "id": 1, "name": "C1", "group": "shared", "cores": 1, "memory_mb": 2048, "disk_gb": 20,
        "included_traffic_gb": 20000, "minimum_usage_hours": 1,
        "prices": [
          { "location": "ovh", "price_hourly": { "net": 900, "currency": "IRR" }, "price_monthly": { "net": 657000, "currency": "IRR" } }
        ]
      }
    ],
    "resources": [
      { "sku": "volume_gb", "location": "ovh", "unit": "...", "price_hourly": { "net": 0, "currency": "IRR" }, "price_monthly": { "net": 0, "currency": "IRR" } }
    ]
  }
}

server_types همه پلن‌ها را با قیمت هر مکان و resources بقیه قیمت‌ها (primary_ipv4، floating_ipv4، floating_ipv6، elastic_ipv4، volume_gb، snapshot_gb، backup به صورت درصدی از پلن، انواع لود بالانسر و nat_gateway) را دارد. قیمت‌ها بدون مالیات بر ارزش افزوده و از همان ردیف‌هایی هستند که صورتحساب استفاده می‌کند. GET /pricing (با توکن) ردیف‌های قیمت حساب خود شما را برمی‌گرداند.

فهرست‌ها، برچسب‌ها و پروژه‌ها

هر فهرست منابع این پارامترها را می‌پذیرد:

پارامتر	توضیح
label_selector	عبارت‌های جداشده با کاما که همه باید برقرار باشند: key=value، key!=value، key (برچسب را دارد) یا !key (ندارد). مثال: env=prod,tier!=db. selector نادرست پاسخ 422 invalid_label_selector می‌گیرد.
project_id	فقط منابع این پروژه
page، per_page	صفحه‌بندی اختیاری: per_page بین ۱ و ۱۰۰، پیش‌فرض ۲۵. بدون page و per_page کل فهرست در یک صفحه برمی‌گردد.

{ "data": [ { "id": 12, "name": "web-1" } ], "meta": { "pagination": { "page": 1, "per_page": 25, "previous_page": null, "next_page": null, "last_page": 1 } } }

منابع labels (جفت‌های کلید/مقدار) دارند و به یک پروژه تعلق دارند (اگر هنگام ساخت project_id ندهید، پروژه پیش‌فرض حساب). PATCH نام، برچسب‌ها، محافظت در برابر حذف (protection_delete) و پروژه را تغییر می‌دهد؛ فقط فیلدهای ارسال‌شده تغییر می‌کنند.

عملیات ناهمگام

تغییری که زمان می‌برد پاسخ 202 (یا برای ساخت 201) با یک action_id می‌گیرد. action را تا وقتی status برابر success یا error شود بررسی کنید:

curl -s $BASE/actions/812 -H "$AUTH"
# {"data":{"id":812,"command":"create","status":"running","progress":40,"resource":{...},"error":null,"started_at":"...","finished_at":null}}

GET /actions همه actionهای حساب (از جدید به قدیم) و GET /<resource>/{id}/actions actionهای یک منبع را برمی‌گرداند. با CLI: arianet cloud actions wait <id>.

خطاها

همه خطاها یک قالب دارند:

{ "error": "Human-readable message", "code": "not_found", "reason": "..." }

بر اساس code که ثابت است تصمیم بگیرید. reason وقتی چند حالت برای یک خطا وجود دارد آن را دقیق‌تر می‌کند (مثلاً نوع منبع برای quota_exceeded). کدهای هر وضعیت HTTP در x-error-codes سند OpenAPI آمده است.

HTTP	code رایج
400	invalid_input
401	unauthorized
402	موجودی برای سفارش کافی نیست
403	forbidden، identity_needed
404	not_found
409	وضعیت منبع الان اجازه نمی‌دهد (already_attached، ip_change_fee_not_confirmed، ...)
422	درخواست درست است اما رد شد (datacenter_closed، invalid_label_selector، quota_exceeded، plan_sold_out، ...)
423	locked، server_locked، lb_locked: منبع درگیر عملیات دیگری است
429	rate_limit_exceeded
503	unavailable، datacenter_unavailable، ... (همراه Retry-After)

محدودیت نرخ

حساب و کاربر صاحب هر توکن می‌توانند ۳۶۰۰ درخواست در ساعت و ۶۰ درخواست در دقیقه ارسال کنند. هر پاسخ این هدرها را دارد:

هدر	معنی
RateLimit-Limit	تعداد درخواست مجاز در پنجره فعلی
RateLimit-Remaining	درخواست‌های باقی‌مانده در پنجره
RateLimit-Reset	ثانیه تا شروع پنجره بعدی

پس از عبور از محدودیت، پاسخ 429 با کد rate_limit_exceeded و هدر Retry-After (بر حسب ثانیه) است. همین مدت صبر کنید و دوباره تلاش کنید. پاسخ 503 هم Retry-After دارد.

curl -s -D - -o /dev/null $BASE/servers -H "$AUTH" | grep -i -e ratelimit -e retry-after

سرورها

متد و مسیر	کاربرد
GET /servers	فهرست سرورها
POST /servers	ساخت یک سرور، یا تا ۱۰ سرور با count
GET /servers/{id}	یک سرور
PATCH /servers/{id}	تغییر name، labels، protection_delete، protection_rebuild یا project_id
DELETE /servers/{id}	حذف سرور (گزینه‌ها در ادامه)
POST /servers/{id}/actions/{op}	poweron، poweroff (سخت)، shutdown (ACPI)، reboot، reset، rebuild ({"image":"..."})، change_plan ({"plan_id":4})، enable_rescue، disable_rescue، reset_password، change_ipv4 (برای تغییر پولی {"confirm_paid":true})
POST /servers/{id}/actions/attach_to_network، detach_from_network	شبکه‌های خصوصی
POST /servers/{id}/actions/enable_backup، disable_backup، change_backup_window، create_backup، restore_backup	پشتیبان‌ها
POST /servers/{id}/actions/create_image	گرفتن اسنپ‌شات
GET /servers/{id}/costs	هزینه سرور (در ادامه)
GET /servers/{id}/actions، /backups، /snapshots، /metrics، /networking، /storage، /events، /ip-changes	جزئیات و تاریخچه
POST /servers/{id}/console	لینک یک‌بارمصرف کنسول VNC با اعتبار ۶۰ ثانیه

فیلدهای بدنه ساخت: name، datacenter، plan_id، image (الزامی)؛ ssh_key_ids، ssh_keys، user_data (cloud-init، حداکثر ۳۲ کیلوبایت)، start_after_create، firewall_ids، networks، volume_ids، backups، labels، project_id، count. مقدار image نامی مثل ubuntu-24.04 یا snapshot:<id> / backup:<id> است.

حذف سرور

curl -s -X DELETE "$BASE/servers/12?keep_backups=true&delete_snapshots=true" -H "$AUTH"

پارامتر query	پیش‌فرض	توضیح
keep_backups	false	پشتیبان‌های کامل‌شده به صورت اسنپ‌شات نگه داشته شوند و تا زمان حذف بر اساس GB هزینه داشته باشند (اگر موجودی کافی نباشد 402)
delete_snapshots	false	اسنپ‌شات‌های سرور هم حذف شوند؛ اسنپ‌شات‌های محافظت‌شده باقی می‌مانند. به طور پیش‌فرض اسنپ‌شات‌ها پس از حذف سرور باقی می‌مانند و هزینه دارند.
reason	-	دلیل: price، performance، ip_filtered، no_longer_needed، migrating، support یا other
note	-	توضیح کوتاه (با reason=other الزامی، حداکثر ۵۰۰ کاراکتر)

اگر محافظت در برابر حذف فعال باشد، ابتدا آن را خاموش کنید (PATCH /servers/{id} با {"protection_delete": false}).

هزینه سرور

GET /servers/{id}/costs نرخ ساعتی و ماهانه فعلی سرور را به تفکیک هر بخش و هزینه نسخه‌های آن پس از حذف را برمی‌گرداند:

{
  "data": {
    "server_id": 12,
    "hours_per_month": 730,
    "lines": [
      { "type": "server", "id": 12, "name": "web-1", "sku": "...", "quantity": 1, "unit": "...", "hourly_price": 3300, "monthly_price": 2409000, "currency": "IRR" },
      { "type": "volume", "id": 7, "name": "data", "sku": "volume_gb", "quantity": 50, "unit": "...", "hourly_price": 0, "monthly_price": 0, "currency": "IRR" }
    ],
    "totals": [ { "currency": "IRR", "hourly_price": 3300, "monthly_price": 2409000 } ],
    "snapshots":    { "count": 1, "size_gb": 20, "hourly_price": 0, "monthly_price": 0, "currency": "IRR" },
    "kept_backups": { "count": 0, "size_gb": 0,  "hourly_price": 0, "monthly_price": 0, "currency": "IRR" }
  }
}

type هر ردیف یکی از server، primary_ipv4، floating_ip، elastic_ip، volume یا backup است؛ quantity برابر ۱، حجم دیسک بر حسب GB یا درصد پشتیبان از پلن است. totals جمع ردیف‌ها به تفکیک ارز است. snapshots پس از حذف هزینه دارند و kept_backups فقط با keep_backups=true. (اعداد بالا نمونه هستند.)

منابع دیگر

منبع	مسیرها
دیسک‌ها	/volumes، /volumes/{id}، POST /volumes/{id}/actions/{op} (attach با server_id، detach، resize با size_gb فقط افزایشی)، GET /volume-prices
شبکه‌های خصوصی	/networks، /networks/{id}، POST /networks/{id}/subnets، DELETE /networks/{id}/subnets/{subnet}، PUT /networks/{id}/routes
NAT gateway	/nat-gateways، /nat-gateways/{id}
فایروال‌ها	/firewalls، /firewalls/{id} (PUT قوانین را جایگزین می‌کند)، PUT /firewalls/{id}/servers، POST /firewalls/{id}/actions/{op} (apply_to_resources، remove_from_resources)
IPهای شناور	/floating-ips، /floating-ips/{id}، POST /floating-ips/{id}/actions/{op} (assign، unassign، change_dns_ptr)
IPهای elastic	/elastic-ips، /elastic-ips/{id}، POST /elastic-ips/{id}/actions/{op} (assign، unassign)
IPهای اصلی	/primary-ips، /primary-ips/{id}، POST /primary-ips/{id}/actions/change_dns_ptr
لود بالانسرها	/load-balancers، /load-balancers/{id}، POST /load-balancers/{id}/actions/{op} (سرویس‌ها، هدف‌ها، نوع، الگوریتم، شبکه خصوصی)، GET /load-balancers/{id}/health، GET /load-balancer-types
ایمیج‌ها	GET /images، GET /images/custom، GET /datacenters/{code}/images
اسنپ‌شات و پشتیبان	/snapshots، /snapshots/{id}، /backups، /backups/{id}، POST /backups/{id}/actions/convert (نگه‌داشتن پشتیبان به صورت اسنپ‌شات)
کاتالوگ و حساب	GET /datacenters، GET /plans، GET /pricing، GET /public/pricing، GET /limits
Actionها	GET /actions، GET /actions/{id}، GET /actions/{id}/events

همه فیلدها، بدنه‌ها و پاسخ‌ها در مرجع تعاملی و سند OpenAPI آمده‌اند.

ابزارها

• CLI: arianet cloud ...
• پرووایدر Terraform: ariaservice/arianet