API: فایروال، IP شناور و اطلاعات زندهٔ ماشین

گروه‌های امنیتی و قوانین آن‌ها، IPهای شناور، آدرس‌های زندهٔ ماشین و قابلیت‌های مجاز ارائه‌دهنده در هر منطقه.

همهٔ این موارد نزد ارائه‌دهندهٔ ابری اعمال می‌شوند. درخواست‌های فایروال نتیجهٔ واقعی را برمی‌گردانند؛ اگر ارائه‌دهنده نپذیرد، پاسخ 422 با error (مثلاً QUOTA_EXCEEDED) و یک message خوانا است. تغییرات IP شناور با 202 پاسخ می‌دهند؛ GET /floating-ips را تا ثابت شدن وضعیت بپرسید. پیش از هر کار با GET /orders/{order}/capabilities ببینید ارائه‌دهنده آن قابلیت را در آن منطقه مجاز می‌داند یا نه.

دریافت اطلاعات زندهٔ ماشین

GET /orders/{order}/instance

وضعیت فعلی ماشین و همهٔ آدرس‌های آن را از ارائه‌دهنده می‌پرسد: IPv4 و IPv6 عمومی خود ماشین، آدرس‌های خصوصی و IPهای شناور.

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

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

فیلد	نوع
`order`	integer

پاسخ‌ها

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

نمونه

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

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

GET /floating-ips/{floatingIp}/reverse-dns

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

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

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

فیلد	نوع
`floatingIp`	integer

پاسخ‌ها

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

نمونه

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

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

PUT /floating-ips/{floatingIp}/reverse-dns

همان قواعد ماشین، از جمله forward_record_missing.

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

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

فیلد	نوع
`floatingIp`	integer

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

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

پاسخ‌ها

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

نمونه

curl -X PUT https://veneshcloud.ir/api/floating-ips/FLOATING_IP_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}/capabilities

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

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

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

فیلد	نوع
`order`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (Capabilities).

نمونه

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

دریافت قابلیت‌های منطقه

GET /provider-capabilities

همان قابلیت‌های ماشین، برای یک ارائه‌دهنده و منطقه.

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

پارامترهای query

فیلد	نوع	مقادیر
`provider`	string
`region`	string

پاسخ‌ها

200 موفق. برمی‌گرداند: data (Capabilities).

نمونه

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

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

GET /orders/{order}/security-groups

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

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

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

فیلد	نوع
`order`	integer

پاسخ‌ها

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

نمونه

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

فهرست فایروال‌ها

GET /security-groups

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

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

پاسخ‌ها

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

نمونه

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

ساخت فایروال

POST /security-groups

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

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

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

فیلد	نوع	الزامی
`provider`	string	بله
`region`	string	بله
`name`	string	بله
`description`	string	خیر
`rules`	فهرستی از `SecurityGroupRule`	خیر

پاسخ‌ها

201 ایجاد شد. برمی‌گرداند: data (SecurityGroup).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/security-groups \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"provider":"aws","region":"REGION","name":"my-name"}'

تغییر نام فایروال

PATCH /security-groups/{securityGroup}

نام یا توضیحات فایروال را تغییر می‌دهد.

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

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

فیلد	نوع
`securityGroup`	integer

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

فیلد	نوع	الزامی	مقادیر
`name`	string	خیر
`description`	string	خیر

پاسخ‌ها

200 موفق

نمونه

curl -X PATCH https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

حذف فایروال

DELETE /security-groups/{securityGroup}

فایروال را نزد ارائه‌دهنده حذف می‌کند. ابتدا آن را از همهٔ ماشین‌ها جدا کنید.

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

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

فیلد	نوع
`securityGroup`	integer

پاسخ‌ها

204 انجام شد، محتوایی برنگردانده می‌شود
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X DELETE https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

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

POST /security-groups/{securityGroup}/rules

یک قانون اضافه می‌کند: جهت، پروتکل، پورت‌های اختیاری و یک محدودهٔ CIDR.

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

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

فیلد	نوع
`securityGroup`	integer

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

فیلد	نوع	الزامی	مقادیر
`id`	integer	خیر
`direction`	string	بله	`ingress`, `egress`
`protocol`	string	بله	`tcp`, `udp`, `icmp`, `any`
`port_min`	integer	خیر
`port_max`	integer	خیر
`remote_cidr`	string	بله
`description`	string	خیر

پاسخ‌ها

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

نمونه

curl -X POST https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID/rules \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"direction":"ingress","protocol":"tcp","remote_cidr":"string"}'

جایگزینی قوانین فایروال

PUT /security-groups/{securityGroup}/rules

همهٔ قوانین فایروال را با فهرست ارسالی جایگزین می‌کند.

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

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

فیلد	نوع
`securityGroup`	integer

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

فیلد	نوع	الزامی	مقادیر
`rules`	فهرستی از `SecurityGroupRule`	بله

پاسخ‌ها

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

نمونه

curl -X PUT https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID/rules \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"rules":[]}'

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

DELETE /security-groups/{securityGroup}/rules/{rule}

یک قانون را از فایروال حذف می‌کند.

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

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

فیلد	نوع
`securityGroup`	integer
`rule`	integer

پاسخ‌ها

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

نمونه

curl -X DELETE https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID/rules/RULE_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

اتصال فایروال

POST /security-groups/{securityGroup}/attach

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

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

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

فیلد	نوع
`securityGroup`	integer

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

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

پاسخ‌ها

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

نمونه

curl -X POST https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID/attach \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"order_id":1}'

جداسازی فایروال

