API: فایروال، IP ثابت و اسنپ‌شات

قوانین فایروال، IP ثابت و اسنپ‌شات هر ماشین، به‌علاوهٔ فهرست‌های سراسری حساب.

اسنپ‌شات‌ها را ارائه‌دهنده می‌گیرد: بازیابی و کپی فقط برای اسنپ‌شات‌های تکمیل‌شده کار می‌کند. نقاط پایانی قدیمی قوانین فایروال و IP ثابت فقط سابقه نگه می‌دارند و منسوخ شده‌اند؛ به‌جای آن‌ها از نقاط پایانی فایروال و IP شناور استفاده کنید. اسنپ‌شات‌ها را ببینید.

فهرست قوانین فایروال

GET /orders/{order}/firewall-rules

قوانین ذخیره‌شدهٔ یک ماشین را برمی‌گرداند.

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

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

فیلد	نوع
`order`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (فهرستی از FirewallRule).
403 مجاز نیست، این منبع متعلق به شما نیست

نمونه

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

افزودن قانون فایروال

POST /orders/{order}/firewall-rules

یک قانون برای ماشین ذخیره می‌کند. port_range یک پورت مانند 22 یا یک بازه مانند 1000-2000 است.

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

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

فیلد	نوع
`order`	integer

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

فیلد	نوع	الزامی	مقادیر
`direction`	string	بله	`in`, `out`
`protocol`	string	بله	`tcp`, `udp`, `icmp`
`port_range`	string	خیر
`source_cidr`	string	بله
`description`	string	خیر

پاسخ‌ها

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

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/firewall-rules \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"direction":"in","protocol":"tcp","source_cidr":"0.0.0.0/0"}'

حذف قانون فایروال

DELETE /orders/{order}/firewall-rules/{firewallRule}

یک قانون ذخیره‌شده را حذف می‌کند.

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

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

فیلد	نوع
`order`	integer
`firewallRule`	integer

پاسخ‌ها

204 انجام شد، محتوایی برنگردانده می‌شود
403 مجاز نیست، این منبع متعلق به شما نیست
404 پیدا نشد

نمونه

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

فهرست IPهای ثابت یک ماشین

GET /orders/{order}/static-ips

آدرس‌های ثبت‌شده برای ماشین را برمی‌گرداند.

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

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

فیلد	نوع
`order`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (فهرستی از StaticIp).
403 مجاز نیست، این منبع متعلق به شما نیست

نمونه

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

رزرو IP ثابت

POST /orders/{order}/static-ips

یک آدرس را برای ماشین ثبت می‌کند. با is_reserved پس از حذف ماشین نگه داشته می‌شود و می‌توان آن را به ماشین دیگری وصل کرد.

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

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

فیلد	نوع
`order`	integer

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

فیلد	نوع	الزامی
`ip_address`	string	بله
`label`	string	خیر
`is_reserved`	boolean	خیر

پاسخ‌ها

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

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/static-ips \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"ip_address":"203.0.113.10"}'

آزادسازی IP ثابت

DELETE /orders/{order}/static-ips/{staticIp}

رکورد آدرس را حذف می‌کند.

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

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

فیلد	نوع
`order`	integer
`staticIp`	integer

پاسخ‌ها

204 انجام شد، محتوایی برنگردانده می‌شود
403 مجاز نیست، این منبع متعلق به شما نیست
404 پیدا نشد

نمونه

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

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

GET /orders/{order}/snapshots

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

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

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

فیلد	نوع
`order`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (فهرستی از Snapshot).
403 مجاز نیست، این منبع متعلق به شما نیست

نمونه

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

ساخت اسنپ‌شات

POST /orders/{order}/snapshots

از ارائه‌دهنده می‌خواهد از دیسک ماشین اسنپ‌شات بگیرد. با pending شروع می‌شود و پس از پایان کار ارائه‌دهنده با حجم واقعی completed می‌شود؛ فقط اسنپ‌شات completed را می‌توان بازیابی، کپی یا برای ساخت ماشین استفاده کرد.

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

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

فیلد	نوع
`order`	integer

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

فیلد	نوع	الزامی	مقادیر
`name`	string	بله
`size_gb`	integer	خیر

پاسخ‌ها

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

نمونه

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

حذف اسنپ‌شات

DELETE /orders/{order}/snapshots/{snapshot}

اسنپ‌شات را حذف می‌کند. به ماشین دست نمی‌زند.

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

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

