---
title: "وب سرویس ابر آریانت"
description: "وب سرویس ابر آریانت روی api.ariaservice.net/cloud/v1 - سرورها، دیسک‌ها، شبکه‌ها، فایروال‌ها، IPها، لود بالانسرها، ایمیج‌ها، قیمت‌ها و محدودیت نرخ."
url: https://docs.ariaservice.net/cloud-api
markdown: https://docs.ariaservice.net/cloud-api.md
language: fa
---

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

وب سرویس ابر، منابع **ابر آریانت** را مدیریت می‌کند: سرورها، دیسک‌ها (Volume)، شبکه‌های خصوصی، NAT gateway، فایروال‌ها، IPهای شناور، elastic و اصلی، لود بالانسرها، ایمیج‌ها، اسنپ‌شات‌ها و پشتیبان‌ها. دستورهای [`arianet cloud`](https://docs.ariaservice.net/cli#ابر-آریانت) و [پرووایدر Terraform](https://docs.ariaservice.net/terraform) روی همین وب سرویس ساخته شده‌اند.

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

> **VPS یا ابر؟**
VPSهایی که از `/api/v1/servers` (دستورهای `arianet vps`) سفارش داده می‌شوند در [وب سرویس VPS](https://docs.ariaservice.net/api-endpoints) توضیح داده شده‌اند. این صفحه فقط درباره ابر آریانت است. هر دو وب سرویس همان توکن را می‌پذیرند.

## شروع سریع

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

```bash
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` (۱ تا ۱۰) چند سرور در یک درخواست ساخته می‌شود. عملیات را تا پایان دنبال کنید (بخش [عملیات ناهمگام](#عملیات-ناهمگام)).

## احراز هویت

```text
Authorization: Bearer <token>
```

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

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

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

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

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

```json
{
  "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` کل فهرست در یک صفحه برمی‌گردد. |

```json
{ "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` شود بررسی کنید:

```bash
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>`.

## خطاها

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

```json
{ "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` دارد.

```bash
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>` است.

### حذف سرور

```bash
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` نرخ ساعتی و ماهانه فعلی سرور را به تفکیک هر بخش و هزینه نسخه‌های آن پس از حذف را برمی‌گرداند:

```json
{
  "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` |

همه فیلدها، بدنه‌ها و پاسخ‌ها در [مرجع تعاملی](https://docs.ariaservice.net/cloud-api-reference) و [سند OpenAPI](https://api.ariaservice.net/cloud/v1/openapi.json) آمده‌اند.

## ابزارها

- [CLI](https://docs.ariaservice.net/cli#ابر-آریانت): `arianet cloud ...`
- [پرووایدر Terraform](https://docs.ariaservice.net/terraform): `ariaservice/arianet`