旧版 Log Analytics 警报 REST API

项目
02/26/2024

本文介绍了如何使用旧版 API 来管理警报规则。

使用 Log Analytics 警报 REST API 可以在 Log Analytics 中创建和管理警报。本文提供有关用于执行不同操作的 API 和几个示例的详细信息。

Log Analytics 搜索 REST API 为 RESTful，可通过 Azure 资源管理器 REST API 访问。本文提供了几个示例，它们使用 ARMClient 从 PowerShell 命令行访问 API。此开源命令行工具简化了 Azure 资源管理器 API 的调用。

使用 ARMClient 和 PowerShell 是访问 Log Analytics 搜索 API 的许多选项之一。借助这些工具，可以利用 RESTful Azure 资源管理器 API 对 Log Analytics 工作区进行调用并在其中执行搜索命令。 API 以 JSON 格式输出搜索结果，使你能够以编程方式通过多种不同的方法搜索结果。

先决条件

目前，仅可以使用 Log Analytics 中已保存的搜索来创建警报。有关详细信息，请参阅日志搜索 REST API。

计划

已保存的搜索可以有一个或多个计划。计划定义搜索的运行频率以及进行条件识别的时间间隔。计划具有下表中所述的属性：

properties	描述
`Interval`	搜索的运行频率。以分钟为度量单位。
`QueryTimeSpan`	计算条件的时间间隔。必须等于或大于 `Interval`。以分钟为度量单位。
`Version`	正在使用的 API 版本。目前，此设置应始终为 `1`。

例如，假设某个事件查询的 Interval 为 15 分钟，且 Timespan 为 30 分钟。在这种情况下，该查询将每隔 15 分钟运行。如果条件在 30 分钟范围内持续求解为 true，则会触发警报。

检索计划

使用 Get 方法检索已保存搜索的所有计划。

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

结合使用 Get 方法和计划 ID 检索已保存搜索的特定计划。

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 方法和唯一计划 ID 创建一个新计划。两个计划的 ID 不能相同，即使它们与不同的已保存搜索关联，也是如此。在 Log Analytics 控制台中创建计划时，将为计划 ID 创建一个 GUID。

注意

所有已保存的搜索、计划和使用 Log Analytics API 创建的操作的名称必须小写。

$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 方法和相同已保存搜索的现有计划 ID 来修改该计划。在以下示例中，计划已禁用。请求正文必须包含该计划的 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 方法和计划 ID 删除计划。

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。一个操作还可以定义一个阈值，用于确定搜索结果在哪种情况下与某个条件匹配。某些操作将同时定义这两者，以便达到阈值时执行这些进程。

所有操作具有下表中所述的属性。不同类型的警报具有下表中所述的其他不同属性：

properties	说明
`Type`	操作的类型。目前，可能的值为 `Alert` 和 `Webhook`。
`Name`	警报的显示名称。
`Version`	正在使用的 API 版本。目前，此设置应始终为 `1`。

检索操作

使用 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 方法和计划 ID 检索计划的特定操作。

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

创建或编辑操作

结合计划的唯一操作 ID 使用 Put 方法来创建新操作。在 Log Analytics 控制台中创建操作时，GUID 作为操作 ID。

注意

所有已保存的搜索、计划和使用 Log Analytics API 创建的操作的名称必须小写。

结合使用 Put 方法和相同已保存搜索的现有操作 ID 来修改该计划。请求正文必须包含该计划的 etag。

用于创建新操作的请求格式因操作类型而异，因此以下部分提供了这些示例。

删除操作

结合使用 Delete 方法和操作 ID 可删除操作。

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

警报操作

一个计划应具有一个且只能是一个警报操作。警报操作具有下表中所述的一个或多个部分：