فیلد	نوع
`order`	integer
`snapshot`	integer

پاسخ‌ها

204 انجام شد، محتوایی برنگردانده می‌شود
403 مجاز نیست، این منبع متعلق به شما نیست
404 پیدا نشد

نمونه

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

کپی اسنپ‌شات

POST /orders/{order}/snapshots/{snapshot}/copy

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

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

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

فیلد	نوع
`order`	integer
`snapshot`	integer

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

فیلد	نوع	الزامی	مقادیر
`name`	string	بله
`target_order_id`	integer	خیر

پاسخ‌ها

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

نمونه

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/snapshots/SNAPSHOT_ID/copy \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-name"}'

دریافت DNS معکوس ماشین

GET /orders/{order}/reverse-dns

نام PTR تنظیم‌شده برای IPv4 عمومی ماشین را برمی‌گرداند یا null.

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

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

فیلد	نوع
`order`	integer

پاسخ‌ها

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

نمونه

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

تنظیم DNS معکوس ماشین

PUT /orders/{order}/reverse-dns

نام PTR را برای IPv4 عمومی ماشین تنظیم می‌کند (با hostname: null حذف می‌شود). رکورد A خود نام باید از قبل به IP اشاره کند، وگرنه 422 با error: forward_record_missing برمی‌گردد.

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

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

فیلد	نوع
`order`	integer

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

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

پاسخ‌ها

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

نمونه

curl -X PUT https://veneshcloud.ir/api/orders/ORDER_ID/reverse-dns \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"my-vm"}'

دریافت قیمت اسنپ‌شات

GET /orders/{order}/snapshots/pricing

قیمت هر گیگابایت و بیشترین هزینهٔ اسنپ‌شات این ماشین (اندازهٔ دیسک آن) و کافی بودن کیف پول را برمی‌گرداند. مبلغ واقعی پس از تکمیل اسنپ‌شات و بر اساس اندازهٔ واقعی کسر می‌شود.

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

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

فیلد	نوع
`order`	integer

پاسخ‌ها

200 موفق

نمونه

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

تمدید اسنپ‌شات

POST /orders/{order}/snapshots/{snapshot}/renew

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

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

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

فیلد	نوع
`order`	integer
`snapshot`	integer

پاسخ‌ها

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

نمونه

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

فهرست همهٔ IPهای ثابت

GET /account/static-ips

IPهای ثابت همهٔ ماشین‌های شما را همراه نام میزبان هر ماشین برمی‌گرداند.

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

پاسخ‌ها

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

نمونه

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

اتصال IP رزروشده به ماشین دیگر

POST /account/static-ips/{staticIp}/reassign

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

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

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

فیلد	نوع
`staticIp`	integer

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

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

پاسخ‌ها

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

نمونه

curl -X POST https://veneshcloud.ir/api/account/static-ips/IP_ID/reassign \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"order_id":1}'

فهرست همهٔ قوانین فایروال

GET /account/firewall-rules

قوانین فایروال همهٔ ماشین‌های شما را برمی‌گرداند.

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

پاسخ‌ها

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

نمونه

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

فهرست همهٔ اسنپ‌شات‌ها

GET /account/snapshots

اسنپ‌شات‌های همهٔ ماشین‌های شما را برمی‌گرداند.

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

پاسخ‌ها

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

نمونه

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

اشیاء

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

FirewallRule

فیلد	نوع	مقادیر
`id`	integer
`order_id`	integer
`hostname`	string
`direction`	string	`in`, `out`
`protocol`	string	`tcp`, `udp`, `icmp`
`port_range`	string
`source_cidr`	string
`description`	string
`created_at`	string

Snapshot

فیلد	نوع	مقادیر
`id`	integer
`order_id`	integer
`hostname`	string
`name`	string
`size_gb`	integer
`status`	string	`pending`, `completed`, `failed`
`external_id`	string
`copied_from_snapshot_id`	integer
`failure_reason`	string
`billing`	`SnapshotBilling`
`created_at`	string

SnapshotBilling

فیلد	نوع	مقادیر
`state`	string	`active`, `overdue`
`price_usd`	string
`price_rial`	integer
`period_days`	integer
`paid_until`	string
`next_renewal_at`	string
`delete_at`	string

StaticIp

فیلد	نوع	مقادیر
`id`	integer
`order_id`	integer
`hostname`	string
`ip_address`	string
`label`	string
`is_reserved`	boolean
`assigned_at`	string
`created_at`	string