Проверки

В этой статье мы опишем как можно управлять Проверками (checks) через API. Проверки используются для мониторинга доступности и производительности ваших компонентов, таких как веб-сайты, API, TCP-сервисы и SSL-сертификаты.

Объект Проверки

GET /v1/checks
GET /v1/checks/{check_id}

Метод для получения всех проверок или одной проверки по ID.

Пример объекта:

{
    "active": true,
    "created_at": "2025-05-26T11:20:08.078931",
    "host": "pingera.ru",
    "id": "9juyny85ibe7",
    "interval": 60,
    "last_checked_at": null,
    "name": "my first tcp check",
    "parameters": {},
    "port": 443,
    "status": "pending",
    "timeout": 10,
    "type": "tcp",
    "updated_at": "2025-05-26T11:20:08.078935",
    "url": null,
    "secrets": []
}

Поля

Поле	Тип объекта	Описание
active	boolean	Активна ли проверка. true если активна, false если нет.
created_at	string (ISO 8601)	Дата и время создания проверки.
host	string or null	Хост для проверки (например, для tcp, ssl типов). Может быть null если используется url.
id	string	ID проверки.
interval	number	Интервал между проверками в секундах. Минимальное значение: 30.
last_checked_at	string (ISO 8601) or null	Дата и время последней выполненной проверки. null если проверка еще не выполнялась.
name	string	Название проверки.
parameters	object	Дополнительные параметры, зависящие от типа проверки. См. раздел "Параметры Проверки".
port	number or null	Порт для проверки (например, для tcp, ssl типов).
status	string	Текущий статус проверки (например, pending, up, down).
timeout	number	Таймаут ожидания ответа в секундах. Максимальное значение: 30.
type	string	Тип проверки. Возможные значения: web, tcp, ssl, api, portscan, synthetic, multistep, icmp, dns.
updated_at	string (ISO 8601)	Дата и время последнего обновления проверки.
url	string or null	URL для проверки (например, для web, api, synthetic типов). Может быть null если используется host.
secrets	array	Список объектов секретов, которые связаны с этой проверко. Больше про секреты

Постраничный вывод (Пагинация)

При запросе списка всех проверок с использованием метода GET /v1/checks, результаты возвращаются постранично (с использованием пагинации). Объект ответа будет содержать информацию о пагинации в соответствующем блоке.

Пример объекта пагинации:

{
    "pagination": {
        "page": 1,
        "page_size": 20,
        "total_items": 19,
        "total_pages": 1
    }
}

Вы можете управлять выводом данных, используя следующие параметры запроса:

• page_size: Определяет количество элементов, возвращаемых на одной странице. Максимальное значение — 100. По умолчанию — 20.
• page: Задает номер запрашиваемой страницы. По умолчанию — 1. Например:

Чтобы получить 50 проверок на странице:

GET /v1/checks?page_size=50

Чтобы перейти к третьей странице результатов (с размером страницы по умолчанию или ранее установленным page_size):

GET /v1/checks?page=3

Создать Проверку

POST /v1/checks

Создать новую проверку.

Обязательные поля

Поле	Тип объекта	Описание
name	string	Название проверки.
type	string	Тип проверки (web, tcp, ssl, api, synthetic, multistep, portscan, icmp, dns).
interval	number	Интервал проверки в секундах (минимум 30).
host или url	string	Хост или URL для проверки, в зависимости от type.

Примечание: В зависимости от type могут потребоваться дополнительные поля, например, port для tcp.

Ответ

API вернет объект созданной Проверки.

Изменить или удалить Проверку

PUT /v1/checks/{check_id}
PATCH /v1/checks/{check_id}
DELETE /v1/checks/{check_id}

Используйте те же поля, что и в объекте проверки для изменения. DELETE запрос удаляет проверку.

Параметры Проверки

Поле parameters содержит конфигурацию, специфичную для типа проверки (type).

Для type: "web" и type: "api"

Эти типы проверок могут содержать следующие параметры:

"parameters": {
    "regions": [] // Список регионов из которых запустится проверка
    "http_request": {
        "body": "", // Тело запроса (например, JSON для POST/PUT)
        "headers": { // Заголовки HTTP запроса
            "X-API-KEY": "your-api-key",
            "content-type": "application/json"
        },
        "method": "GET", // HTTP метод: GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH
        "password": "",  // Пароль для Basic Auth
        "username": ""   // Имя пользователя для Basic Auth
    },
    "search_text": "" // Опциональный текст для поиска в теле ответа, чтобы считать проверку успешной
}

