Инциденты

В этой статье мы опишем, как можно управлять Инцидентами Статус Страниц через API. Инциденты представляют собой события, влияющие на работу ваших компонентов или сервисов.

Объект Инцидента

GET /v1/pages/{page_id}/incidents
GET /v1/pages/{page_id}/incidents/unresolved
GET /v1/pages/{page_id}/incidents/{incident_id}

Метод для получения всех инцидентов указанной Статус Страницы или одного инцидента по ID. Пример объекта:

{
  "auto_transition_deliver_notifications_at_end": false,
  "auto_transition_deliver_notifications_at_start": false,
  "auto_transition_to_maintenance_state": false,
  "auto_transition_to_operational_state": false,
  "components": [
    {
      "created_at": "2025-05-02T08:51:26.818399",
      "description": "Еще один демонстрационный компонент",
      "group": false,
      "group_id": "5p48re6calih",
      "id": "ydwkigxh69gp",
      "name": "Демо компонент 2",
      "only_show_if_degraded": false,
      "page_id": "5rs9dvpvyyp8",
      "position": 0,
      "showcase": true,
      "start_date": null,
      "status": "operational",
      "updated_at": "2025-05-11T19:48:38.966575"
    },
    {
      "created_at": "2025-01-30T17:27:20",
      "description": "Это демонстрационный компонент. На нем показываем инциденты и новые фичи",
      "group": false,
      "group_id": "5p48re6calih",
      "id": "gnmsg97pjj3c",
      "name": "Демо компонент",
      "only_show_if_degraded": false,
      "page_id": "5rs9dvpvyyp8",
      "position": 0,
      "showcase": true,
      "start_date": null,
      "status": "operational",
      "updated_at": "2025-05-11T19:48:38.963415"
    }
  ],
  "created_at": "2025-05-11T19:46:54.470501",
  "id": "xd9p9fj2rt6a",
  "impact": "minor",
  "incident_updates": [
    {
      "body": "Закрываем демо инцидент. Все очень хорошо.",
      "components": {
        "gnmsg97pjj3c": "operational",
        "ydwkigxh69gp": "operational"
      },
      "created_at": "2025-05-11T19:48:38.959114",
      "deliver_notifications": false,
      "display_at": null,
      "id": "txt2udbikij6",
      "incident_id": "xd9p9fj2rt6a",
      "status": "resolved",
      "updated_at": "2025-05-11T19:48:38.959117"
    },
    {
      "body": "Все хорошо, мы как всегда демонстрируем инцидент.",
      "components": {
        "gnmsg97pjj3c": "major_outage",
        "ydwkigxh69gp": "partial_outage"
      },
      "created_at": "2025-05-11T19:46:54.483345",
      "deliver_notifications": true,
      "display_at": null,
      "id": "6055hqw6393s",
      "incident_id": "xd9p9fj2rt6a",
      "status": "investigating",
      "updated_at": "2025-05-11T19:46:54.483347"
    }
  ],
  "metadata": null,
  "monitoring_at": null,
  "name": "Какой-то демо инцидент",
  "page_id": "5rs9dvpvyyp8",
  "postmortem_body": null,
  "postmortem_body_last_updated_at": null,
  "postmortem_published_at": null,
  "reminder_intervals": null,
  "resolved_at": "2025-05-11T19:48:38.959114",
  "scheduled_auto_completed": false,
  "scheduled_auto_in_progress": false,
  "scheduled_for": null,
  "scheduled_remind_prior": false,
  "scheduled_reminded_at": null,
  "scheduled_until": null,
  "status": "resolved",
  "updated_at": "2025-05-11T19:48:38.956474"
}

Открытые Инциденты

/v1/pages/{page_id}/incidents/unresolved возвращает открытые инциденты, у которых resolved_at не установлен.

Поля