部分	说明	使用情况
阈值	用于确定何时运行操作的条件。	对于每个警报是必需的，无论是在警报扩展到 Azure 之前还是之后。
严重性	触发警报时用于对警报进行分类的标签。	对于每个警报是必需的，无论是在警报扩展到 Azure 之前还是之后。
取消	用于停止警报通知的选项。	对于每个警报是可选的，无论是在警报扩展到 Azure 之前还是之后。
操作组	在其中指定所需操作（例如电子邮件、短信、Webhook 和自动化 Runbook）的 Azure `ActionGroup` 的 ID。	在警报扩展到 Azure 之后是必需的。
自定义操作	修改 `ActionGroup` 中 select 操作的标准输出。	对于每个警报是可选的，可以在警报扩展到 Azure 之后使用。

阈值

一项警报操作应具有一个且只能有一个阈值。当已保存搜索的结果匹配与该搜索关联的操作中的阈值时，将运行该操作中的任何其他进程。操作也可以只包含一个阈值，以便与不包含阈值的其他类型的操作一起使用。

阈值具有下表中所述的属性：

properties	说明
`Operator`	阈值比较运算符。 gt = 大于 lt = 小于
`Value`	阈值的数值。

例如，假设某个事件查询的 Interval 为 15 分钟，Timespan 为 30 分钟，且 Threshold 大于 10。在这种情况下，该查询将每隔 15 分钟运行。如果该查询返回 30 分钟范围内创建的 10 个事件，则会触发警报。

以下示例响应适用于只有 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 方法和唯一操作 ID 可为计划创建新阈值操作。

$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 方法和现有操作 ID 可修改计划的阈值操作。请求正文必须包含操作的 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 警报的规范化严重性等级，如下表所示：

Log Analytics 严重性级别	Azure 警报严重性级别
`critical`	Sev 0
`warning`	Sev 1
`informational`	Sev 2

以下示例响应适用于只有 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
}

可以结合唯一的操作 ID 使用 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 方法与现有操作 ID 来为计划修改严重性操作。请求正文必须包含操作的 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
}

可以结合唯一的操作 ID 使用 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 方法与现有操作 ID 来为计划修改严重性操作。请求正文必须包含操作的 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 中的多个警报，而无需反复声明相同的操作。操作组支持多个操作，例如电子邮件、短信、自动化 Runbook 和 Webhook URI。

对于已将其警报扩展到 Azure 中的用户，一个计划现在应将操作组详细信息与 Threshold 一起传递，以便能够创建警报。在创建警报之前，需要先在操作组中定义电子邮件详细信息、Webhook URL、Runbook 自动化详细信息和其他操作。可以在 Azure 门户中从 Azure Monitor 创建操作组，或使用操作组 API。

若要将某个操作组关联到警报，请在警报定义中指定该操作组的唯一 Azure 资源管理器 ID。以下示例演示了用法：

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

可以组合唯一的操作 ID 使用 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

可以组合现有的操作 ID 使用 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

默认情况下，警报的电子邮件主题是：<WorkspaceName> 的警报通知 <AlertName>。但可以自定义该主题，这样就可以指定词语或标记，以便轻松在收件箱中利用筛选规则。自定义的电子邮件标头详细信息需要与 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
}

可以结合唯一的操作 ID 使用 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

可以组合现有的操作 ID 使用 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 的操作组发送的 Webhook 具有固定的结构。但你可以使用受支持的特定变量来自定义 JSON 有效负载，以满足 Webhook 终结点的要求。有关详细信息，请参阅日志搜索警报规则的 Webhook 操作。

自定义 Webhook 详细信息必须与 ActionGroup 详细信息一起发送。它们将应用于操作组中指定的所有 Webhook 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
},

可以结合唯一的操作 ID 使用 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

可以组合现有的操作 ID 使用 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

旧版 Log Analytics 警报 REST API

先决条件

计划

检索计划

创建计划

编辑日程安排

删除计划

操作

检索操作

创建或编辑操作

删除操作

警报操作

阈值

严重性

取消

操作组

自定义操作

自定义操作组的 EmailSubject

自定义操作组的 WebhookPayload

后续步骤

其他资源