عملیات‌ها (Actions)

بیش‌تر تغییرات منابع در داده‌هات، مانند ساخت سرور، اتصال والیوم یا رزرو آی‌پی الستیک، زمان‌بر هستند و به‌شکل «عملیات» (Action) انجام می‌شوند. شما یک عملیات را آغاز می‌کنید، شناسه‌ی آن را دریافت می‌کنید و تا پایان کار، وضعیت و میزان پیشرفت آن را دنبال می‌کنید.

آغاز عملیات

برای آغاز یک عملیات، درخواست POST را به مسیر /actions ارسال کنید. بدنه‌ی درخواست شامل نام فرمان (command) و ورودی‌های آن (input) است:

bash

curl -X POST "https://api.dadehat.com/api/v1/actions" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"command": "vm.stop", "input": {"vm_id": "<VM_ID>"}}'

در صورت پذیرش درخواست، پاسخ با کد 201 و شیء عملیات برگردانده می‌شود:

json

{
  "action": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "command": "vm.stop",
    "status": "running",
    "progress": 0,
    "started": "2026-09-26T10:15:00Z",
    "finished": null,
    "resources": [{"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "project"}],
    "error": null
  }
}

یادداشت

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

شیء عملیات

هر عملیات شامل فیلدهای زیر است:

id: شناسه‌ی یکتای عملیات.
command: نام فرمانی که عملیات با آن آغاز شده است، مانند vm.create.
status: وضعیت عملیات؛ یکی از running (در حال اجرا)، success (موفق) یا error (ناموفق).
progress: میزان پیشرفت از ۰ تا ۱۰۰. عملیات در حال اجرا هیچ‌گاه ۱۰۰ گزارش نمی‌کند و عملیات پایان‌یافته همیشه ۱۰۰ است.
started و finished: زمان آغاز و پایان عملیات در قالب RFC 3339. برای عملیات در حال اجرا، finished برابر null است.
resources: منابع مرتبط با عملیات، به‌شکل فهرستی از id و type.
error: در صورت ناموفق بودن عملیات، شامل code و message. مقدار code برابر failed (عملیات ناموفق بوده است) یا compensated (تغییرات نیمه‌کاره بازگردانده شده‌اند) است.

مشاهده‌ی وضعیت عملیات

برای مشاهده‌ی وضعیت یک عملیات، از درخواست زیر استفاده کنید:

bash

curl -H "Authorization: Bearer <TOKEN>" \
  "https://api.dadehat.com/api/v1/actions/<ACTION_ID>"

برای مشاهده‌ی فهرست عملیات‌ها، درخواست GET /actions را ارسال کنید. این مسیر پارامترهای زیر را می‌پذیرد:

پارامتر	توضیح
page	شماره‌ی صفحه.
per_page	تعداد نتایج هر صفحه؛ پیش‌فرض ۲۰ و حداکثر ۱۰۰.
command	فیلتر بر اساس نام فرمان، مانند volume.create.
status	فیلتر بر اساس وضعیت: running، success یا error.

پاسخ فهرست، علاوه بر actions، اطلاعات صفحه‌بندی را در meta.pagination شامل page، per_page، total_entries و last_page برمی‌گرداند.

لغو عملیات

برای لغو یک عملیات، درخواست POST /actions/<ACTION_ID>/cancel را ارسال کنید. با لغو عملیات در حال اجرا، تغییراتی که تا آن لحظه انجام شده‌اند بازگردانده می‌شوند. لغو یک عملیات ناموفق نیز منابع نیمه‌کاره‌ی آن را پاک‌سازی می‌کند.

عملیاتی که با موفقیت به پایان رسیده است قابل لغو نیست و درخواست لغو آن با کد 409 و مقدار action_not_cancellable پاسخ داده می‌شود.

پیگیری لحظه‌ای با WebSocket

به‌جای پرس‌وجوی دوره‌ای، می‌توانید به نشانی wss://api.dadehat.com/api/v1/ws متصل شوید و تغییرات عملیات را به‌شکل لحظه‌ای دریافت کنید. توکن را هنگام برقراری اتصال در سرآیند Authorization ارسال کنید.

پس از اتصال، برای هر عملیاتی که آغاز کرده‌اید، پیام اشتراک زیر را بفرستید. اتصال به‌شکل خودکار در عملیات‌های شما مشترک نمی‌شود و بدون این پیام، به‌روزرسانی‌ای دریافت نخواهید کرد:

json

{"type": "subscribe", "workflow_id": "<ACTION_ID>", "subscription_type": "workflow"}

از این پس، با هر تغییر، پیامی از نوع action_update دریافت می‌کنید که شیء عملیات در فیلد action آن قرار دارد:

json

{"type": "action_update", "timestamp": "2026-09-26T10:15:30Z", "action": {"id": "<ACTION_ID>", "command": "vm.stop", "status": "success", "progress": 100}}

در پیام پایانی عملیات ناموفق، علت خطا در action.error.message آمده است. برای جزئیات کامل‌تر، مانند فهرست منابع، شیء عملیات را با درخواست GET دریافت کنید. برای لغو اشتراک پیام unsubscribe و برای بررسی سلامت اتصال پیام ping را بفرستید.

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

جدول‌های زیر فرمان‌هایی را نشان می‌دهند که می‌توانید با POST /actions آغاز کنید. در ستون ورودی‌ها، فیلدهای الزامی آمده است. شناسه‌های لازم را می‌توانید از اندپوینت‌های خواندنی در مرجع اندپوینت‌ها به دست آورید.

سرور

فرمان	ورودی‌های الزامی	توضیح
vm.create	نمونه‌ی کامل در ادامه	ساخت سرور
vm.start	vm_id	روشن کردن سرور
vm.stop	vm_id	خاموش کردن سرور
vm.resize	vm_id و دست‌کم یکی از cpu_cores یا memory_mb	تغییر منابع سرور؛ سرور باید خاموش باشد.
vm.migrate	vm_id	مهاجرت سرور
vm.delete	vm_id	حذف سرور
vm.sg.attach	vm_id، sg_id	اتصال گروه امنیتی به سرور
vm.sg.detach	vm_id	جدا کردن گروه امنیتی از سرور

کانتینر

فرمان	ورودی‌های الزامی	توضیح
container.deploy	ورودی‌ها مطابق مرجع اندپوینت‌ها؛ از جمله container_plan_id	ساخت کانتینر
container.update	container_id	تغییر پیکربندی یا ایمیج کانتینر
container.scale	container_id	تغییر تعداد نمونه‌ها
container.restart	container_id	راه‌اندازی مجدد کانتینر
container.delete	container_id	حذف کانتینر
container.sg.attach	container_id، sg_id	اتصال گروه امنیتی به کانتینر
container.sg.detach	container_id	جدا کردن گروه امنیتی از کانتینر

والیوم و اسنپ‌شات

فرمان	ورودی‌های الزامی	توضیح
volume.create	project_id، tenant_id، region، size_gi و volume_mode (اختیاری: block یا filesystem)	ساخت والیوم
volume.attach	volume_id، target_kind (vm یا container)، target_id و برای کانتینر mount_path	اتصال والیوم
volume.detach	volume_id	قطع اتصال والیوم
volume.delete	volume_id	حذف والیوم
volume.snapshot.create	volume_id، project_id	گرفتن اسنپ‌شات
volume.snapshot.delete	snapshot_id، project_id	حذف اسنپ‌شات
volume.snapshot.restore	snapshot_id، project_id	بازیابی اسنپ‌شات
volume.snapshot.restore.vm	snapshot_id، project_id	بازیابی اسنپ‌شات روی دیسک سرور
volume.snapshot.restore.container	snapshot_id، project_id	بازیابی اسنپ‌شات روی والیوم کانتینر
volume.snapshot.restore.unattached	snapshot_id، project_id	بازیابی اسنپ‌شات به‌عنوان والیوم جدید

شبکه

فرمان	ورودی‌های الزامی	توضیح
network.subnet.create	vpc_id، cidr	ساخت ساب‌نت
network.subnet.update	subnet_id	ویرایش ساب‌نت، مانند سرورهای DNS
network.subnet.delete	subnet_id	حذف ساب‌نت
network.vpc.delete	vpc_id	حذف ابر خصوصی
internet-gateway.create	vpc_id	فعال‌سازی اینترنت گیت‌وی
internet-gateway.delete	ورودی‌ها مطابق مرجع اندپوینت‌ها	غیرفعال‌سازی اینترنت گیت‌وی
public-ip.reserve	project_id	رزرو آی‌پی الستیک
public-ip.attach	elastic_ip_id، workload_uuid، workload_kind (vm، container یا loadbalancer)	اتصال آی‌پی الستیک
public-ip.detach	elastic_ip_id	قطع اتصال آی‌پی الستیک
public-ip.release	elastic_ip_id	آزادسازی آی‌پی الستیک
loadbalancer.create	ورودی‌ها مطابق مرجع اندپوینت‌ها	ساخت توزیع‌کننده‌ی بار
loadbalancer.backends.set	load_balancer_id، project_id	تعیین مقصدهای توزیع‌کننده‌ی بار
loadbalancer.delete	load_balancer_id، project_id	حذف توزیع‌کننده‌ی بار

بیلد و بازارچه

فرمان	ورودی‌های الزامی	توضیح
build.trigger	rule_id، project_id	اجرای دستی بیلد بر اساس یک قانون بیلد
app.deploy	ورودی‌ها مطابق مرجع اندپوینت‌ها	نصب اپلیکیشن از بازارچه
app.delete	app_id	حذف اپلیکیشن

نمونه‌ی ساخت سرور

برای ساخت سرور، مقادیر لازم را از اندپوینت‌های زیر به دست آورید:

tenant_id از پاسخ GET /projects/<PROJECT_ID>
vpc_id و subnet_id از GET /vpcs و GET /vpcs/<VPC_ID>/subnets؛ مقدار subnet_cr_name در پاسخ GET /subnets/<SUBNET_ID> آمده است.
base_image_uuid از GET /vms/base-images
vm_type_id از GET /vms/types
شناسه‌ی کلیدهای SSH از GET /ssh-keys و شناسه‌ی گروه امنیتی از GET /security-groups

سپس عملیات را به‌شکل زیر آغاز کنید:

bash

curl -X POST "https://api.dadehat.com/api/v1/actions" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "vm.create",
    "input": {
      "project_id": "<PROJECT_ID>",
      "tenant_id": "<TENANT_ID>",
      "vpc_id": "<VPC_ID>",
      "subnet_id": "<SUBNET_ID>",
      "subnet_cr_name": "<SUBNET_CR_NAME>",
      "name": "web-01",
      "base_image_uuid": "<BASE_IMAGE_ID>",
      "vm_type_id": "<VM_TYPE_ID>",
      "ssh_key_ids": ["<SSH_KEY_ID>"],
      "security_group_id": "<SECURITY_GROUP_ID>"
    }
  }'

فیلدهای ssh_key_ids و security_group_id اختیاری هستند. سرور بدون گروه امنیتی، بدون فایروال ساخته می‌شود. منابع پردازشی، حافظه و دیسک سرور از پلن انتخاب‌شده (vm_type_id) تعیین می‌شوند. برای آشنایی با جزئیات ساخت سرور، راهنمای ساخت سرور را ببینید.

خطاهای رایج

وضعیت	کد	علت
400	invalid_input	نام فرمان ناشناخته است یا یکی از ورودی‌های الزامی ارسال نشده است. متن خطا نام فیلد را مشخص می‌کند.
403	insufficient-scope	توکن دسترسی write لازم برای این منبع را ندارد.
403	kyc_not_verified	احراز هویت حساب کامل نیست.
404	not_found	عملیات یا منبع وجود ندارد یا متعلق به پروژه‌ی دیگری است.
409	action_not_cancellable	عملیات در وضعیتی است که قابل لغو نیست.