Поле	Тип объекта	Описание
`auto_transition_deliver_notifications_at_end`	`boolean`	Указывает, нужно ли отправлять уведомления об инциденте при его завершении.
`auto_transition_deliver_notifications_at_start`	`boolean`	Указывает, нужно ли отправлять уведомления об инциденте при его начале.
`auto_transition_to_maintenance_state`	`boolean`	Указывает, нужно ли автоматически переводить инцидент в состояние "обслуживание".
`auto_transition_to_operational_state`	`boolean`	Указывает, нужно ли автоматически переводить инцидент в состояние "в рабочем состоянии".
`components`	`array` of `object`	Массив объектов компонентов, затронутых инцидентом. Каждый объект компонента содержит подробную информацию о компоненте.
`created_at`	`string` (ISO 8601)	Дата и время создания инцидента.
`id`	`string`	Уникальный идентификатор инцидента.
`impact`	`string`	Уровень критичности инцидента (`minor`, `major`, `critical` и т.д.).
`incident_updates`	`array` of `object`	Массив обновлений инцидента. Каждый объект обновления содержит информацию об изменении статуса инцидента, затронутых компонентах и другие детали.
`incident_updates[].body`	`string`	Текст обновления инцидента.
`incident_updates[].components`	`object`	Объект, содержащий статусы затронутых компонентов в данном обновлении. Ключи - ID компонентов, значения - их новые статусы.
`incident_updates[].created_at`	`string` (ISO 8601)	Дата и время создания обновления инцидента.
`incident_updates[].deliver_notifications`	`boolean`	Указывает, нужно ли рассылать уведомления об этом обновлении.
`incident_updates[].display_at`	`string` or `null`	Дата и время, когда обновление должно быть отображено.
`incident_updates[].id`	`string`	Уникальный идентификатор обновления инцидента.
`incident_updates[].incident_id`	`string`	Идентификатор инцидента, к которому относится данное обновление.
`incident_updates[].status`	`string`	Статус обновления инцидента.
`incident_updates[].updated_at`	`string` (ISO 8601)	Дата и время последнего обновления обновления инцидента.
`metadata`	`object` or `null`	Дополнительные метаданные, связанные с инцидентом.
`monitoring_at`	`string` or `null`	Дата и время начала мониторинга инцидента.
`name`	`string`	Название инцидента.
`page_id`	`string`	Идентификатор страницы, на которой произошел инцидент.
`postmortem_body`	`string` or `null`	Содержание заключения после инцидента (postmortem).
`postmortem_body_last_updated_at`	`string` or `null`	Дата и время последнего обновления заключения после инцидента.
`postmortem_published_at`	`string` or `null`	Дата и время публикации заключения после инцидента.
`reminder_intervals`	`array` or `null`	Интервалы времени для напоминаний об инциденте.
`resolved_at`	`string` or `null`	Дата и время разрешения инцидента.
`scheduled_auto_completed`	`boolean`	Указывает, был ли инцидент автоматически завершен по расписанию.
`scheduled_auto_in_progress`	`boolean`	Указывает, был ли инцидент автоматически переведен в состояние "в процессе" по расписанию.
`scheduled_for`	`string` or `null`	Дата и время начала запланированного инцидента.
`scheduled_remind_prior`	`boolean`	Указывает, нужно ли напоминать об инциденте до его начала.
`scheduled_reminded_at`	`string` or `null`	Дата и время отправки напоминания о запланированном инциденте.
`scheduled_until`	`string` or `null`	Дата и время окончания запланированного инцидента.
`status`	`string`	Текущий статус инцидента. Может быть `investigating`, `identified`, `monitoring`, `resolved`
`updated_at`	`string` (ISO 8601)	Дата и время последнего обновления инцидента.

Получить запланированные работы

GET /v1/pages/{page_id}/incidents/maintenance

Получить запланированные работы (maintenance windows) для указанной Статус Страницы. По умолчанию возвращает работы со статусом scheduled.

Параметры запроса

Параметр	Тип	Описание
`status`	`string` (опционально)	Фильтр по статусу работ. Возможные значения: `scheduled`, `in_progress`, `verifying`, `completed`. По умолчанию: `scheduled`

Примеры запросов

Получить все запланированные работы:

curl -X GET \
  -H "Authorization: YOUR_API_KEY" \
  https://api.pingera.ru/v1/pages/5rs9dvpvyyp8/incidents/maintenance

Получить работы, которые сейчас выполняются:

curl -X GET \
  -H "Authorization: YOUR_API_KEY" \
  https://api.pingera.ru/v1/pages/5rs9dvpvyyp8/incidents/maintenance?status=in_progress

Получить завершенные работы:

curl -X GET \
  -H "Authorization: YOUR_API_KEY" \
  https://api.pingera.ru/v1/pages/5rs9dvpvyyp8/incidents/maintenance?status=completed

Ответ

API вернет массив объектов инцидентов. Для запланированных работ особенно важны следующие поля:

Поле	Тип	Описание
`scheduled_for`	`string` (ISO 8601)	Дата и время начала работ
`scheduled_until`	`string` (ISO 8601)	Дата и время окончания работ
`scheduled_reminded_at`	`string` or `null`	Время отправки последнего напоминания
`scheduled_auto_completed`	`boolean`	Автоматически завершить работы в `scheduled_until`
`scheduled_auto_in_progress`	`boolean`	Автоматически начать работы в `scheduled_for`
`auto_transition_deliver_notifications_at_end`	`boolean`	Отправлять уведомления при завершении работ
`auto_transition_deliver_notifications_at_start`	`boolean`	Отправлять уведомления при начале работ
`auto_transition_to_maintenance_state`	`boolean`	Переводить компоненты в статус "Запланированные работы" при начале
`auto_transition_to_operational_state`	`boolean`	Восстанавливать компоненты в статус "Работает штатно" при завершении
`scheduled_remind_prior`	`boolean`	Включить напоминания перед началом работ
`reminder_intervals`	`string` or `null`	Интервалы для напоминаний (например, "24h,1h")

