Устаревший REST API оповещений Log Analytics

В этой статье описывается, как управлять правилами генерации оповещений с помощью устаревшего API.

REST API оповещений Log Analytics позволяет создавать оповещения и управлять ими в Log Analytics. В этой статье приводятся сведения об API и несколько примеров выполнения различных операций.

Для поиска в службе Log Analytics используется REST API категории RESTful — к нему можно получить доступ с помощью REST API Azure Resource Manager. В этой статье вы найдете примеры, в которых доступ к API осуществляется из командной строки PowerShell с помощью ARMClient. Это средство командной строки с открытым кодом упрощает вызов API Resource Manager Azure.

Использование ARMClient и PowerShell — это один из многих вариантов, которые можно использовать для доступа к API Поиск Log Analytics. С помощью этих инструментов можно использовать API Azure Resource Manager категории RESTful для осуществления вызовов рабочих областей Log Analytics и выполнения команд поиска в них. API выводит результаты поиска в формате JSON, чтобы их можно было использовать различными способами программно.

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

В настоящее время оповещения могут создаваться только с помощью сохраненного поиска в службе Log Analytics. Дополнительные сведения см. в разделе Журнал Поиск REST API.

Расписания

Сохраненный поиск может включать одно расписание или несколько. Расписание определяет частоту выполнения поиска и интервал времени, в течение которого определяются критерии. Расписания имеют свойства, описанные в следующей таблице:

Например, рассмотрим запрос события с 15 минутами Interval и Timespan 30 минутами. В этом случае запрос будет выполняться каждые 15 минут. Оповещение будет активировано, если критерии по-прежнему разрешаются до true более чем 30-минутного интервала.

Получение расписаний

Используйте метод Get для получения всех расписаний для сохраненного поиска.

armclient get /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search  ID}/schedules?api-version=2015-03-20

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

armclient get /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Subscription ID}/schedules/{Schedule ID}?api-version=2015-03-20

Следующий пример ответа предназначен для расписания:

{
   "value": [{
      "id": "subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/sampleRG/providers/Microsoft.OperationalInsights/workspaces/MyWorkspace/savedSearches/0f0f4853-17f8-4ed1-9a03-8e888b0d16ec/schedules/a17b53ef-bd70-4ca4-9ead-83b00f2024a8",
      "etag": "W/\"datetime'2016-02-25T20%3A54%3A49.8074679Z'\"",
      "properties": {
         "Interval": 15,
         "QueryTimeSpan": 15,
         "Enabled": true,
      }
   }]
}

Создание расписания

Чтобы создать расписание, используйте метод Put с уникальным идентификатором расписания. Два расписания не могут иметь одинаковый идентификатор, даже если они связаны с разными сохраненными поисковыми запросами. При создании расписания в консоли Log Analytics для идентификатора расписания создается GUID.

$scheduleJson = "{'properties': { 'Interval': 15, 'QueryTimeSpan':15, 'Enabled':'true' } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/mynewschedule?api-version=2015-03-20 $scheduleJson

Изменение расписания

Чтобы изменить расписание, используйте метод Put с идентификатором существующего расписания для того же сохраненного поискового запроса. В следующем примере расписание отключено. Текст запроса должен содержать etag расписания.

$scheduleJson = "{'etag': 'W/\"datetime'2016-02-25T20%3A54%3A49.8074679Z'\""','properties': { 'Interval': 15, 'QueryTimeSpan':15, 'Enabled':'false' } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/mynewschedule?api-version=2015-03-20 $scheduleJson

Удаление расписаний

Чтобы удалить расписание, используйте метод Delete с идентификатором расписания.

armclient delete /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Subscription ID}/schedules/{Schedule ID}?api-version=2015-03-20

Действия

Расписание может включать несколько действий. Действие может определить один или несколько процессов для выполнения, например отправку сообщения электронной почты или запуск модуля Runbook. Действие также может определить пороговое значение, определяющее, когда результаты поиска соответствуют каким-либо критериям. Некоторые действия будут определять оба элемента так, чтобы процессы выполнялись при достижении порогового значения.

Все действия имеют свойства, описанные в следующей таблице. Различные типы оповещений имеют другие свойства, описанные в следующей таблице:

Извлечение действий

Используйте метод Get для получения всех действий для расписания.

armclient get /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search  ID}/schedules/{Schedule ID}/actions?api-version=2015-03-20

Используйте метод Get с идентификатором действия для получения конкретного действия для расписания.

armclient get /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Subscription ID}/schedules/{Schedule ID}/actions/{Action ID}?api-version=2015-03-20

Создание или изменение действий

Используйте метод Put с идентификатором действия, уникальным для расписания, чтобы создать новое действие. При создании действия в консоли Log Analytics для идентификатора действия отображается GUID.

Чтобы изменить расписание, используйте метод Put с идентификатором существующего действия для того же сохраненного поискового запроса. Текст запроса должен содержать Etag расписания.

Формат запроса для создания нового действия зависит от типа действия, поэтому эти примеры приведены в следующих разделах.

Действия удаления

Для удаления действия используйте метод Delete с идентификатором действия.

armclient delete /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Subscription ID}/schedules/{Schedule ID}/Actions/{Action ID}?api-version=2015-03-20

Действия оповещений

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

Пороговые значения

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

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

Например, рассмотрим запрос события с Interval 15 минутами, Timespan 30 минутами и Threshold более 10. В этом случае запрос будет выполняться каждые 15 минут. Оповещение будет активировано, если оно возвращает 10 событий, созданных за 30 минут.

Следующий пример ответа предназначен для действия только с :Threshold

"etag": "W/\"datetime'2016-02-25T20%3A54%3A20.1302566Z'\"",
"properties": {
   "Type": "Alert",
   "Name": "My threshold action",
   "Threshold": {
      "Operator": "gt",
      "Value": 10
   },
   "Version": 1
}

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

$thresholdJson = "{'properties': { 'Name': 'My Threshold', 'Version':'1', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 10 } } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/mythreshold?api-version=2015-03-20 $thresholdJson

Чтобы изменить действие с пороговым значением для расписания, используйте метод Put с идентификатором существующего действия. Текст запроса должен содержать Etag действия.

$thresholdJson = "{'etag': 'W/\"datetime'2016-02-25T20%3A54%3A20.1302566Z'\"','properties': { 'Name': 'My Threshold', 'Version':'1', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 10 } } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/mythreshold?api-version=2015-03-20 $thresholdJson

Статус

Log Analytics позволяет классифицировать оповещения по категориям для упрощения управления и рассмотрения. Уровни серьезности оповещений: informational, warningи critical. Эти категории сопоставляются с нормализованной шкалой серьезности оповещений Azure, как показано в следующей таблице:

Следующий пример ответа предназначен для действия только Threshold с и Severity:

"etag": "W/\"datetime'2016-02-25T20%3A54%3A20.1302566Z'\"",
"properties": {
   "Type": "Alert",
   "Name": "My threshold action",
   "Threshold": {
      "Operator": "gt",
      "Value": 10
   },
   "Severity": "critical",
   "Version": 1
}

Используйте метод Put с уникальным идентификатором действия, чтобы создать новое действие для расписания с Severityпомощью .

$thresholdWithSevJson = "{'properties': { 'Name': 'My Threshold', 'Version':'1','Severity': 'critical', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 10 } } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/mythreshold?api-version=2015-03-20 $thresholdWithSevJson

Чтобы изменить действие серьезности для расписания, используйте метод Put с идентификатором существующего действия. Текст запроса должен содержать Etag действия.

$thresholdWithSevJson = "{'etag': 'W/\"datetime'2016-02-25T20%3A54%3A20.1302566Z'\"','properties': { 'Name': 'My Threshold', 'Version':'1','Severity': 'critical', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 10 } } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/mythreshold?api-version=2015-03-20 $thresholdWithSevJson

Подавление

Оповещения о запросах на основе Log Analytics срабывают при каждом достижении или превышении порогового значения. В зависимости от логики, подразумеваемой в запросе, оповещение может возникать в течение ряда интервалов. В результате уведомления отправляются постоянно. Чтобы предотвратить такой сценарий, можно задать Suppress параметр, который предписывает Log Analytics ожидать определенное время, прежде чем уведомление будет активировано во второй раз для правила генерации оповещений.

Например, если Suppress задано значение в течение 30 минут, оповещение срабатывает в первый раз и отправляет настроенные уведомления. Затем он подождит 30 минут, прежде чем снова будет использоваться уведомление о правиле генерации оповещений. В промежуточный период правило генерации оповещений будет продолжать работать. Log Analytics подавляет только уведомление в течение указанного времени независимо от количества срабатываний правила генерации оповещений за этот период.

Свойство Suppress правила генерации оповещений поиска по журналам задается с помощью Throttling значения . Период подавления задается с помощью DurationInMinutes значения .

Следующий пример ответа предназначен для действия только со Thresholdсвойствами , Severityи Suppress .

"etag": "W/\"datetime'2016-02-25T20%3A54%3A20.1302566Z'\"",
"properties": {
   "Type": "Alert",
   "Name": "My threshold action",
   "Threshold": {
      "Operator": "gt",
      "Value": 10
   },
   "Throttling": {
   "DurationInMinutes": 30
   },
   "Severity": "critical",
   "Version": 1
}

Используйте метод Put с уникальным идентификатором действия, чтобы создать новое действие для расписания с Severityпомощью .

$AlertSuppressJson = "{'properties': { 'Name': 'My Threshold', 'Version':'1','Severity': 'critical', 'Type':'Alert', 'Throttling': { 'DurationInMinutes': 30 },'Threshold': { 'Operator': 'gt', 'Value': 10 } } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/myalert?api-version=2015-03-20 $AlertSuppressJson

Чтобы изменить действие серьезности для расписания, используйте метод Put с идентификатором существующего действия. Текст запроса должен содержать Etag действия.

$AlertSuppressJson = "{'etag': 'W/\"datetime'2016-02-25T20%3A54%3A20.1302566Z'\"','properties': { 'Name': 'My Threshold', 'Version':'1','Severity': 'critical', 'Type':'Alert', 'Throttling': { 'DurationInMinutes': 30 },'Threshold': { 'Operator': 'gt', 'Value': 10 } } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{ResourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/myalert?api-version=2015-03-20 $AlertSuppressJson

Группы действий

Все оповещения в Azure используют группу действий в качестве механизма по умолчанию для обработки действий. С помощью группы действий можно указать действия один раз, а затем связать группу действий с несколькими оповещениями в Azure без необходимости многократного объявления одних и тех же действий. Группы действий поддерживают несколько действий, таких как электронная почта, SMS, голосовой вызов, подключение ITSM, модуль runbook службы автоматизации и универсальный код ресурса (URI) веб-перехватчика.

Для пользователей, которые расширили свои оповещения в Azure, расписание теперь должно содержать сведения о группе действий, Threshold чтобы иметь возможность создать оповещение. Прежде чем создавать оповещение, необходимо определить сведения о электронной почте, URL-адреса веб-перехватчиков, сведения об автоматизации runbook и другие действия в группе действий. Вы можете создать группу действий из Azure Monitor в портал Azure или использовать API группы действий.

Чтобы связать группу действий с оповещением, укажите уникальный идентификатор azure Resource Manager группы действий в определении оповещения. В следующем примере показано использование:

"etag": "W/\"datetime'2017-12-13T10%3A52%3A21.1697364Z'\"",
"properties": {
   "Type": "Alert",
   "Name": "test-alert",
   "Description": "I need to put a description here",
   "Threshold": {
      "Operator": "gt",
      "Value": 12
   },
   "AzNsNotification": {
      "GroupIds": [
         "/subscriptions/1234a45-123d-4321-12aa-123b12a5678/resourcegroups/my-resource-group/providers/microsoft.insights/actiongroups/test-actiongroup"
      ]
   },
   "Severity": "critical",
   "Version": 1
}

Используйте метод Put с уникальным идентификатором действия, чтобы связать уже существующую группу действий с расписанием. В следующем примере показано использование:

$AzNsJson = "{'properties': { 'Name': 'test-alert', 'Version':'1', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 12 },'Severity': 'critical', 'AzNsNotification': {'GroupIds': ['subscriptions/1234a45-123d-4321-12aa-123b12a5678/resourcegroups/my-resource-group/providers/microsoft.insights/actiongroups/test-actiongroup']} } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{Resource Group Name}/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/myAzNsaction?api-version=2015-03-20 $AzNsJson

Используйте метод Put с существующим идентификатором действия, чтобы изменить группу действий, связанную с расписанием. Текст запроса должен содержать Etag действия.

$AzNsJson = "{'etag': 'datetime'2017-12-13T10%3A52%3A21.1697364Z'\"', 'properties': { 'Name': 'test-alert', 'Version':'1', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 12 },'Severity': 'critical', 'AzNsNotification': { 'GroupIds': ['subscriptions/1234a45-123d-4321-12aa-123b12a5678/resourcegroups/my-resource-group/providers/microsoft.insights/actiongroups/test-actiongroup'] } } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{Resource Group Name}/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/myAzNsaction?api-version=2015-03-20 $AzNsJson

Настройка действий

По умолчанию действия соответствуют стандартным шаблонам и формату уведомлений. Но вы можете настроить некоторые действия, даже если они управляются группами действий. В настоящее время можно настроить для EmailSubject и WebhookPayload.

Настройка EmailSubject для группы действий

По умолчанию для оповещений по электронной почте используется уведомление об <AlertName> оповещении <WorkspaceName>. Но тему можно настроить таким образом, чтобы можно было указать слова или теги, чтобы вы могли легко использовать правила фильтрации в папке "Входящие". Настраиваемые сведения о заголовке электронной почты необходимо отправить вместе с подробными сведениями ActionGroup , как показано в следующем примере:

"etag": "W/\"datetime'2017-12-13T10%3A52%3A21.1697364Z'\"",
"properties": {
   "Type": "Alert",
   "Name": "test-alert",
   "Description": "I need to put a description here",
   "Threshold": {
      "Operator": "gt",
      "Value": 12
   },
   "AzNsNotification": {
      "GroupIds": [
         "/subscriptions/1234a45-123d-4321-12aa-123b12a5678/resourcegroups/my-resource-group/providers/microsoft.insights/actiongroups/test-actiongroup"
      ],
      "CustomEmailSubject": "Azure Alert fired"
   },
   "Severity": "critical",
   "Version": 1
}

Используйте метод Put с уникальным идентификатором действия, чтобы связать существующую группу действий с настройкой расписания. В следующем примере показано использование:

$AzNsJson = "{'properties': { 'Name': 'test-alert', 'Version':'1', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 12 },'Severity': 'critical', 'AzNsNotification': {'GroupIds': ['subscriptions/1234a45-123d-4321-12aa-123b12a5678/resourcegroups/my-resource-group/providers/microsoft.insights/actiongroups/test-actiongroup'], 'CustomEmailSubject': 'Azure Alert fired'} } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{Resource Group Name}/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/myAzNsaction?api-version=2015-03-20 $AzNsJson

Используйте метод Put с существующим идентификатором действия, чтобы изменить группу действий, связанную с расписанием. Текст запроса должен содержать Etag действия.

