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

# Создание сценария автоматизации

В данном разделе рассмотрим общие принципы создания и построения сценариев автоматизации.

Перед созданием вашего первого сценария рекомендуется ознакомиться с терминологией и общими понятия о функционале Автоматизации:

Глоссарий терминов раздела Автоматизация

Основные положения функционала Автоматизации

# Добавление сценария

  1. Перейдите через основное меню в раздел Действия - Автоматизация - откроется экран управления сценариями.
  2. Для добавления в систему нового сценария нажмите кнопку ➕ Создать сценарий в правом верхнем углу экрана.
  3. Заполните основные параметры создаваемого сценария:
    • Владелец сценария - Рабочая группа, которой будет принадлежать сценарий.
    • Название - логически понятное название сценария.
    • Тип - CMDBAutoDiscovery.
    • Описание (опционально).
    • Импорт сценария (опционально). image
  4. Нажмите кнопку Создать - сценарий будет создан и откроется конструктор сценария.
  5. Каждый сценарий начинает работу с События запуска - блока OnLogEvent,
    автоматически добавляемого при создании каждого сценария.
    image
    • Удалить или изменить блок OnLogEvent нельзя.
    • В исходящем пине (переменной) Value блока OnLogEvent содержится значение первичного события, переданного в коллектор через:

# Фильтрация событий

Следующим действием необходимо произвести фильтрацию поступающих событий в сценарий Автоматизации.

Для этого добавьте блок локальной функции в сценарий:

  1. В диспетчере объектов нажмите ➕ в категории Локальные функции - будет объявлена функция CodeFunction.

    image

  2. В меню действий над функцией CodeFunction выберите Добавить в сценарий </>.

  3. Двойным кликом по добавленному блоку локальной функции откройте Инспектор объектов.

    image

  4. Измените Название локальной функции, например FilterEvents.

  5. Добавьте Входящий пин InValue с типом Monq.Cl.CollectorLogEvent.

    Системный тип Monq.Cl.CollectorLogEvent описывает структуру первичного события monq.

  6. Настройте Исходящие пины следующим образом:

    • ok, тип Exec
    • failed, тип Exec

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

    image

  7. Перейдите в режим редактирования текущей локальной функции FilterEvents- нажмите на вкладку Редактор находясь в Инспекторе объектов.

  8. Приведите код функции к следующему виду:

    private async ValueTask<FuncResult> FilterEvents(Monq.Cl.CollectorLogEvent InValue) {
if (InValue._stream.id == 248)
{
  return new FuncResult("ok");
}
return new FuncResult("failed");
}

    image

    В данном примере производится проверка поля первичного события _stream.id (идентификатор "Потока данных") c предзаданным пользователем значением = 248.
    Если первичное событие пришло через Поток данных, имеющий идентификатор id = 248 дальнейшее прохождение сценария будет выполнено по Исходящему пину ok, иначе по Исходящему пину failed. В нашем сценарии, события пришедшие по другим Потокам данных будут завершены на пине failed и дальнейшая обработка сценария также будет завершена.

  9. Соедините соответствующие пины протягиванием связи между ними:

    • Блок OnLogEvent пин Out ➞ Блок FilterEvents пин In - связь очередности выполнения функций в сценарии.

    • Блок OnLogEvent пин Value ➞ Блок FilterEvents пин InValue - связь передачи значения переменной.

      image

# Обработка события

Рассмотрим пример создания Конфигурационной единицы (КЕ) по входящим событиям из Zabbix (объект host первичного события Zabbix).

# Пример первичного события из системы мониторинга Zabbix
{
  "id": "50133",
  "clock": 1646785676,
  "acknowledged": 0,
  "name": "Disk space usage",
  "value": 1,
  "severity": 4,
  "trigger": {
    "id": "20170",
    "revealedDescription": "Disk space usage",
    "description": "Disk space usage",
    "revealedComments": "",
    "comments": "",
    "expression": "{25124}>90",
    "lastChangeTime": 0,
    "priority": 4,
    "state": 0,
    "status": 0,
    "url": "",
    "value": 1
  },
  "group": {
    "id": "24",
    "name": "d12-apps"
  },
  "host": {
    "id": "10452",
    "hostValue": "d12 Host",
    "name": "d12 Host"
  },
  "itemsIds": [
    37676
  ],
  "tags": [],
  "zabbixVersion": 5.4
}