Открыть Инцидент

POST /v1/pages/{page_id}/incidents

Открыть новый Инцидент для указанной Статус Страницы.

Требуемые поля

Поле	Тип объекта	Описание
`name`	`string`	Имя инцидента
`body`	`string`	Текст обновления инцидента
`status`	`string`	Статус инцидента. Может быть `investigating`, `identified`, `monitoring`, `resolved`.
`components`	`object`	Обновление статусов компонентов: `{"component_id": "status", ...}`

Например, чтобы создать инцидент необходимо послать запрос такого содержания:

curl -X POST 
-H "Authorization: API_KEY" 
-H "Content-type: application/json" 
https://api.pingera.ru/v1/pages/{page_id}/incidents 
-d '{ 
  "name": "имя инцидента", 
  "body": "какое-то сообщение", 
  "components": {
    "gnmsg97pjj3c": "major_outage",
    "ydwkigxh69gp": "partial_outage"
  }
}'

Будет создан инцидент в со статусом из status, для компонентов поменяется статус, а подписчикам будет разослано уведомление с body и другими деталями.

Ответ

API вернет объект инцидента.

Изменить или удалить Инцидент

PUT /v1/pages/{page_id}/incidents/{incident_id}
PATCH /v1/pages/{page_id}/incidents/{incident_id}
DELETE /v1/pages/{page_id}/incidents/{incident_id}

Используйте методы PUT или PATCH для частичного обновления существующего инцидента по его ID на указанной Статус Странице. Метод DELETE используется для удаления инцидента.

При обновлении инцидента поведение API зависит от полей, которые вы передаете:

Обновление основных полей инцидента: Если вы передаете поля name или impact, API просто обновит соответствующие поля объекта инцидента.
Создание обновления инцидента и обновление статусов компонентов: Если вы передаете поля body или components (или deliver_notifications), API создаст новую запись в incident_updates с указанным body и обновит статусы соответствующих компонентов. Поле deliver_notifications по умолчанию имеет значение true, если не указано иное.

Примеры обновления инцидента

Частичное обновление названия инцидента:

curl -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.pingera.ru/v1/pages/5rs9dvpvyyp8/incidents/xd9p9fj2rt6a \
  -d '{
    "name": "Обновленное название инцидента"
  }'

Этот запрос обновит только название инцидента с ID xd9p9fj2rt6a на странице 5rs9dvpvyyp8.

Частичное обновление уровня критичности инцидента:

curl -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.pingera.ru/v1/pages/5rs9dvpvyyp8/incidents/xd9p9fj2rt6a \
  -d '{
    "impact": "major"
  }'

Этот запрос обновит только уровень критичности инцидента с ID xd9p9fj2rt6a.

Создание нового обновления инцидента и обновление статусов компонентов:

curl -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.pingera.ru/v1/pages/5rs9dvpvyyp8/incidents/xd9p9fj2rt6a \
  -d '{
    "body": "Проблема все еще сохраняется, мы продолжаем работу.",
    "components": {
      "gnmsg97pjj3c": "major_outage",
      "ydwkigxh69gp": "degraded_performance"
    },
    "deliver_notifications": true
  }'

Этот запрос создаст новое обновление для инцидента с ID xd9p9fj2rt6a со следующим текстом: "Проблема все еще сохраняется, мы продолжаем работу." Он также обновит статус компонента gnmsg97pjj3c на major_outage и компонента ydwkigxh69gp на degraded_performance. Уведомления об этом обновлении будут разосланы.

Создание нового обновления инцидента без рассылки уведомлений:

curl -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.pingera.ru/v1/pages/5rs9dvpvyyp8/incidents/xd9p9fj2rt6a \
  -d '{
    "body": "Внутреннее обновление: найден потенциальный источник проблемы.",
    "deliver_notifications": false
  }'

Этот запрос создаст новое обновление для инцидента, но уведомления рассылаться не будут. Статусы компонентов останутся без изменений.

При успешном обновлении API вернет обновленный объект инцидента.

Закрытие инцидента

curl -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.pingera.ru/v1/pages/5rs9dvpvyyp8/incidents/xd9p9fj2rt6a \
  -d '{
    "body": "Инцидент закрыт",
    "status": "resolved"
  }'

Если вы выставляете status Инцидента в resolved, то поле resolved_at автоматически выставляется в значение времени now.

Объект Инцидента​

Открытые Инциденты​

Поля​

Получить запланированные работы​

Параметры запроса​

Примеры запросов​

Ответ​

Открыть Инцидент​

Требуемые поля​

Ответ​

Изменить или удалить Инцидент​

Примеры обновления инцидента​

Объект Инцидента

Открытые Инциденты

Поля

Получить запланированные работы

Параметры запроса

Примеры запросов

Ответ

Открыть Инцидент

Требуемые поля

Ответ

Изменить или удалить Инцидент

Примеры обновления инцидента