API-Referenz zur Warnungsverwaltung für lokale Verwaltungskonsolen
Artikel
In diesem Artikel werden die Warnungsverwaltungs-REST-APIs aufgeführt, die für lokale Microsoft Defender for IoT-Verwaltungskonsolen unterstützt werden.
alerts (Warnungsinformationen abrufen)
Mit dieser API können Sie alle oder gefilterte Warnungen von einer lokalen Verwaltungskonsole abrufen.
Definiert den Universally Unique Identifier (UUID, universell eindeutiger Bezeichner) für die Warnung, die Sie behandeln oder für die Sie einen Bearbeitungs- und Lernvorgang durchführen möchten.
Wenn die Anforderung erfolgreich ist, wird die Eigenschaft „content“ angezeigt. Andernfalls wird die Eigenschaft „error“ angezeigt.
Mögliche Werte des Felds „content“:
Statuscode
`Message`
BESCHREIBUNG
200
Die Aktualisierungsanforderung der Warnung wurde erfolgreich abgeschlossen.
Die Aktualisierungsanforderung wurde erfolgreich abgeschlossen. Keine Kommentare.
200
Die Warnung wurde bereits bearbeitet (handle).
Die Warnung wurde bereits bearbeitet, als eine „handle“-Anforderung für die Warnung empfangen wurde. Die Warnung bleibt im Status handled.
200
Für die Warnung wurde bereits ein Bearbeitungs- und Lernvorgang durchgeführt (handleAndLearn).
Für die Warnung wurde bereits ein Bearbeitungs- und Lernvorgang durchgeführt, als eine handleAndLearn-Anforderung empfangen wurde. Die Warnung bleibt im Status handledAndLearn.
200
Die Warnung wurde bereits bearbeitet (handled). Für die Warnung wurde bereits ein Bearbeitungs- und Lernvorgang (handleAndLearn) ausgeführt.
Die Warnung wurde bereits bearbeitet, als eine handleAndLearn-Anforderung empfangen wurde. Die Warnung erhält den Status handleAndLearn.
200
Für die Warnung wurde bereits ein Bearbeitungs- und Lernvorgang durchgeführt (handleAndLearn). Die Bearbeitungsanforderung wurde ignoriert.
Die Warnung befand sich bereits im Status handleAndLearn, als eine Anforderung zum Bearbeiten der Warnung empfangen wurde. Die Warnung bleibt im Status handleAndLearn.
500
Ungültige Aktion.
Die gesendete Aktion ist keine gültige Aktion, die für die Warnung ausgeführt werden kann.
500
Unerwarteter Fehler.
Ein unerwarteter Fehler ist aufgetreten. Wenden Sie sich an den technischen Support, um das Problem zu beheben.
500
Die Anforderung konnte nicht ausgeführt werden, da für diese UUID keine Warnung gefunden wurde.
Die angegebene Warnungs-UUID wurde im System nicht gefunden.
Dient zum Verwalten von Wartungsfenstern, in denen keine Warnungen gesendet werden. Definieren und aktualisieren Sie mit dieser API End- und Startzeiten, Geräte oder Subnetze, die beim Auslösen von Warnungen ausgeschlossen werden sollen, oder Defender for IoT-Engines, die nicht einbezogen werden sollen.
Während eines Wartungsfensters können Sie beispielsweise die Übermittlung aller Warnungen mit Ausnahme von Malwarewarnungen auf wichtigen Geräten unterbrechen.
Die mit der maintenanceWindow-API definierten Wartungsfenster werden im Fenster „Warnungsausschlüsse“ der lokalen Verwaltungskonsole als schreibgeschützte Ausschlussregel angezeigt und mit der folgenden Syntax benannt: Maintenance-{token name}-{ticket ID}.
Wichtig
Diese API wird nur für Wartungszwecke und nur für eine begrenzte Zeit unterstützt und sollte nicht anstelle von Warnungsausschlussregeln verwendet werden. Verwenden Sie diese API nur für einmalige, zeitlich begrenzte Wartungsvorgänge.
URI: /external/v1/maintenanceWindow
POST
Dienst zum Erstellen eines neuen Wartungsfensters.
Eine Zeichenfolge. Definiert die ID des Wartungstickets in den Systemen des Benutzers. Stellen Sie sicher, dass die Ticket-ID nicht mit einem vorhandenen geöffneten Wartungsfenster verknüpft ist.
2987345p98234
Erforderlich
ttl
Positive ganze Zahl. Definiert die Gültigkeitsdauer (Time to Live, TTL), welche die Dauer des Wartungsfensters in Minuten angibt. Nach dem definierten Zeitraum endet das Wartungsfenster, und das System verhält sich wieder normal.
180
Erforderlich
engines
JSON-Array mit Zeichenfolgen. Definiert die Engine, deren Warnungen während des Wartungsfensters unterdrückt werden sollen. Mögliche Werte:
JSON-Array mit Zeichenfolgen. Definiert die Sensoren, deren Warnungen während des Wartungsfensters unterdrückt werden sollen. Sie können die Sensor-IDs mit der API appliances (OT-Sensor-Appliances verwalten) abrufen.
1,35,63
Optional
Subnetze
JSON-Array mit Zeichenfolgen. Definiert die Subnetze, deren Warnungen während des Wartungsfensters unterdrückt werden sollen. Definieren Sie jedes Subnetz in einer CIDR-Notation.
192.168.0.0/16,138.136.80.0/14,112.138.10.0/8
Optional
Statuscode
`Message`
BESCHREIBUNG
201 (Erstellt)
-
Die Aktion wurde erfolgreich abgeschlossen.
400 (Ungültige Anforderung)
Keine TicketId
In der API-Anforderung fehlte ein ticketId-Wert.
400 (Ungültige Anforderung)
Ungültige TTL
Die API-Anforderung enthielt einen nicht positiven oder nicht numerischen TTL-Wert.
400 (Ungültige Anforderung)
Anforderung konnte nicht analysiert werden.
Beim Analysieren des Anforderungstexts ist ein Problem aufgetreten, z. B. falsche Parameter oder ungültige Werte.
400 (Ungültige Anforderung)
Ein Wartungsfenster mit denselben Parametern ist bereits vorhanden.
Wird angezeigt, wenn bereits ein Wartungsfenster mit den gleichen Details vorhanden ist.
404 (Nicht gefunden)
Unbekannte Sensor-ID
Einer der in der Anforderung aufgeführten Sensoren ist nicht vorhanden.
409 (Konflikt)
Die Ticket-ID verfügt bereits über ein geöffnetes Fenster.
Die Ticket-ID ist mit einem anderen geöffneten Wartungsfenster verknüpft.
Definiert die ID des Wartungstickets in den Systemen des Benutzers. Stellen Sie sicher, dass die Ticket-ID mit einem vorhandenen geöffneten Wartungsfenster verknüpft ist.
2987345p98234
Erforderlich
Fehlercodes:
Code
`Message`
BESCHREIBUNG
200 (OK)
-
Die Aktion wurde erfolgreich abgeschlossen.
400 (Ungültige Anforderung)
Keine TicketId
Der ticketId-Parameter fehlt in der Anforderung.
404 (Not Found):
Wartungsfenster nicht gefunden.
Die Ticket-ID ist nicht mit einem geöffneten Wartungsfenster verknüpft.
Dient zum Abrufen eines Protokolls aller Aktionen zum Öffnen (POST), Schließen (DELETE) und Aktualisieren (PUT) ab, die mithilfe dieser API für die Behandlung von Wartungsfenstern ausgeführt wurden. T
Filtert die Protokolle aufsteigend ab dem vordefinierten Datum. Das Format ist YYYY-MM-DD.
2022-08-10
Optional
toDate
Filtert die Protokolle bis zum vordefinierten Datum. Das Format ist YYYY-MM-DD.
2022-08-10
Optional
ticketId
Filtert die Protokolle, die mit einer bestimmten Ticket-ID verknüpft sind.
9a5fe99c-d914-4bda-9332-307384fe40bf
Optional
tokenName
Filtert die Protokolle, die mit einem bestimmten Tokennamen verknüpft sind.
quarterly-sanity-window
Optional
Fehlercodes:
Code
`Message`
BESCHREIBUNG
200
OK
Die Aktion wurde erfolgreich abgeschlossen.
204:
Kein Inhalt
Es sind keine anzuzeigenden Daten vorhanden.
400
Ungültige Anforderung
Das Datumsformat ist falsch.
500
Interner Serverfehler
Sonstiger unerwarteter Fehler.
Typ: JSON
Array von JSON-Objekten, die Vorgänge im Wartungsfenster darstellen.
Antwortstruktur:
Name
type
Nullwerte zulassend/Keine Nullwerte zulassend
Liste der Werte
id
Lange ganze Zahl
Lässt keine NULL-Werte zu
Eine interne ID für das aktuelle Protokoll
dateTime
String
Lässt keine NULL-Werte zu
Die Zeit, zu der die Aktivität aufgetreten ist, z. B.: 2022-04-23T18:25:43.511Z
ticketId
String
Lässt keine NULL-Werte zu
Die Wartungsfenster-ID. Beispiel: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName
Zeichenfolge
Lässt keine NULL-Werte zu
Der Tokenname des Wartungsfenstertokens. Beispiel: quarterly-sanity-window
engines
Array von Zeichenfolgen
Nullwerte zulässig
Die Engines, für die das Wartungsfenster gilt (wie bei der Erstellung des Wartungsfensters angegeben): Protocol Violation, Policy Violation, Malware, Anomaly oder Operational
sensorIds
Zeichenfolgenarray
Nullwerte zulässig
Die Sensoren, für die das Wartungsfenster gilt (wie bei der Erstellung des Wartungsfensters angegeben)
Subnetze
Zeichenfolgenarray
Nullwerte zulässig
Die Subnetze, für die das Wartungsfenster gilt (wie bei der Erstellung des Wartungsfensters angegeben)
ttl
Numeric
Nullwerte zulässig
Der TTL-Wert des Wartungsfensters (wie bei der Erstellung oder Aktualisierung des Wartungsfensters angegeben)
Ermöglicht es Ihnen, durch Ändern des ttl-Parameters die Dauer des Wartungsfensters zu aktualisieren, nachdem Sie den Wartungsvorgang gestartet haben. Die neue Definition der Dauer überschreibt die vorherige Definition.
Diese Methode ist hilfreich, wenn Sie anstelle der aktuell konfigurierten Dauer eine längere Zeitspanne festlegen möchten. Wenn Sie beispielsweise ursprünglich 180 Minuten definiert haben, 90 Minuten verstrichen sind und Sie weitere 30 Minuten hinzufügen möchten, ändern Sie den ttl-Wert in 120 Minuten, um die Dauer zurückzusetzen.