Для type: "tcp"

Для TCP проверок объект parameters может содержать search_text и send_text.

"parameters": {
  "regions": [] // Список регионов из которых запустится проверка
  "search_text": "OpenSSH_9.7", // Читать из сокета и искать текст
  "send_text": "" // Отправить текст в сокет
},

Для type: "ssl"

Для SSL проверок объект parameters может содержать настройки, связанные с валидацией сертификата, например, количество дней до истечения срока действия для предупреждения.

"parameters": {
  "regions": [] // Список регионов из которых запустится проверка
  "assertions": {
    "ssl_score": 70, // Все проверки с SSL баллом ниже 70 будут неуспешны
    "expiration_threshold": 1209600 // Предупреждать за N секунд до истечения SSL сертификата
  }
}

Для type: "multistep" и type: "synthetic"

Для пошаговых проверок достаточно передать в объекте parameters скрипт Playwright в pw_script.

{
  "parameters": {
    "regions": [] // Список регионов из которых запустится проверка
    "pw_script": "// Импортируем необходимые модули из библиотеки Playwright\nconst { test, expect } = require('@playwright/test');\n\ntest.describe('Тестирование API эндпоинта get-templates', () => {\n  test('должен успешно получить данные и убедиться, что они не пустые', async ({ request }) => {\n    \n    const apiUrl = 'https://api.pingera.ru/v1/pages/get-templates';\n\n    try {\n      const response = await request.get(apiUrl);\n\n      expect(response.ok(), 'API эндпоинт должен быть доступен и возвращать успешный статус.').toBeTruthy();\n      \n      const responseBody = await response.json();\n\n      expect(typeof responseBody, 'Тело ответа должно быть объектом.').toBe('object');\n      expect(responseBody).not.toBeNull();\n      expect(Array.isArray(responseBody), 'Тело ответа не должно быть массивом.').toBe(false);\n      expect(Object.keys(responseBody).length, 'Объект с шаблонами не должен быть пустым.').toBeGreaterThan(0);\n\n      console.log('✅ Тест успешно пройден! Эндпоинт доступен и возвращает непустой результат.');\n\n    } catch (error) {\n      console.error('❌ Произошла ошибка во время выполнения теста:', error);\n      throw error;\n    }\n  });\n});"
  }
}

Для type: "icmp"

Для ICMP (Ping) проверок объект parameters может содержать настройки отправки ICMP echo-запросов и валидации результатов.

{
  "parameters": {
    "regions": [], // Список регионов из которых запустится проверка
    "probe_count": 4, // Количество ping-проб (по умолчанию: 4, диапазон: 1-100)
    "ip_version": "auto", // Версия IP: 'v4', 'v6', или 'auto' (предпочитает v6)
    "probe_interval": 1.0, // Интервал между пробами в секундах (по умолчанию: 1.0, диапазон: 0.001-10)
    "probe_timeout": 1.0, // Таймаут отдельной пробы в секундах (по умолчанию: 1.0, диапазон: 0.1-30)
    "assertions": {
      "max_packet_loss": 10 // Максимально допустимый процент потери пакетов (диапазон: 0-100)
    }
  }
}

Для type: "dns"

Для DNS проверок объект parameters может содержать настройки DNS-запроса и валидации ответов.

{
  "parameters": {
    "regions": [], // Список регионов из которых запустится проверка
    "record_type": "A", // Тип DNS-записи (по умолчанию: 'A'): A, AAAA, MX, TXT, CNAME, NS, SOA и др.
    "dns_servers": ["8.8.8.8", "1.1.1.1"], // Список пользовательских DNS-серверов (необязательно)
    "expected_answers": ["93.184.216.34"], // Список ожидаемых DNS-ответов для валидации (необязательно)
    "validation_mode": "contains_all", // Режим валидации: 'contains_all' (по умолчанию) или 'exact'
    "whois_lookup": false // Получение WHOIS информации о домене (по умолчанию: false)
  }
}

Результаты DNS проверки с WHOIS содержат дополнительную информацию о регистрации домена:

{
  "check_metadata": {
    "domain": "example.com",
    "record_type": "A",
    "dns_servers": "system_default",
    "validation_mode": "none",
    "authoritative_nameservers": ["a.iana-servers.net.", "b.iana-servers.net."],
    "answers": ["93.184.216.34"],
    "expected_answers": null,
    "whois_info": {
      "domain_name": "example.com",
      "registrar": "Example Registrar, Inc.",
      "creation_date": "1995-08-14T04:00:00",
      "expiration_date": "2026-08-13T04:00:00",
      "updated_date": "2024-08-14T07:01:38",
      "status": ["clientDeleteProhibited", "clientTransferProhibited", "clientUpdateProhibited"]
    }
  }
}

Параметр whois_lookup особенно полезен для мониторинга срока действия регистрации доменов. Вы можете настроить оповещения, чтобы получать уведомления заблаговременно перед истечением срока регистрации. Подробнее см. в разделе DNS проверки.

Для type: "portscan"

Для Portscan проверок объект parameters может содержать настройки сканирования портов с использованием nmap.

{
  "parameters": {
    "regions": [], // Список регионов из которых запустится проверка
    "ports": "top-ports:100", // Спецификация портов (по умолчанию: 'top-ports:100')
    "scan_type": "syn", // Тип сканирования: 'syn', 'connect', 'udp' (по умолчанию: 'syn')
    "service_detection": true, // Определение версии сервиса (по умолчанию: true)
    "timing": "T3", // Шаблон времени T0-T5 (по умолчанию: 'T3')
    "host_timeout": "5m", // Максимальное время на хост (по умолчанию: '5m')
    "min_parallelism": 100, // Минимальное количество параллельных проб (по умолчанию: 100)
    "max_rtt_timeout": "100ms", // Максимальное время ожидания ответа (например, '100ms', '2s')
    "assertions": {
      "fail_on_vulnerabilities": true, // Считать проверку неуспешной при обнаружении уязвимостей
      "min_risk_level": "high", // Минимальный уровень риска: 'critical', 'high', 'medium', 'low', 'info'
      "expected_open_ports": [80, 443] // Список ожидаемых открытых портов
    }
  }
}

Результаты portscan проверки содержат:

{
  "check_metadata": {
    "target": "example.com",
    "execution_time": 5678,
    "scan_results": [
      {
        "ip": "93.184.216.34",
        "hostname": "example.com",
        "state": "up",
        "open_ports": [
          {
            "port": 80,
            "protocol": "tcp",
            "service": "http",
            "version": "nginx 1.18.0",
            "product": "nginx",
            "extrainfo": ""
          }
        ],
        "os_matches": []
      }
    ],
    "summary": {
      "total_hosts": 1,
      "hosts_up": 1,
      "hosts_down": 0,
      "total_open_ports": 2
    },
    "vulnerabilities": [
      {
        "port": 23,
        "service": "Telnet",
        "risk_level": "high",
        "description": "Unencrypted remote access",
        "detected_version": "unknown"
      }
    ]
  }
}

Подробнее о настройке portscan проверок см. в разделе Portscan (Мониторинг портов).

Регионы проверок

GET /v1/checks/get-regions
GET /v1/checks/get-regions?check_type=<str>

Получить список регионов из которых можно запустить проверку с фильтрацией по типу проверки. Подробнее про регионы.

Пример объекта:

{
  "regions": [
    {
      "id": "IN, Mumbai",
      "display_name": "Asia, South, Mumbai",
      "aliases": ["asia-south1", "in-mum1"],
      "available_check_types": [
        "api",
        "dns",
        "icmp",
        "multistep",
        "ssl",
        "synthetic",
        "tcp",
        "web"
      ]
    },
    {
      "id": "EU, West",
      "display_name": "Europe, West, Belgium",
      "aliases": ["eu-west1", "eu-bel1"],
      "available_check_types": [
        "api",
        "dns",
        "icmp",
        "multistep",
        "ssl",
        "synthetic",
        "tcp",
        "web"
      ]
    },
    {
      "id": "ZA, Johannesburg",
      "display_name": "Africa, South, Johannesburg",
      "aliases": ["africa-south1", "za-jnb1"],
      "available_check_types": [
        "api",
        "dns",
        "icmp",
        "multistep",
        "ssl",
        "synthetic",
        "tcp",
        "web"
      ]
    },
    {
      "id": "BR, Sao Paulo",
      "display_name": "South America, East, Sao Paulo",
      "aliases": ["southamerica-east1", "br-sao1"],
      "available_check_types": [
        "api",
        "dns",
        "icmp",
        "multistep",
        "ssl",
        "synthetic",
        "tcp",
        "web"
      ]
    },
    {
      "id": "CN, Hong Kong",
      "display_name": "Asia, East, Hong Kong",
      "aliases": ["asia-east2", "cn-hk1"],
      "available_check_types": [
        "api",
        "dns",
        "icmp",
        "multistep",
        "ssl",
        "synthetic",
        "tcp",
        "web"
      ]
    }
  ],
  "total_regions": 5
}

Поля

Поле	Тип данных	Описание
regions	array	Массив объектов, каждый из которых представляет собой описание доступного региона.
id	string	Уникальный идентификатор региона. Используется для указания региона при создании или редактировании проверок (например, в API запросах). Пример: "IN, Mumbai".
display_name	string	Читабельное название региона, предназначенное для отображения в пользовательском интерфейсе. Пример: "Asia, South, Mumbai".
aliases	array of strings	Массив альтернативных идентификаторов региона, которые можно использовать вместо основного id. Обычно включают идентификаторы облачных провайдеров (например, "asia-south1", "in-mum1").
available_check_types	array of strings	Массив строк, содержащих типы проверок, которые можно запускать из данного региона. Возможные значения включают: "api", "dns", "icmp", "multistep", "ssl", "synthetic", "tcp", "web".
total_regions	number	Общее количество доступных регионов.

Указать регионы для проверки

Регионы можно указать в массиве parameters.regions при создании или редактировании проверки. Если регион не указан, то проверка будет выполнена в регионе по умолчанию - RU, Moscow.

Вы можете использовать как основной идентификатор региона (id), так и любой из его псевдонимов (aliases). Например, для европейского региона допустимы все варианты: "EU, West", "eu-west1", "eu-bel1".

{
  "name": "My new synthetic check",
  "type": "synthetic",
  "timeout": 10,
  "parameters": {
      "regions": ["RU, Moscow", "asia-south1"],
      ...
  }
}

Параллельное выполнение проверок

Когда вы выбираете несколько регионов для проверки, у вас появляется возможность запускать проверки параллельно из всех выбранных регионов одновременно или из случайного подмножества регионов.

Настройка через API

Для включения параллельного выполнения используйте параметр multi_region_execution в объекте parameters:

Выполнение во всех регионах:

{
  "name": "Global API Monitor",
  "type": "web",
  "url": "https://api.example.com",
  "interval": 300,
  "parameters": {
    "regions": ["RU, Moscow", "EU, West", "US, East Coast"],
    "multi_region_execution": {
      "enabled": true,
      "execution_mode": "all"
    }
  }
}

Выполнение в случайных N регионах:

{
  "name": "Sample Regional Monitor",
  "type": "web",
  "url": "https://api.example.com",
  "interval": 300,
  "parameters": {
    "regions": ["RU, Moscow", "EU, West", "US, East Coast", "Asia, Tokyo", "AU, Sydney"],
    "multi_region_execution": {
      "enabled": true,
      "execution_mode": "random_n",
      "count": 2
    }
  }
}

Параметры multi_region_execution

Параметр	Тип	Обязательный	Описание
enabled	boolean	Да	Включает или выключает параллельное выполнение
execution_mode	string	Да	Режим выполнения: "all" (все регионы) или "random_n" (случайные N регионов)
count	number	Нет	Количество случайных регионов (обязателен только для режима "random_n")

Тарификация параллельных проверок

Важно: При использовании параллельного выполнения кредиты списываются за каждое выполнение в каждом регионе отдельно.

Например:

• Если вы запускаете ICMP проверку (стоимость 1 кредит) параллельно в 3 регионах, с вас будет списано 3 кредита (3 региона × 1 кредит)
• Если вы запускаете синтетическую проверку (стоимость 10 кредитов) параллельно в 5 регионах, с вас будет списано 50 кредитов (5 регионов × 10 кредитов)

Особенности работы параллельных проверок

Повторные попытки

При параллельном выполнении проверки не повторяются автоматически в случае неудачи. Мы считаем, что наличие нескольких регионов уже обеспечивает достаточную надёжность для определения проблем с сервисом.

Результаты проверок

При параллельном выполнении результаты группируются в группы выполнения (execution groups). Каждая группа содержит результаты из всех регионов для одного запуска проверки. Это важно учитывать при работе с алертами и анализе результатов через API.

Подробнее о параллельном выполнении см. в разделе Регионы проверок.

Для работы с группами выполнения через API см. документацию Группы выполнения.