Delen via


Naslaginformatie over de API voor waarschuwingsbeheer voor on-premises beheerconsoles

Dit artikel bevat de REST API's voor waarschuwingsbeheer die worden ondersteund voor Microsoft Defender voor on-premises IoT-beheerconsoles.

waarschuwingen (waarschuwingsgegevens ophalen)

Gebruik deze API om alle of gefilterde waarschuwingen op te halen uit een on-premises beheerconsole.

URI: /external/v1/alerts of /external/v2/alerts

GET

Queryparameters:

Naam Beschrijving Voorbeeld Vereist/optioneel
Staat Alleen verwerkte of onverwerkte waarschuwingen ophalen. Ondersteunde waarden:
- handled
- unhandled
Alle andere waarden worden genegeerd.
/api/v1/alerts?state=handled Optioneel
fromTime Ontvang waarschuwingen die zijn gemaakt vanaf een bepaald tijdstip, in milliseconden vanaf Epoch-tijd en in UTC-tijdzone. /api/v1/alerts?fromTime=<epoch> Optioneel
toTime Ontvang waarschuwingen die alleen eerder op een bepaald tijdstip zijn gemaakt, in milliseconden vanaf Epoch-tijd en in UTC-tijdzone. /api/v1/alerts?toTime=<epoch> Optioneel
siteId De site waarop de waarschuwing is gedetecteerd. /api/v1/alerts?siteId=1 Optioneel
Zone De zone waarop de waarschuwing is gedetecteerd. /api/v1/alerts?zoneId=1 Optioneel
sensorId De sensor waarop de waarschuwing is gedetecteerd. /api/v1/alerts?sensorId=1 Optioneel

Notitie

Mogelijk hebt u de site- en zone-id niet. Als dit het geval is, voert u eerst een query uit op alle apparaten om de site- en zone-id op te halen. Zie Naslaginformatie over integratie-API's voor on-premises beheerconsoles (openbare preview) voor meer informatie.

UUID (Waarschuwingen beheren op basis van de UUID)

Gebruik deze API om opgegeven actie uit te voeren op een specifieke waarschuwing die is gedetecteerd door Defender for IoT.

U kunt deze API bijvoorbeeld gebruiken om een doorstuurregel te maken waarmee gegevens worden doorgestuurd naar QRadar. Zie Qradar integreren met Microsoft Defender voor IoT voor meer informatie.

URI: /external/v1/alerts/<UUID>

PUT

Type: JSON

Queryparameters:

Naam Beschrijving Voorbeeld Vereist/optioneel
UUID Hiermee definieert u de universeel unieke id (UUID) voor de waarschuwing die u wilt verwerken of verwerken en leren. /api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0 Vereist

Hoofdtekstparameters

Naam Beschrijving Voorbeeld Vereist/optioneel
action Tekenreeks Of handlehandleAndLearn Vereist

Voorbeeld van aanvraag

{
    "action": "handle"
}

maintenanceWindow (uitsluitingen voor waarschuwingen maken)

Beheert onderhoudsvensters, waaronder geen waarschuwingen worden verzonden. Gebruik deze API voor het definiƫren en bijwerken van stop- en starttijden, apparaten of subnetten die moeten worden uitgesloten bij het activeren van waarschuwingen, of het definiƫren en bijwerken van Defender for IoT-engines die moeten worden uitgesloten.

Tijdens een onderhoudsvenster wilt u bijvoorbeeld de levering van waarschuwingen voor alle waarschuwingen stoppen, met uitzondering van malwarewaarschuwingen op kritieke apparaten.

De onderhoudsvensters die met de maintenanceWindow API worden gedefinieerd, worden in het venster Uitsluitingen van waarschuwingen van de on-premises beheerconsole weergegeven als een uitsluitingsregel met het kenmerk Alleen-lezen, met de naam met de volgende syntaxis: Maintenance-{token name}-{ticket ID}.

Belangrijk

Deze API wordt alleen ondersteund voor onderhoudsdoeleinden en voor een beperkte periode en is niet bedoeld om te worden gebruikt in plaats van regels voor het uitsluiten van waarschuwingen. Gebruik deze API alleen voor eenmalige, tijdelijke onderhoudsbewerkingen.

URI: /external/v1/maintenanceWindow

POST

Hiermee maakt u een nieuw onderhoudsvenster.

Hoofdtekstparameters:

Naam Beschrijving Voorbeeld Vereist/optioneel
ticketId Tekenreeks. Definieert de onderhoudsticket-id in de systemen van de gebruiker. Zorg ervoor dat de ticket-id niet is gekoppeld aan een bestaand geopend venster. 2987345p98234 Vereist
Ttl Positief geheel getal. Definieert de TTL (time to live), de duur van het onderhoudsvenster, in minuten. Nadat de gedefinieerde periode is voltooid, is het onderhoudsvenster voorbij en gedraagt het systeem zich weer normaal. 180 Vereist
Engines JSON-matrix met tekenreeksen. Definieert van welke engine waarschuwingen tijdens het onderhoudsvenster moeten worden onderdrukt. Mogelijke waarden:

- ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION
ANOMALY,OPERATIONAL Optioneel
sensorIds JSON-matrix met tekenreeksen. Hiermee definieert u vanaf welke sensoren waarschuwingen tijdens het onderhoudsvenster moeten worden onderdrukt. U kunt deze sensor-id's ophalen uit de API voor apparaten (OT-sensorapparaten beheren). 1,35,63 Optioneel
Subnetten JSON-matrix met tekenreeksen. Definieert de subnetten voor het onderdrukken van waarschuwingen tijdens het onderhoudsvenster. Definieer elk subnet in een CIDR-notatie. 192.168.0.0/16,138.136.80.0/14,112.138.10.0/8 Optioneel

DELETE

Sluit een bestaand onderhoudsvenster.

Queryparameters:

Naam Beschrijving Voorbeeld Vereist/optioneel
ticketId Definieert de onderhoudsticket-id in de systemen van de gebruiker. Zorg ervoor dat de ticket-id is gekoppeld aan een bestaand geopend venster. 2987345p98234 Vereist

GET

Haal een logboek op van alle acties voor openen (POST), sluiten (DELETE) en bijwerken (PUT) die met deze API zijn uitgevoerd voor het afhandelen van onderhoudsvensters. T

Queryparameters:

Naam Beschrijving Voorbeeld Vereist/optioneel
Fromdate Filtert de logboeken vanaf de vooraf gedefinieerde datum en hoger. De indeling is YYYY-MM-DD. 2022-08-10 Optioneel
Todate Filtert de logboeken tot de vooraf gedefinieerde datum. De indeling is YYYY-MM-DD. 2022-08-10 Optioneel
ticketId Filtert de logboeken met betrekking tot een specifieke ticket-id. 9a5fe99c-d914-4bda-9332-307384fe40bf Optioneel
tokenName Filtert de logboeken met betrekking tot een specifieke tokennaam. kwartaal-sanity-venster Optioneel

Foutcodes:

Code Bericht Beschrijving
200 OK De actie is voltooid.
204: Geen inhoud Er zijn geen gegevens om weer te geven.
400 Onjuiste aanvraag De datumnotatie is onjuist.
500 Interne serverfout Eventuele andere onverwachte fouten.

PUT

Hiermee kunt u de duur van het onderhoudsvenster bijwerken nadat u het onderhoudsproces hebt gestart door de ttl parameter te wijzigen. De nieuwe duurdefinitie overschrijft de vorige definitie.

Deze methode is handig als u een langere duur wilt instellen dan de momenteel geconfigureerde duur. Als u bijvoorbeeld oorspronkelijk 180 minuten hebt gedefinieerd, er 90 minuten zijn verstreken en u nog eens 30 minuten wilt toevoegen, werkt u de ttl naar minuut bij om het aantal duur opnieuw in te 120 stellen.

Queryparameters:

Naam Beschrijving Voorbeeld Vereist/optioneel
ticketId Tekenreeks. Definieert de onderhoudsticket-id in de systemen van de gebruiker. 2987345p98234 Vereist
Ttl Positief geheel getal. Hiermee definieert u de duur van het venster in minuten. 210 Vereist

pcap (PCAP-waarschuwing aanvragen)

Gebruik deze API om een PCAP-bestand aan te vragen dat is gerelateerd aan een waarschuwing.

URI: /external/v2/alerts/

GET

Queryparameters:

Naam Beschrijving Voorbeeld Vereist/optioneel
id Waarschuwings-id van de on-premises beheerconsole /external/v2/alerts/pcap/<id> Vereist

Volgende stappen

Zie het overzicht naslaginformatie over Defender for IoT API voor meer informatie.