DELETE /security-groups/{securityGroup}/orders/{order}

فایروال را از ماشین جدا می‌کند. اگر فایروال دیگری نماند، ماشین به گروه پیش‌فرض و باز ارائه‌دهنده برمی‌گردد.

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

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

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

پاسخ‌ها

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

نمونه

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

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

GET /orders/{order}/floating-ips

IPهای شناور متصل یا در حال اتصال به ماشین را برمی‌گرداند.

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

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

فیلد	نوع
`order`	integer

پاسخ‌ها

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

نمونه

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

دریافت قیمت IP شناور

GET /floating-ips/pricing

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

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

پاسخ‌ها

200 موفق. برمی‌گرداند: data (FloatingIpPricing).

نمونه

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

تمدید IP شناور

POST /floating-ips/{floatingIp}/renew

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

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

پاسخ‌ها

200 موفق. برمی‌گرداند: data (FloatingIp).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/floating-ips/FLOATING_IP_ID/renew \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

فهرست IPهای شناور

GET /floating-ips

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

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

پاسخ‌ها

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

نمونه

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

دریافت IP شناور

POST /floating-ips

یک آدرس جدید از ارائه‌دهنده می‌گیرد. برای رزرو و اتصال به یک ماشین order_id و در غیر این صورت provider و region بفرستید. ابتدا یک دوره از کیف پول کسر می‌شود (اگر ارائه‌دهنده ناموفق باشد بازگردانده می‌شود)؛ اگر موجودی کافی نباشد 422 برمی‌گردد. با 202 پاسخ می‌دهد.

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

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

فیلد	نوع	الزامی
`order_id`	integer	خیر
`provider`	string	خیر
`region`	string	خیر
`label`	string	خیر

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد. برمی‌گرداند: data (FloatingIp).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

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

برچسب IP شناور

PATCH /floating-ips/{floatingIp}

برچسب IP شناور را تغییر می‌دهد.

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

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

فیلد	نوع
`floatingIp`	integer

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

فیلد	نوع	الزامی	مقادیر
`label`	string	خیر

پاسخ‌ها

200 موفق

نمونه

curl -X PATCH https://veneshcloud.ir/api/floating-ips/FLOATING_IP_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

آزادسازی IP شناور

DELETE /floating-ips/{floatingIp}

آدرس را به ارائه‌دهنده برمی‌گرداند. با 202 پاسخ می‌دهد و پس از آزادسازی از فهرست حذف می‌شود.

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

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

فیلد	نوع
`floatingIp`	integer

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد
204 انجام شد، محتوایی برنگردانده می‌شود

نمونه

curl -X DELETE https://veneshcloud.ir/api/floating-ips/FLOATING_IP_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

اتصال IP شناور

POST /floating-ips/{floatingIp}/attach

IP شناور آزاد را به یکی از ماشین‌های شما در همان منطقه وصل می‌کند. با 202 پاسخ می‌دهد.

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

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

فیلد	نوع
`floatingIp`	integer

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

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

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

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

انتقال IP شناور

POST /floating-ips/{floatingIp}/move

یک IP شناور متصل را به ماشین دیگری از شما در همان منطقه منتقل می‌کند: ابتدا جدا و سپس به ماشین order_id وصل می‌شود. با 202 پاسخ می‌دهد؛ GET /floating-ips را بپرسید. صورتحساب تغییری نمی‌کند.

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

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

فیلد	نوع
`floatingIp`	integer

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

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

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد
404 پیدا نشد
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

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

جداسازی IP شناور

POST /floating-ips/{floatingIp}/detach

آدرس را از ماشین جدا می‌کند و همچنان متعلق به شماست. با 202 پاسخ می‌دهد.

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

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

فیلد	نوع
`floatingIp`	integer

پاسخ‌ها

202 پذیرفته شد، کار در پس‌زمینه ادامه دارد

نمونه

curl -X POST https://veneshcloud.ir/api/floating-ips/FLOATING_IP_ID/detach \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

اشیاء

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

Capabilities

فیلد	نوع	مقادیر
`provider`	string
`region`	string
`features`	object

FloatingIp

فیلد	نوع	مقادیر
`id`	integer
`provider`	string
`region`	string
`label`	string
`ip_address`	string
`status`	string	`allocating`, `available`, `attaching`, `attached`, `detaching`, `releasing`, `failed`
`order_id`	integer
`hostname`	string
`pending_order_id`	integer
`failure_reason`	string
`billing`	object
`created_at`	string

FloatingIpPricing

فیلد	نوع	مقادیر
`usd_equivalent_price`	string
`period_days`	integer
`rial`	integer
`fx_rate_id`	integer
`as_of`	string
`wallet_balance_usd`	string
`wallet_balance_rial`	integer
`sufficient_balance`	boolean
`auto_renew`	boolean

LiveInstance

فیلد	نوع	مقادیر
`status`	string
`provider_status`	string
`launched_at`	string
`outgoing_traffic_bytes`	integer
`plan`	string
`ipv4_address`	string
`ipv6_address`	string
`addresses`	فهرستی از object

SecurityGroup

فیلد	نوع	مقادیر
`id`	integer
`provider`	string
`region`	string
`name`	string
`description`	string
`external_id`	string
`rules`	فهرستی از `SecurityGroupRule`
`orders`	فهرستی از object
`created_at`	string

SecurityGroupRule

فیلد	نوع	مقادیر
`id`	integer
`direction`	string	`ingress`, `egress`
`protocol`	string	`tcp`, `udp`, `icmp`, `any`
`port_min`	integer
`port_max`	integer
`remote_cidr`	string
`description`	string