通过

旧版 Log Analytics 警报 REST API

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

重要

如前所述，Log Analytics 警报 API 将于 2025 年 10 月 1 日停用。 必须转换到在该日期前使用计划查询规则 API 进行日志搜索警报。 在 2019 年 6 月 1 日之后创建的 Log Analytics 工作区使用 scheduledQueryRules API 来管理警报规则。 请在旧工作区中切换至当前 API，以充分利用 Azure Monitor scheduledQueryRules 的功能优势。

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。

附表

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

财产 DESCRIPTION
Interval 搜索的运行频率。 以分钟为单位测量。
QueryTimeSpan 评估条件的时间间隔。 必须等于或大于 Interval。 以分钟为单位测量。
Version 正在使用的 API 版本。 目前，此设置应始终为 1。

例如，假设事件查询的 Interval 时长为 15 分钟和 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

使用具有计划 ID 的 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,
      }
   }]
}

创建计划

使用具有唯一计划 ID 的 Put 方法创建新计划。 即使两个计划分别关联了不同的保存搜索，它们也不能具有相同的 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。 作还可以定义一个阈值，用于确定搜索结果何时与某些条件匹配。 某些动作将定义为同时满足这两个条件，以便在达到阈值时执行过程。

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

财产 DESCRIPTION
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

使用具有动作 ID 的 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

创建或编辑动作

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

注释

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

使用 Put 方法与已保存搜索中的现有操作 ID 一起，以修改该日程。 请求的正文必须包含计划的 etag。

创建新动作的请求格式因动作类型而异，因此下面提供了这些示例。

删除操作

使用带有动作 ID 的 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

警报操作

计划应具有一个警报作和一个警报作。 警报作包含下表中所述的一个或多个部分：

部分 DESCRIPTION 用法
阈值 动作运行时的标准。 扩展到 Azure 之前或之后，每个警报都需要满足要求。
严重程度 用于在触发时对警报进行分类的标签。 每个警报在扩展到 Azure 之前或之后都是必需的。
抑制 选择停止警报通知。 每个警报在扩展到 Azure 之前或之后都是可选的。
行动小组 指定需要采取行动的 Azure ActionGroup ID，例如电子邮件、短信、语音呼叫、网络钩子、自动化运行手册和 ITSM 连接器。 警报扩展到 Azure 后需要。
自定义操作 修改ActionGroup中选择动作的标准输出。 对于每个警报都是可选的，可以在警报扩展到 Azure 后使用。

阈值

警报操作应只有一个阈值。 当保存的搜索结果与该搜索关联的操作中的阈值匹配时，将运行该操作中的其他进程。 动作还可以仅包含一个阈值，以便它可以与不包含阈值的其他类型动作一起使用。

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

财产 DESCRIPTION
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
}

使用具有唯一动作 ID 的 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 方法与现有的动作 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

使用现有动作 ID 的 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 中的多个警报，而无需重复声明相同的操作。 操作组支持多种操作，例如电子邮件、短信、语音呼叫、ITSM连接、自动化运行手册和Webhook URI。

对于已将警告扩展到 Azure 的用户，计划现在应当与Threshold一起传递操作组详细信息，以便创建警告。 在创建警报之前，需要先在操作组中定义电子邮件详细信息、Webhook URL、作业计划自动化详细信息和其他动作。 可以在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
}

将 Put 方法与唯一的作 ID 配合使用，以关联已存在的计划作组。 以下示例演示了用法：

$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 方法与现有操作 ID 配合，以修改与时间表关联的操作组。 请求的正文必须包含操作的 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.

为动作组自定义 Email Subject

默认情况下，警报的电子邮件主题为警报通知<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
}

使用带有唯一操作 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

使用 Put 方法和现有的操作 ID 来修改与某个计划关联的操作组。 请求的正文必须包含作的 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 具有固定的结构。 但是，可以使用支持满足 Webhook 终结点要求的特定变量来自定义 JSON 有效负载。 有关详细信息，请参阅 日志搜索警报规则的 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

使用 Put 方法配合现有的操作 ID 来修改与计划关联的操作组。 请求的正文必须包含操作的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

后续步骤