$AzNsJson = "{'etag': 'datetime'2017-12-13T10%3A52%3A21.1697364Z'\"', 'properties': { 'Name': 'test-alert', 'Version':'1', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 12 },'Severity': 'critical', 'AzNsNotification': {'GroupIds': ['subscriptions/1234a45-123d-4321-12aa-123b12a5678/resourcegroups/my-resource-group/providers/microsoft.insights/actiongroups/test-actiongroup']}, 'CustomEmailSubject': 'Azure Alert fired' } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{Resource Group Name}/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/myAzNsaction?api-version=2015-03-20 $AzNsJson

Настройка webhookPayload для группы действий

По умолчанию веб-перехватчик, отправленный через группу действий для Log Analytics, имеет фиксированную структуру. Но вы можете настроить полезные данные JSON, используя определенные переменные, поддерживаемые в соответствии с требованиями конечной точки веб-перехватчика. Дополнительные сведения см. в разделе Действие веб-перехватчика для правил генерации оповещений поиска по журналам.

Настраиваемые сведения о веб-перехватчике должны отправляться вместе с подробными сведениями ActionGroup . Они будут применяться ко всем URI веб-перехватчиков, указанным в группе действий. В следующем примере показано использование:

"etag": "W/\"datetime'2017-12-13T10%3A52%3A21.1697364Z'\"",
"properties": {
   "Type": "Alert",
   "Name": "test-alert",
   "Description": "I need to put a description here",
   "Threshold": {
      "Operator": "gt",
      "Value": 12
   },
   "AzNsNotification": {
      "GroupIds": [
         "/subscriptions/1234a45-123d-4321-12aa-123b12a5678/resourcegroups/my-resource-group/providers/microsoft.insights/actiongroups/test-actiongroup"
      ],
   "CustomWebhookPayload": "{\"field1\":\"value1\",\"field2\":\"value2\"}",
   "CustomEmailSubject": "Azure Alert fired"
   },
   "Severity": "critical",
   "Version": 1
},

Используйте метод Put с уникальным идентификатором действия, чтобы связать существующую группу действий с настройкой расписания. В следующем примере показано использование:

$AzNsJson = "{'properties': { 'Name': 'test-alert', 'Version':'1', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 12 },'Severity': 'critical', 'AzNsNotification': {'GroupIds': ['subscriptions/1234a45-123d-4321-12aa-123b12a5678/resourcegroups/my-resource-group/providers/microsoft.insights/actiongroups/test-actiongroup'], 'CustomEmailSubject': 'Azure Alert fired','CustomWebhookPayload': '{\"field1\":\"value1\",\"field2\":\"value2\"}'} } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{Resource Group Name}/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/myAzNsaction?api-version=2015-03-20 $AzNsJson

Используйте метод Put с существующим идентификатором действия, чтобы изменить группу действий, связанную с расписанием. Текст запроса должен содержать Etag действия.

$AzNsJson = "{'etag': 'datetime'2017-12-13T10%3A52%3A21.1697364Z'\"', 'properties': { 'Name': 'test-alert', 'Version':'1', 'Type':'Alert', 'Threshold': { 'Operator': 'gt', 'Value': 12 },'Severity': 'critical', 'AzNsNotification': {'GroupIds': ['subscriptions/1234a45-123d-4321-12aa-123b12a5678/resourcegroups/my-resource-group/providers/microsoft.insights/actiongroups/test-actiongroup']}, 'CustomEmailSubject': 'Azure Alert fired','CustomWebhookPayload': '{\"field1\":\"value1\",\"field2\":\"value2\"}' } }"
armclient put /subscriptions/{Subscription ID}/resourceGroups/{Resource Group Name}/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Search ID}/schedules/{Schedule ID}/actions/myAzNsaction?api-version=2015-03-20 $AzNsJson

Дальнейшие действия

• Используйте REST API для выполнения поиска в журналах в службе Log Analytics.
• Сведения об оповещениях поиска по журналам в Azure Monitor.
• Узнайте , как создавать, изменять и администрировать правила генерации оповещений поиска по журналам в Azure Monitor.