API پشتیبان‌گیری
مدیریت منابع، اجرای پشتیبان‌گیری، نسخه‌ها، بازگردانی، دانلود و توکن ویجت با کلید محرمانه پروژه، فقط از سرور.
احراز هویت و محدودیت‌ها
API پشتیبان‌گیری فقط با کلید محرمانه پروژه (nmk_sk_…) و فقط از سرور شما کار می‌کند. کلید را در متغیر محیطی نگه دارید و در سرآیند بفرستید.
- فقط کلید محرمانه (nmk_sk_…) در سرآیند Authorization: Bearer یا X-Namayek-Key؛ کلید در نشانی ⇒ SECRET_KEY_IN_URL.
- درخواست با سرآیند Origin (یعنی از مرورگر) رد می‌شود؛ کلید محرمانه هرگز در مرورگر.
- پروژه همیشه همان پروژه کلید است؛ منبع پروژه دیگر ۴۰۴ برمی‌گرداند.
- سقف هر کلید در دقیقه برای سه گروه جدا: خواندن، تغییر و ساخت توکن ویجت؛ مقدار را مدیر سامانه تنظیم می‌کند (پیش‌فرض ۶۰ / ۶۰ / ۶۰۰) و در سرآیند X-RateLimit-Limit برمی‌گردد؛ درخواست بررسی نسخه سقف ساعتی جدا دارد (پیش‌فرض ۱۰).
- هر تغییر در رویدادهای منبع و گزارش امنیتی با عامل «کلید API» ثبت می‌شود.
| دامنه | نوع / مقدار | توضیح |
|---|---|---|
backup:read | خواندن | منابع، نسخه‌ها، بازگردانی‌ها، کارها، عامل‌ها، رویدادها و توکن ویجت. |
backup:write | نوشتن | اجرا، ویرایش محدود، سنجاق، انتقال به سطل، بررسی نسخه و لغو کار یا بازگردانی. |
backup:restore | بازگردانی | ایجاد بازگردانی. |
backup:download | دانلود | ساخت لینک دانلود. |
مسیرها
| روش | مسیر | دامنه | توضیح |
|---|---|---|---|
GET | /v1/backup/sources | backup:read | فهرست منابع پروژه. |
GET | /v1/backup/sources/{sourceId} | backup:read | جزئیات منبع (بدون هزینه‌ها و بدون خط کلید SSH). |
POST | /v1/backup/sources/{sourceId}/run | backup:write | اجرای فوری؛ سرآیند Idempotency-Key الزامی. |
PATCH | /v1/backup/sources/{sourceId} | backup:write | نام، برچسب، زمان‌بندی (فقط بدون کاهش) و توقف/ادامه با enabled؛ نگهداری و رمزنگاری فقط از پنل. |
GET | /v1/backup/sources/{sourceId}/snapshots | backup:read | نسخه‌های منبع. |
GET | /v1/backup/snapshots | backup:read | نسخه‌های همه منبع‌های پروژه؛ فیلتر sourceId، state، pinned، from، to و cursor. |
GET | /v1/backup/snapshots/{snapshotId} | backup:read | جزئیات نسخه. |
POST | /v1/backup/snapshots/{snapshotId}/pin · /unpin | backup:write | سنجاق کردن و برداشتن. |
DELETE | /v1/backup/snapshots/{snapshotId} | backup:write | انتقال به سطل بازیافت؛ فقط اگر «عملیات حساس API» روشن باشد. |
POST | /v1/backup/snapshots/{snapshotId}/restores | backup:restore | بازگردانی؛ new_database همیشه، in_place فقط با «عملیات حساس API»؛ Idempotency-Key الزامی. |
POST | /v1/backup/snapshots/{snapshotId}/verify | backup:write | بررسی یکپارچگی (integrity، deep یا restore = بازگردانی آزمایشی)؛ Idempotency-Key الزامی. |
GET | /v1/backup/restores | backup:read | فهرست بازگردانی‌ها؛ فیلتر sourceId، state و cursor. |
GET | /v1/backup/restores/{restoreId} | backup:read | وضعیت بازگردانی. |
POST | /v1/backup/restores/{restoreId}/cancel | backup:write | لغو بازگردانی در صف یا در حال اجرا. |
GET | /v1/backup/jobs/{jobId} | backup:read | وضعیت کار. |
POST | /v1/backup/jobs/{jobId}/cancel | backup:write | لغو کار در صف؛ کار در حال اجرا در اولین فرصت متوقف می‌شود. |
POST | /v1/backup/snapshots/{snapshotId}/downloads | backup:download | لینک دانلود یک‌بارمصرف قفل‌شده به IP فراخوان (باید در فهرست IP کلید باشد). |
GET | /v1/backup/agents | backup:read | فهرست عامل‌ها. |
GET | /v1/backup/events | backup:read | رویدادهای پشتیبان‌گیری. |
POST | /v1/backup/widgets/{publicId}/embed-tokens | backup:read | توکن کوتاه‌عمر ویجت برای یک دامنه مجاز. |
اجرای پشتیبان‌گیری
اجرای فوری با Idempotency-Key یکتا؛ تکرار همان کلید همان کار را برمی‌گرداند و اجرای دوم نمی‌سازد.
curl -sS "https://api.namayek.com/v1/backup/sources" \ -H "Authorization: Bearer $NAMAYEK_SECRET_KEY"curl -sS -X POST "https://api.namayek.com/v1/backup/sources/{sourceId}/run" \ -H "Authorization: Bearer $NAMAYEK_SECRET_KEY" \ -H "Idempotency-Key: $(uuidgen)"curl -sS "https://api.namayek.com/v1/backup/jobs/{jobId}" \ -H "Authorization: Bearer $NAMAYEK_SECRET_KEY"curl -sS -X POST "https://api.namayek.com/v1/backup/jobs/{jobId}/cancel" \ -H "Authorization: Bearer $NAMAYEK_SECRET_KEY"curl -sS -X PATCH "https://api.namayek.com/v1/backup/sources/{sourceId}" \ -H "Authorization: Bearer $NAMAYEK_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled":false}'بازگردانی و دانلود
curl -sS "https://api.namayek.com/v1/backup/sources/{sourceId}/snapshots" \ -H "Authorization: Bearer $NAMAYEK_SECRET_KEY"curl -sS -X POST "https://api.namayek.com/v1/backup/snapshots/{snapshotId}/restores" \ -H "Authorization: Bearer $NAMAYEK_SECRET_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"mode":"new_database","target":"shop_restore_check"}'curl -sS -X POST "https://api.namayek.com/v1/backup/snapshots/{snapshotId}/verify" \ -H "Authorization: Bearer $NAMAYEK_SECRET_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"level":"integrity"}'curl -sS -X POST "https://api.namayek.com/v1/backup/snapshots/{snapshotId}/downloads" \ -H "Authorization: Bearer $NAMAYEK_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"mode":"ciphertext"}'| پارامتر | نوع | لزوم | پیش‌فرض | توضیح |
|---|---|---|---|---|
mode | plaintext | ciphertext | لازم | — | plaintext فقط برای نسخه‌های دارای کلید مدیریت‌شده. |
rangeStart | integer | اختیاری | — | ادامه دانلود قطع‌شده از این بایت. |
خطاها
بدنه خطا همان قالب همه API های نمایک است و کد ماشین‌خوان در code می‌آید.
| کد | HTTP | معنی و اقدام |
|---|---|---|
BACKUP_SOURCE_NOT_FOUND | 404 | منبع پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
BACKUP_SNAPSHOT_NOT_FOUND | 404 | نسخه پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
BACKUP_JOB_NOT_FOUND | 404 | کار پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
BACKUP_RESTORE_NOT_FOUND | 404 | بازگردانی پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
BACKUP_AGENT_NOT_FOUND | 404 | عامل پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
BACKUP_KEY_NOT_FOUND | 404 | کلید پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
BACKUP_WIDGET_NOT_FOUND | 404 | ویجت پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
BACKUP_TOKEN_NOT_FOUND | 404 | توکن پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
BACKUP_TARGET_NOT_FOUND | 404 | فضای ذخیره سازی پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
BACKUP_SOURCE_LIMIT | 409 | به سقف تعداد منابع این پروژه رسیده اید (N)وضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_AGENT_LIMIT | 409 | به سقف تعداد عامل های این پروژه رسیده اید (N)وضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_WIDGET_LIMIT | 409 | به سقف تعداد ویجت های این پروژه رسیده اید (N)وضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_KEY_LIMIT | 409 | به سقف تعداد کلیدهای این پروژه رسیده اید (N)وضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_ENGINE_MODE_UNSUPPORTED | 400 | این نوع پایگاه داده در حالت اتصال مستقیم پشتیبانی نمی شود؛ از عامل استفاده کنیدبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_DIRECT_DISABLED | 409 | اتصال مستقیم فعلا غیرفعال استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_INTERVAL_TOO_SHORT | 400 | فاصله اجرا باید دست کم N دقیقه باشدفاصله را دست‌کم برابر کمترین مقدار مجاز (فیلد min در پاسخ) بگذارید. |
BACKUP_CRON_INVALID | 400 | عبارت زمان بندی معتبر نیستبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_WINDOW_INVALID | 400 | بازه زمانی مجاز معتبر نیستبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_RETENTION_INVALID | 400 | سیاست نگهداری معتبر نیستبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_RETENTION_PENDING | 409 | یک تغییر سیاست در انتظار اعمال است؛ اول آن را لغو کنیدتغییر در انتظار را در پنل لغو کنید و دوباره بفرستید. |
BACKUP_ENCRYPTION_INVALID | 400 | برای این حالت رمزنگاری دست کم یک کلید مشتری لازم استبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_RECIPIENT_INVALID | 400 | کلید عمومی معتبر نیست (باید با nmkpk1 شروع شود)بدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_RECIPIENT_EXISTS | 409 | این کلید قبلا ثبت شده استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_RECIPIENT_IN_USE | 409 | این کلید در منابع دیگری استفاده می شودوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_ALREADY_RUNNING | 409 | یک اجرا برای این منبع در جریان استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_SOURCE_PAUSED | 409 | منبع متوقف استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_SOURCE_DISABLED | 409 | منبع توسط پشتیبانی غیرفعال شده استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_SOURCE_DELETING | 409 | منبع در حال حذف استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_AGENT_REQUIRED | 409 | برای این منبع هنوز عاملی وصل نشده استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_AGENT_OFFLINE | 409 | عامل این منبع از … قطع استسرویس عامل را روی سرور خود بررسی کنید (namayek-agent status). |
BACKUP_AGENT_INCAPABLE | 409 | عامل این کار را پشتیبانی نمی کندوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_AGENT_REVOKED | 409 | این عامل باطل شده استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_SLUG_TAKEN | 409 | این نام کوتاه برای منبع دیگری از این پروژه استفاده شده استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_RANGE_INVALID | 400 | نقطه ادامه دانلود معتبر نیستبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_TARGET_INVALID | 400 | تنظیمات فضای ذخیره سازی معتبر نیستبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_WIDGET_DISABLED | 403 | ویجت وضعیت پشتیبان فعلا غیرفعال استاین کار برای کلید یا پروژه مجاز نیست؛ تنظیمات «دسترسی API» یا دامنه کلید را بررسی کنید. |
BACKUP_JOB_NOT_RETRYABLE | 409 | فقط کار پشتیبان گیری ناموفق یا جامانده قابل تکرار استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_SNAPSHOT_NOT_AVAILABLE | 409 | این نسخه در دسترس نیستوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_SNAPSHOT_LOCKED | 409 | این نسخه تا … قفل تغییرناپذیر داردوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_SNAPSHOT_ON_HOLD | 409 | این نسخه توقیف قانونی داردوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_SNAPSHOT_PINNED | 409 | این نسخه سنجاق شده است؛ اول سنجاق را برداریدوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_SNAPSHOT_QUARANTINED | 409 | این نسخه به دلیل خطای سلامت داده قرنطینه است و تا بررسی پشتیبانی برای بازگردانی و دانلود در دسترس نیست؛ از نسخه دیگری استفاده کنیدوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_QUARANTINE_UNVERIFIED | 409 | بررسی دوباره این نسخه هنوز موفق نشده است؛ اول بررسی دوباره را اجرا کنید یا آزادسازی اجباری را انتخاب کنیدوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_NOT_SERVER_DECRYPTABLE | 409 | این نسخه فقط با کلید شما باز می شود؛ نسخه رمزنگاری شده را دانلود کنیدنسخه رمزنگاری‌شده را دانلود و با کلید خود باز کنید. |
BACKUP_RESTORE_TARGET_INVALID | 400 | نام مقصد معتبر نیستبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_CONFIRM_MISMATCH | 400 | عبارت تایید درست وارد نشده استبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_DIRECT_HOST_INVALID | 400 | نشانی معتبر نیستبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_DIRECT_HOST_BLOCKED | 400 | این نشانی به شبکه داخلی اشاره می کندنشانی عمومی پایگاه داده را بدهید یا از عامل نمایک استفاده کنید. |
BACKUP_DIRECT_PORT_NOT_ALLOWED | 400 | این درگاه مجاز نیستبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_DIRECT_TLS_REQUIRED | 400 | اتصال باید رمزنگاری شده (TLS یا SSH) باشدبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_SSH_HOST_KEY_UNCONFIRMED | 409 | اثر انگشت کلید سرور SSH را تایید کنیداثر انگشت را با خروجی ssh-keygen -lf روی سرور مقایسه و در پنل تایید کنید. |
BACKUP_CONNECTION_UNTESTED | 409 | اول اتصال را آزمایش کنیدوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_DOWNLOAD_DISABLED | 409 | دانلود غیرفعال استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_DOWNLOAD_LIMIT | 429 | دانلودهای همزمان زیاد استکمی بعد دوباره تلاش کنید؛ سرآیند Retry-After را رعایت کنید. |
BACKUP_API_ACTION_DISABLED | 403 | این کار از طریق API برای این پروژه غیرفعال استاین کار فقط از پنل انجام می‌شود یا باید در «سیاست‌ها › دسترسی API» روشن شود. |
BACKUP_STORAGE_UNAVAILABLE | 503 | فضای ذخیره سازی موقتا در دسترس نیستموقت است؛ با فاصله فزاینده دوباره تلاش کنید. |
BACKUP_WIDGET_ORIGIN_INVALID | 400 | دامنه شماره N معتبر نیستبدنه یا پارامتر را مطابق جدول‌های همین مستندات اصلاح کنید. |
BACKUP_TARGET_TEST_REQUIRED | 409 | برای فعال سازی، آزمایش موفق هر دو نقش لازم استوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_TARGET_IN_USE | 409 | این فضای ذخیره سازی نسخه فعال دارد و محل آن تغییر نمی کند؛ برای انتقال، فضای تازه بسازیدوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
BACKUP_DEPENDENCY_UNAVAILABLE | 503 | سرویس موقتا در دسترس نیست؛ کمی بعد دوباره تلاش کنیدموقت است؛ با فاصله فزاینده دوباره تلاش کنید. |
| کد | HTTP | معنی و اقدام |
|---|---|---|
PROJECT_NOT_FOUND | 404 | پروژه پیدا نشدشناسه را بررسی کنید؛ منبعی که مال پروژه کلید نیست هم ۴۰۴ برمی‌گرداند. |
PROJECT_DISABLED | 403 | این پروژه غیرفعال استاین کار برای کلید یا پروژه مجاز نیست؛ تنظیمات «دسترسی API» یا دامنه کلید را بررسی کنید. |
PROJECT_NOT_EMPTY | 409 | این پروژه هنوز منبع یا عامل پشتیبان گیری داردوضعیت فعلی اجازه این کار را نمی‌دهد؛ متن خطا مانع را می‌گوید. |
KYC_REQUIRED | 403 | برای ادامه، احراز هویت لازم استاین کار برای کلید یا پروژه مجاز نیست؛ تنظیمات «دسترسی API» یا دامنه کلید را بررسی کنید. |
ACCOUNT_SUSPENDED | 402 | سرویس به دلیل بدهی متوقف شده؛ با شارژ کیف پول فورا فعال می شودکیف پول را شارژ کنید؛ نسخه‌های قبلی حفظ شده‌اند. |
آخرین به‌روزرسانی: