API REST de Alertas do Log Analytics Herdado

Este artigo descreve como gerenciar as regras de alerta usando a API herdada.

A API REST de alerta do Log Analytics permite criar e gerenciar alertas no Log Analytics. Este artigo fornece detalhes sobre a API e vários exemplos para executar operações diferentes.

A API REST de Pesquisa do Log Analytics é RESTful e pode ser acessada por meio da API REST do Azure Resource Manager. Neste artigo, você encontrará exemplos em que a API é acessada em uma linha de comando do PowerShell usando o ARMClient. Essa ferramenta de linha de comando de software livre simplifica a invocação da API do Azure Resource Manager.

O uso do ARMClient e do PowerShell é uma das muitas opções que você pode usar para acessar a API de Pesquisa do Log Analytics. Com essas ferramentas, você pode utilizar a API do RESTful Azure Resource Manager para fazer chamadas para espaços de trabalho do Log Analytics e executar comandos de pesquisa dentro deles. A API produz resultados da pesquisa no formato JSON para que você use os resultados da pesquisa de diferentes maneiras por meio de programação.

Pré-requisitos

Atualmente, os alertas somente podem ser criados com uma pesquisa salva no Log Analytics. Para obter mais informações, confira a API REST da Pesquisa de Logs.

Agendas

Uma pesquisa salva pode ter um ou mais agendamentos. O agendamento define a frequência com que a pesquisa é executada e o intervalo de tempo em que os critérios são identificados. As propriedades dos agendamentos são descritas na tabela a seguir:

Por exemplo, considere uma consulta de evento com um Interval de 15 minutos e um Timespan de 30 minutos. Nesse caso, a consulta seria executada a cada 15 minutos. Um alerta seria disparado, se os critérios continuassem a ser resolvidos como true por um período de mais de 30 minutos.

Recuperar agendamentos

Use o método Get para recuperar todos os agendamentos de uma pesquisa salva.

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

Use o método Get com uma ID de agendamento para recuperar um agendamento específico para uma pesquisa salva.

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

A seguinte resposta de exemplo é para um agendamento:

{
   "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,
      }
   }]
}

Criar um agendamento

Use o método Put com uma ID de agendamento única para criar um novo agendamento. Dois agendamentos não podem ter a mesma ID, mesmo que estejam associados a diferentes pesquisas salvas. Quando você cria um agendamento no console do Log Analytics, um GUID é criado para o ID do agendamento.

$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

Editar um agendamento

Use o método Put com uma ID de agendamento existente para a mesma pesquisa salva para modificar esse agendamento. No exemplo a seguir, a agenda está desabilitada. O corpo da solicitação deve incluir a etag do agendamento.

$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

Excluir agendamentos

Use o método Delete com uma ID de agendamento para excluir um agendamento.

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

Ações

Um agendamento pode ter várias ações. Uma ação pode definir um ou mais processos a serem executados, como enviar um email ou iniciar um runbook. Uma ação também pode definir um limite que determina quando os resultados de uma pesquisa correspondem a alguns critérios. Algumas ações definirão ambos para que os processos sejam executados quando o limite for atingido.

As propriedades de todas as ações são descritas na tabela a seguir. Diferentes tipos de alertas têm outras propriedades diferentes, que são descritas na tabela a seguir:

Recuperar ações

Use o método Get para recuperar todas as ações de um agendamento.

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

Use o método Get com a ID de ação para recuperar uma ação específica de um agendamento.

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

Criar ou editar ações

Use o método Put com uma ID de ação que seja exclusiva para o agendamento para criar uma nova ação. Quando você cria uma ação no console do Log Analytics, um GUID é para o ID da ação.

Use o método Put com uma ID de ação existente para a mesma pesquisa salva para modificar esse agendamento. O corpo da solicitação deve incluir a Etag do agendamento.

O formato da solicitação para criar uma nova ação varia conforme o tipo de ação, veja os exemplos fornecidos nas seções a seguir.

Excluir ações

Use o método Delete com a ID de ação para excluir uma ação.

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

Ações de alerta

Um agendamento deve ter somente uma ação de Alerta. Ações de alerta têm uma ou mais das seções descritas na tabela a seguir:

Limites

Uma ação de Alerta deve ter somente um limite. Quando os resultados de pesquisas salvas coincidem com o limite de uma ação associada à pesquisa, outros processos nesta ação são executados. Uma ação também pode conter apenas um limite para ser usado com ações de outros tipos que não contêm os limites.

As propriedades dos limites são descritas na tabela a seguir:

Por exemplo, considere uma consulta de evento com um Interval de 15 minutos, um Timespan de 30 minutos e um Threshold maior que 10. Nesse caso, a consulta seria executada a cada 15 minutos. Um alerta seria disparado se retornasse dez eventos criados em um período de 30 minutos.

A resposta de exemplo a seguir é para uma ação com apenas um Threshold:

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

Use o método Put com uma ID de ação única para criar uma nova ação de limite para um agendamento.

$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

Use o método Put com uma ID de ação existente para criar uma nova ação de limite para um agendamento. O corpo da solicitação deve incluir a Etag da ação.

$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

Severidade

O Log Analytics permite classificar alertas em categorias para facilitar a triagem e o gerenciamento. Os níveis de gravidade dos alertas são informational, warning e critical. Essas categorias são mapeadas para a escala de gravidade normalizada dos Alertas do Azure, conforme mostrado na tabela a seguir:

