API عمومی و توکن‌ها
خواندن وضعیت مانیتورها، ساخت مانیتور و متریک‌های Prometheus با توکن API.
ساخت توکن
«توکن‌های API» (فقط مالک و ادمین) ← نام و دسترسی را بدهید: «فقط‌خواندنی» یا «خواندن و نوشتن». توکن با utc_live_ شروع می‌شود و فقط یک‌بار نمایش داده می‌شود (فقط hash ذخیره می‌شود). هر درخواست باید این هدر را داشته باشد:
Authorization: Bearer utc_live_xxxxxxxxxxxxxxxxxxxxxxxx
توکن دسترسی به همان حسابی را دارد که در آن ساخته شده. با «لغو» در جدول، توکن همان لحظه از کار می‌افتد. از ستون «آخرین استفاده» می‌فهمید کدام توکن هنوز استفاده می‌شود.
مسیرها
| متد و مسیر | دسترسی | کاربرد |
|---|---|---|
GET /api/v1/monitors | خواندن | فهرست مانیتورها با وضعیت فعلی |
GET /api/v1/monitors/:id | خواندن | جزئیات یک مانیتور |
GET /api/v1/monitors/:id/uptime | خواندن | دسترس‌پذیری ۲۴ ساعت اخیر (بازه‌های ساعتی) |
POST /api/v1/monitors | نوشتن | ساخت مانیتور؛ همان قواعد و محدودیت‌های پلن فرم وب |
GET /api/v1/metrics | خواندن | متریک‌ها به فرمت Prometheus |
مستندات تعاملی (OpenAPI/Swagger) روی https://statly.ir/api-backend/api-docs است؛ لینکش را در صفحه‌ی «توکن‌های API» هم می‌بینید.
نمونه
curl https://statly.ir/api-backend/api/v1/monitors \ -H "Authorization: Bearer $STATLY_API_TOKEN"
- نوع‌های قابل ساخت (
typeCode): http، keyword، tcp، ping، ssl، dns، api، heartbeat، webhook. intervalSecبین ۱۵ تا ۸۶۴۰۰ ثانیه، ولی نه کمتر از حداقل پلن شما. فیلدهای اختیاری:timeoutSec(۱ تا ۱۲۰، پیش‌فرض ۱۰)،retryCount(۰ تا ۱۰، پیش‌فرض ۳)،retryIntervalSec(۱ تا ۶۰، پیش‌فرض ۵) وconfigمخصوص هر نوع.
Prometheus و Grafana
با یک توکن «فقط‌خواندنی» می‌توانید /api/v1/metrics را در Prometheus اسکرپ کنید:
scrape_configs:
- job_name: statly
scheme: https
metrics_path: /api-backend/api/v1/metrics
authorization:
credentials: utc_live_xxxxxxxxxxxxxxxxxxxxxxxx
static_configs:
- targets: ['statly.ir']سری‌های موجود (با برچسب‌های monitor_id، monitor_name، type):
| متریک | معنی |
|---|---|
uptime_checker_monitor_up | ۱ اگر مانیتور فعال است، وگرنه ۰ |
uptime_checker_monitor_status | یک سری برای هر وضعیت (up, down, partial_outage, flapping, unknown) |
uptime_checker_monitor_consecutive_failure | شکست‌های پیاپی |
uptime_checker_monitor_incident_open | ۱ اگر قطعی باز است |
uptime_checker_monitor_response_time_seconds | زمان پاسخ آخرین بررسی موفق |
uptime_checker_monitor_ssl_expiry_seconds | ثانیه‌ی مانده تا انقضای گواهی (منفی یعنی منقضی) |
uptime_checker_monitor_uptime_ratio_24h | نسبت دسترس‌پذیری ۲۴ ساعت (۰ تا ۱) |
محدودیت و خطاها
| کد | پیام یا معنی |
|---|---|
401 | توکن لازم است یا نامعتبر/لغوشده است |
403 | این عملیات به توکنی با دسترسی «خواندن و نوشتن» نیاز دارد، یا سقف مانیتور پلن پر است |
400 | ورودی نامعتبر (جزئیات خطا در بدنه‌ی پاسخ) |
429 | تعداد درخواست‌ها بیش از حد مجاز است؛ چند دقیقه صبر کنید |
درخواست‌ها به‌ازای هر حساب (نه هر IP) محدود می‌شوند. اگر هر چند ثانیه یک‌بار متریک می‌گیرید و ۴۲۹ دیدید، فاصله‌ی اسکرپ را بیشتر کنید (مثلاً ۶۰ ثانیه) و تعداد درخواست‌ها را کم کنید.
سایر درخواست‌های ورودی
این‌ها با توکن API کار نمی‌کنند و هرکدام کلید خودشان را دارند: