Python SDK

Pingera Python SDK — это официальный SDK для работы с платформой мониторинга Pingera. Он предоставляет полный набор инструментов для управления мониторингом, инцидентами, статусами и другими ресурсами прямо из вашего кода. SDK автоматически сгенерирован на основе спецификации OpenAPI, что гарантирует полный охват API и строгую типизацию.

Ключевые особенности

Полный охват API: SDK предоставляет доступ ко всем существующим эндпоинтам Pingera API.
Типобезопасность: Все модели данных (запросы и ответы) имеют строгую типизацию благодаря Pydantic, что снижает количество ошибок и улучшает автодополнение в IDE.
Удобство использования: Простая аутентификация и интуитивно понятные классы для работы с различными модулями.
Открытый исходный код: Проект опубликован под лицензией MIT на GitHub, что позволяет любому желающему вносить свой вклад.

Установка

SDK доступен через PyPI. Для установки выполните следующую команду:

pip install pingera-sdk

Быстрый старт и аутентификация

Для начала работы вам необходимо настроить API-ключ. Сделайте это в личном кабинете в меню "Настройки"

SDK поддерживает несколько способов аутентификации.

Способ 1: Переменные окружения

Самый простой способ — использовать переменную окружения.

export PINGERA_API_KEY="ваш_api_токен"

Затем в коде вы можете инициализировать клиент:

from pingera import PingeraClient

# Клиент автоматически загрузит токен из PINGERA_API_KEY
client = PingeraClient.from_env()

Способ 2: Ручная конфигурация

Вы также можете передать токен напрямую при инициализации клиента.

from pingera import PingeraClient, APIKeyAuth

auth = APIKeyAuth("ваш_api_токен")
client = PingeraClient(auth=auth)

# Или используя Configuration
from pingera import ApiClient, Configuration
configuration = Configuration(host="https://api.pingera.ru")
configuration.api_key['apiKeyAuth'] = "ваш_api_токен"
api_client = ApiClient(configuration)

Модули API

SDK организован по модулям, каждый из которых отвечает за определенную часть функциональности Pingera. Вы можете получить к ним доступ через свойства основного объекта клиента (PingeraClient).

Модуль	Описание	Доступ через `client.xyz`
AlertsApi	Управление алертами и каналами уведомлений	`client.alerts`
ChecksApi	Управление регулярными проверками	`client.checks`
ChecksUnifiedResultsApi	Запросы к объединенным результатам проверок	`client.checks_unified_results`
HeartbeatsApi	Управление Пульсарами (cronjob-проверки)	`client.heartbeats`
OnDemandChecksApi	Запуск проверок по требованию	`client.on_demand_checks`
StatusPagesApi	Управление Статус Страницами	`client.status_pages`
StatusPagesComponentsApi	Управление компонентами на Статус Страницах	`client.components`
StatusPagesIncidentsApi	Управление инцидентами и плановыми работами Статус Страниц	`client.incidents`

Примеры использования

1. Управление компонентами на странице статуса

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

from pingera import PingeraClient
from pingera.models import Component

# Инициализируем клиент
client = PingeraClient.from_env()

# Замените на ID вашей страницы статуса
PAGE_ID = "ваш_page_id"

# 1. Создание нового компонента
new_component = Component(
    name="API Server",
    description="Основной API-сервер",
    status="operational"
)
created_component = client.components.v1_pages_page_id_components_post(
    page_id=PAGE_ID,
    component=new_component
)
print(f"✅ Компонент '{created_component.name}' создан с ID: {created_component.id}")

# 2. Обновление статуса компонента
client.components.v1_pages_page_id_components_component_id_status_put(
    page_id=PAGE_ID,
    component_id=created_component.id,
    status="degraded_performance"
)
print(f"⚠️ Статус компонента '{created_component.name}' обновлен на 'degraded_performance'")

# 3. Получение списка всех компонентов
all_components = client.components.v1_pages_page_id_components_get(page_id=PAGE_ID)
print(f"🔎 Найдено {len(all_components.data)} компонентов на странице статуса.")

2. Запуск синтетической проверки по требованию

Этот пример демонстрирует, как запустить on-demand проверку с использованием Playwright-сценария. Это полезно для автоматического тестирования после деплоя или локального тестирования.

import os
import time
import json
from pingera import PingeraClient
from pingera.models import ExecuteCustomCheckRequest
from pingera.exceptions import ApiException

# Инициализируем клиент из переменных окружения
client = PingeraClient.from_env()

# Наш Playwright-сценарий
playwright_script = """
const { test, expect } = require('@playwright/test');
test('Basic Screenshot', async ({ page }) => {
  await page.goto('https://pingera.ru/');
  await page.waitForLoadState('networkidle');
  await page.screenshot({ path: 'screenshot.png', fullPage: true });
  console.log('Скриншот сделан!');
});
"""

# Создаем запрос на запуск on-demand проверки
request_body = ExecuteCustomCheckRequest(
    url="https://pingera.ru",
    type="synthetic",
    parameters={"pw_script": playwright_script},
    timeout=60,
    name="On-Demand Check from SDK"
)

try:
    print("🚀 Запуск on-demand синтетической проверки...")
    job_result = client.on_demand_checks.v1_checks_execute_post(request_body)
    job_id = job_result.job_id
    print(f"✅ Проверка отправлена! ID задачи: {job_id}")

    # Ожидаем завершения
    max_wait_time = 60  # 60 секунд
    start_time = time.time()
    while True:
        if time.time() - start_time > max_wait_time:
            print("❌ Превышено время ожидания.")
            break
        
        job_status = client.on_demand_checks.v1_checks_jobs_job_id_get(job_id=job_id)
        if job_status.status in ["completed", "failed"]:
            print("✅ Задача выполнена.")
            
            # Выводим детальный результат
            print("=== Детальный результат ===")
            print(json.dumps(job_status.result.to_dict(), indent=2))
            break
        
        print("⏳ Ожидание завершения...")
        time.sleep(5)
            
except ApiException as e:
    print(f"❌ Ошибка API: {e.status} - {e.reason}")

Работа с моделями данных

Все запросы и ответы API используют типизированные модели Pydantic. Это обеспечивает строгий контроль данных и предотвращает ошибки.

from pingera.models import IncidentCreate, IncidentUpdateCreate

# Создание нового инцидента
new_incident = IncidentCreate(
    name="Проблемы с подключением к базе данных", 
    body="Изучаем проблему с подключением к БД",
    status="investigating",
    impact="major"
)

# Добавление обновления к существующему инциденту
incident_update = IncidentUpdateCreate(
    body="Проблема найдена и скоро будет исправлена",
    status="identified"
)

Обработка ошибок

SDK использует стандартные исключения для обработки ошибок API.

from pingera.exceptions import ApiException

try:
    # Пример вызова, который может вызвать ошибку
    client.checks.v1_checks_check_id_get(check_id="несуществующий_id")
except ApiException as e:
    print(f"❌ Ошибка API: статус {e.status}, причина: {e.reason}")
    if e.body:
        print(f"Детали ошибки: {e.body}")

Документация и ресурсы

Документация API
GitHub-репозиторий: https://github.com/pingera/pingera-python-sdk
Примеры использования: Директория examples в репозитории
Сгенерированная документация API: Pingera Python SDK - API Methods Documentation

Ключевые особенности​

Установка​

Быстрый старт и аутентификация​

Способ 1: Переменные окружения​

Способ 2: Ручная конфигурация​

Модули API​

Примеры использования​

1. Управление компонентами на странице статуса​

2. Запуск синтетической проверки по требованию​

Работа с моделями данных​

Обработка ошибок​

Документация и ресурсы​