# Объявление структур

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

  1. Добавьте в сценарий глобальную функцию BreakStruct используя правую кнопку мыши.

  2. Соедините входящий пин Object функции BreakStruct с исходящим пином Value события запуска OnLogEvent. Автоматически будет произведена "раскладка" структуры первичного события на соответствующие свойства в виде исходящих пинов функции BreakStruct.

    image

  3. Нас интересует исходящий пин source с типом Dynamic, который содержит исходное событие с данными из Zabbix. А именно объект host, по данным которого мы будем создавать Конфигурационные единицы:

    "host": {
    "id": "10452",
    "hostValue": "d12 Host",
    "name": "d12 Host"
  }

  4. Для работы со значениями, содержащимися в фрагменте, необходимо описать структуру данного объекта:

    1. Создайте новую структуру в Диспетчере объектов - нажмите ➕ в категории Структуры - будет добавлена локальная структура Struct.

      image

    2. Нажмите левой кнопкой мыши по вновь созданной структуре - откроется Инспектор объектов данной структуры.

    3. Задайте Название структуры, например ZabbixHostObject

    4. Добавьте свойства структуры согласно JSON:

      • id, тип String
      • hostValue, тип String
      • name, тип String

      image

    5. Объявление структуры на данном этапе завершено.

# Доступ к полям события

Далее, чтобы получить доступ к объекту host и его свойствам понадобится глобальная функция BreakDynamic

  1. Добавьте в сценарий глобальную функцию BreakDynamic используя правую кнопку мыши.

  2. Соедините входящий пин Object функции BreakDynamic с исходящим пином source предыдущей глобальной функции BreakStruct.

    image

  3. Откройте Инспектор объектов функции BreakDynamic и добавьте исходящий пин hosts с типом ZabbixHostObject (ранее объявленная структура).

    image

  4. Далее необходимо опять "разложить" структуру объекта host, добавьте еще одну новую глобальную функцию BreakStruct и соедините пины:

    • Исходящий пин host функции BreakDynamic ➞ Входящий пин Object функции BreakStruct

    image

  5. На данном этапе мы получили доступ к переменным события из Zabbix: source.host.id, source.host.name, source.host.hostValue в виде исходящих пинов функции BreakStruct.

  6. Следующим шагом необходимо подготовить запрос на создание Конфигурационной единицы, используя публичный API.

# Создание конфигурационной единицы

Будет рассмотрен пример создания КЕ с типом по умолчанию и назначением владельца - текущей Рабочей группы (владелец сценария).

Для создания КЕ используется запрос следующего минимального содержания:

{
  # Идентификатор КЕ:
  "id": 0, 
  # Имя КЕ
  "name": "",
  # Описание КЕ
  "description": "",
  # ID РГ-владельца КЕ:
  "ownerWorkGroup": {
    "id": 0 
  }
}

  1. По представленному выше телу запроса необходимо создать 2 структуры:

    • createCIQuery - структура описывающая весь JSON
    • ownerWorkGroup - структура описывающая объекта "ownerWorkGroup": {"id": 0 }

  2. Создайте новую структуру в Диспетчере объектов - нажмите ➕ в категории Структуры - будет добавлена локальная структура Struct.

  3. Нажмите левой кнопкой мыши по вновь созданной структуре - откроется Инспектор объектов данной структуры.

  4. Задайте Название структуры, например ownerWorkGroup

  5. Добавьте свойства структуры согласно JSON:

    • id, тип Integer64

    image

  6. Повторите пункт 2-3 для создания еще одной структуры.

  7. Задайте Название структуры, например createCIQuery

  8. Добавьте свойства структуры согласно JSON:

    • id, тип String
    • name, тип String
    • description, тип String
    • ownerWorkGroup, тип ownerWorkGroup- созданная структура.

    image

# Подготовка тела запроса

Далее необходимо сформировать запрос на создание КЕ, где:

  • Название КЕ = source.host.name
  • Описание КЕ = source.host.id
  • Владелец КЕ = Владелец сценария

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

# Присвойте значение идентификатора Рабочей группы-владельца сценария переменной id в структуре ownerWorkGroup

  1. Добавьте в сценарий глобальную функцию SetMembersInStruct.

    image

  2. Создайте новую локальную переменную в Диспетчере объектов.

  3. В Инспекторе объектов укажите название созданной переменной, например ownerWorkGroupVar.
    Тип переменной укажите ownerWorkGroup - ранее созданная структура.

    image

  4. Добавьте переменную ownerWorkGroupVar в сценарий из Диспетчера объектов используя пункт контекстного меню Добавить в сценарий Get.

  5. Соедините пин переменной ownerWorkGroupVar с входящим пином Object блока SetMembersInStruct и откройте Инспектор объектов данного блока.

    image

  6. Отметьте входящий пин Id в диспетчере объектов - он будет добавлен как входящий пин текущего блока.

    image

  7. Добавьте в сценарий системную переменную OwnerWorkGroupId и соедините ее с входящим пином Id блока SetMembersInStruct.

    image

  8. Для того, чтобы данная функция была выполнена при запуске сценария соедините исходящий пин ok локальной функции FilterEvents с входящим пином In функции SetMembersInStruct.

    image

# Определите значения "Название КЕ" и "Описание КЕ" в структуре createCIQuery

  1. Добавьте в сценарий еще одну глобальную функцию SetMembersInStruct

    image

  2. Создайте новую локальную переменную в Диспетчере объектов

  3. В Инспекторе объектов укажите название созданной переменной, например CreateCIQueryVar.
    Тип переменной = CreateCIQuery - ранее созданная структура.

    image

  4. Добавьте переменную CreateCIQueryVar в сценарий из Диспетчера объектов.

  5. Соедините пин переменной CreateCIQueryVar с входящим пином Object блока SetMembersInStruct и откройте Инспектор объектов данного блока.

    image

  6. Выберите пины, которые необходимо определить, они появятся как входящие пины блока функции SetMembersInStruct.

    image

  7. Произведите следующую установку связей:

    • Входящий пин name функции SetMembersInStruct ➞ Исходящий пин name функции BreakStruct (передаем значение source.host.name в тело запроса на создание КЕ).
    • Входящий пин description функции SetMembersInStruct ➞ Исходящий пин id функции BreakStruct (передаем значение source.host.id в тело запроса на создание КЕ).
    • Входящий пин ownerWorkGroup функции SetMembersInStruct ➞ Исходящий пин Result функции SetMembersInStruct (передаем значение идентификатора Рабочей группы владельца сценария в тело запроса на создание КЕ).
    • Входящий пин In функции SetMembersInStruct ➞ Исходящий пин Out функции SetMembersInStruct (указываем очередность выполнения функций в сценарии).

  8. Установите значение входящего пина id функции SetMemberInStruct равной 0, для автоматической генерации идентификатора Конфигурационной единицы.

На данном этапе, ваш сценарий должен выглядеть следующим образом:

image

Далее необходимо отправить HTTP POST запрос в публичный API с подготовленными параметрами. Для этого необходима глобальная функция MonqHTTPRequest.

  1. Добавьте в сценарий глобальную функцию MonqHTTPRequest используя контекстное меню.

    image

  2. Для авторизации в публичном API используется специальный токен BearerToken. Чтобы авторизовать запрос понадобится системная переменная RobotToken. Добавьте ее из Диспетчера объектов.

    image

  3. Также для HTTP запроса необходимо указать идентификатор пространства. Текущее значение хранится в системной переменной UserspaceId, также добавьте ее в сценарий.

    image

  4. Произведите следующую установку связей:

    • Входящий пин UserspaceId функции MonqHTTPRequest ➞ Исходящий пин переменной UserspaceId (передаем значение идентификатора пространства в заголовке запроса на создание КЕ).
    • Входящий пин BearerToken функции MonqHTTPRequest ➞ Исходящий пин переменной RobotToken (передаем значение токена авторизации в заголовке запроса на создание КЕ).
    • Входящий пин Body функции MonqHTTPRequest ➞ Исходящий пин Result функции SetMembersInStruct (передаем тело HTTP запроса на создание КЕ).
    • Входящий пин In функции MonqHTTPRequest ➞ Исходящий пин Out функции SetMembersInStruct (указываем очередность выполнения функций в сценарии).

    image

  5. Определите значение входящих пинов Url и Type функции MonqHTTPRequest, указав соответствующие значения:

    • Url = https://<monq-global-domain>/api/public/sm/v2/rsm/config-items?makeNameUnique=false
    • Type = POST

    Замените <monq-global-domain> на доменное имя вашего пространства monq

    image

  6. Нажмите кнопку Скомпилировать в верхней панели конструктора сценария.

  7. Активируйте сценарий переключателем Активен/Неактивен в верхней панели конструктора сценария.

    image

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

image

Теперь при получении события из системы мониторинга Zabbix о проблеме или событии восстановления будет создаваться конфигурационная единица.

На этом возможности функционала Автоматизации не ограничены. Данный сценарий можно расширить различными условиями и проверками, а также выполнением других запросов публичного API.

Если у вас возникли трудности, вы можете импортировать в свою систему готовый сценарий используя функционал Импорт/Экспорт:

  1. Скопируйте код готового сценария в буфер обмена:
    zabbix-host.txt (opens new window)
  2. Перейдите в раздел управления сценариями Автоматизации.
  3. Создайте новый сценарий, задайте Владельца и Название сценария.
  4. Вставьте скопированный код в строку импорта.
  5. Нажмите Создать.
  6. Измените параметр _stream.id в локальной функции FilterEvents на идентификатор Потока данных, события которого необходимо обрабатывать сценарием автоматизации.