A resposta de exemplo a seguir é para uma ação com apenas um Threshold e 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
}

Use o método Put com uma ID de ação única para criar uma nova ação para um agendamento com 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

Use o método Put com uma ID de ação existente para modificar uma ação de gravidade para um agendamento. O corpo da solicitação deve incluir a Etag da ação.

$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

Suprimir

Os alertas de consulta baseados no Log Analytics são disparados sempre que o limite for atingido ou excedido. Com base na lógica implícita na consulta, um alerta pode ser disparado para uma série de intervalos. O resultado é que as notificações são enviadas constantemente. Para evitar esse cenário, você pode definir a opção Suppress que instrui o Log Analytics a aguardar um período estipulado, antes que a notificação seja disparada pela segunda vez para o regra de alerta.

Por exemplo, se Suppress for definida para 30 minutos, o alerta será disparado pela primeira vez e enviará as notificações configuradas. Depois, aguarde 30 minutos antes que a notificação da regra de alerta seja usada novamente. No período provisório, a regra de alerta continuará em execução. Apenas a notificação é suprimida pelo Log Analytics pelo tempo especificado, independentemente de quantas vezes a regra de alerta foi disparada nesse período.

A Suppress propriedade de uma regra de alerta de pesquisa de logs é especificada usando o Throttling valor . O período de supressão é especificado usando o valor DurationInMinutes.

A resposta de exemplo a seguir é para uma ação apenas com as propriedades Threshold, Severity e 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
}

Use o método Put com uma ID de ação única para criar uma nova ação para um agendamento com 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

Use o método Put com uma ID de ação existente para modificar uma ação de gravidade para um agendamento. O corpo da solicitação deve incluir a Etag da ação.

$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

Grupos de ação

Todos os alertas no Azure, use o grupo de ações como mecanismo padrão para lidar com ações. Com um grupo de ações, você pode especificar suas ações uma vez e associar o grupo de ações a vários alertas no Azure, sem a necessidade de declarar as mesmas ações repetidamente. Os grupos de ações dão suporte a várias ações, como email, SMS, chamada de voz, conexão ITSM, runbook de automação e URI de webhook.

Para usuários que estenderam seus alertas para o Azure, agora um agendamento deve ter os detalhes do grupo de ações transmitidos juntamente com Threshold para criar um alerta. Detalhes de email, URLs de webhook, detalhes de automação de runbook e outras ações precisam ser definidos dentro de um grupo de ações, antes de você criar um alerta. Você pode criar um grupo de ações do Azure Monitor no portal do Azure ou usar a API do Grupo de Ações.

Para associar um grupo de ações a um alerta, especifique a ID exclusiva do Azure Resource Manager do grupo de ações na definição do alerta. O exemplo a seguir ilustra o uso:

"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
}

Use o método Put com uma ID de ação exclusiva para associar um grupo de ações já existente a um agendamento. O exemplo a seguir ilustra o uso:

$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

Use o método Put com uma ID de ação existente para modificar um grupo de ações associado a um agendamento. O corpo da solicitação deve incluir a Etag da ação.

$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

Personalizar ações

Por padrão, as ações seguem os modelos e o formato padrão para notificações. Mas você pode personalizar algumas ações, mesmo se elas forem controladas por grupos de ações. No momento, a personalização é possível para EmailSubject e WebhookPayload.

Personalizar EmailSubject para um grupo de ações

Por padrão, o assunto do email para alertas é: Alert Notification <AlertName> para <WorkspaceName>. Mas o assunto pode ser personalizado para que você possa especificar palavras ou marcações, para permitir que você empregue facilmente as regras de filtro na Caixa de Entrada. Os detalhes do cabeçalho de email personalizado precisam ser enviados juntamente com os detalhes do ActionGroup, como no exemplo a seguir:

"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
}

Use o método PUT com uma ID de ação exclusiva para associar o grupo de ações existente com personalização para um agendamento. O exemplo a seguir ilustra o uso:

$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

Use o método Put com uma ID de ação existente para modificar um grupo de ações associado a um agendamento. O corpo da solicitação deve incluir a Etag da ação.

$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

Personalizar o WebhookPayload para um grupo de ações

Por padrão, o webhook enviado pelo grupo de ações para o Log Analytics tem uma estrutura fixa. Mas você pode personalizar o conteúdo JSON usando variáveis específicas compatíveis para atender aos requisitos do ponto de extremidade do webhook. Para obter mais informações, consulte Ação de webhook para regras de alerta de pesquisa de log.

Os detalhes personalizados do webhook devem ser enviados juntamente com os detalhes do ActionGroup. Eles serão aplicados a todos os URIs de webhook especificados dentro do grupo de ações. O exemplo a seguir ilustra o uso:

"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
},

Use o método PUT com uma ID de ação exclusiva para associar o grupo de ações existente com personalização para um agendamento. O exemplo a seguir ilustra o uso:

$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

Use o método Put com uma ID de ação existente para modificar um grupo de ações associado a um agendamento. O corpo da solicitação deve incluir a Etag da ação.

$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

Próximas etapas

• Use a API REST para executar pesquisas de log no Log Analytics.
• Saiba mais sobre alertas de pesquisa de logs no Azure Monitor.
• Saiba como criar, editar ou gerenciar regras de alerta de pesquisa de logs no Azure Monitor.