แก้ไข

แชร์ผ่าน


Alert management API reference for on-premises management consoles

This article lists the alert management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.

alerts (Retrieve alert information)

Use this API to retrieve all or filtered alerts from an on-premises management console.

URI: /external/v1/alerts or /external/v2/alerts

GET

Query parameters:

Name Description Example Required / Optional
state Get only handled or unhandled alerts. Supported values:
- handled
- unhandled
All other values are ignored.
/api/v1/alerts?state=handled Optional
fromTime Get alerts created starting at a given time, in milliseconds from Epoch time and in UTC timezone. /api/v1/alerts?fromTime=<epoch> Optional
toTime Get alerts created only before at a given time, in milliseconds from Epoch time and in UTC timezone. /api/v1/alerts?toTime=<epoch> Optional
siteId The site on which the alert was discovered. /api/v1/alerts?siteId=1 Optional
zoneId The zone on which the alert was discovered. /api/v1/alerts?zoneId=1 Optional
sensorId The sensor on which the alert was discovered. /api/v1/alerts?sensorId=1 Optional

Note

You might not have the site and zone ID. If this is the case, first query all devices to retrieve the site and zone ID. For more information, see Integration API reference for on-premises management consoles (Public preview).

UUID (Manage alerts based on the UUID)

Use this API to take specified action on a specific alert detected by Defender for IoT.

For example, you can use this API to create a forwarding rule that forwards data to QRadar. For more information, see Integrate Qradar with Microsoft Defender for IoT.

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

PUT

Type: JSON

Query parameters:

Name Description Example Required / Optional
UUID Defines the universally unique identifier (UUID) for the alert you want to handle or handle and learn. /api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0 Required

Body parameters

Name Description Example Required / Optional
action String Either handle or handleAndLearn Required

Request example

{
    "action": "handle"
}

maintenanceWindow (Create alert exclusions)

Manages maintenance windows, under which alerts won't be sent. Use this API to define and update stop and start times, devices, or subnets that should be excluded when triggering alerts, or define and update Defender for IoT engines that should be excluded.

For example, during a maintenance window, you might want to stop alert delivery of all alerts, except for malware alerts on critical devices.

The maintenance windows that define with the maintenanceWindow API appear in the on-premises management console's Alert Exclusions window as a read-only exclusion rule, named with the following syntax: Maintenance-{token name}-{ticket ID}.

Important

This API is supported for maintenance purposes only and for a limited time period, and is not meant to be used instead of alert exclusion rules. Use this API for one-time, temporary maintenance operations only.

URI: /external/v1/maintenanceWindow

POST

Creates a new maintenance window.

Body parameters:

Name Description Example Required / Optional
ticketId String. Defines the maintenance ticket ID in the user's systems. Make sure that the ticket ID is not linked to an existing open window. 2987345p98234 Required
ttl Positive integer. Defines the TTL (time to live), which is the duration of the maintenance window, in minutes. After the defined time period is completed, the maintenance window is over and the system behaves normally again. 180 Required
engines JSON array of strings. Defines which engine to suppress alerts from during the maintenance window. Possible values:

- ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION
ANOMALY,OPERATIONAL Optional
sensorIds JSON array of strings. Defines which sensors to suppress alerts from during the maintenance window. You can get these sensor IDs from the appliances (Manage OT sensor appliances) API. 1,35,63 Optional
subnets JSON array of strings. Defines the subnets to suppress alerts from during the maintenance window. Define each subnet in a CIDR notation. 192.168.0.0/16,138.136.80.0/14,112.138.10.0/8 Optional

DELETE

Closes an existing maintenance window.

Query parameters:

Name Description Example Required / Optional
ticketId Defines the maintenance ticket ID in the user's systems. Make sure that the ticket ID is linked to an existing open window. 2987345p98234 Required

GET

Retrieve a log of all the open (POST), close (DELETE), and update (PUT) actions that were performed using this API for handling maintenance windows. T

Query parameters:

Name Description Example Required / Optional
fromDate Filters the logs from the predefined date and later. The format is YYYY-MM-DD. 2022-08-10 Optional
toDate Filters the logs up to the predefined date. The format is YYYY-MM-DD. 2022-08-10 Optional
ticketId Filters the logs related to a specific ticket ID. 9a5fe99c-d914-4bda-9332-307384fe40bf Optional
tokenName Filters the logs related to a specific token name. quarterly-sanity-window Optional

Error codes:

Code Message Description
200 OK The action was successfully completed.
204: No Content There is no data to show.
400 Bad Request The date format is incorrect.
500 Internal Server Error Any other unexpected error.

PUT

Allows you to update the maintenance window duration after you start the maintenance process by changing the ttl parameter. The new duration definition overrides the previous one.

This method is useful when you want to set a longer duration than the currently configured duration. For example, if you've originally defined 180 minutes, 90 minutes have passed, and you want to add another 30 minutes, update the ttl to 120 minute to reset the duration count.

Query parameters:

Name Description Example Required / Optional
ticketId String. Defines the maintenance ticket ID in the user's systems. 2987345p98234 Required
ttl Positive integer. Defines the duration of the window in minutes. 210 Required

pcap (Request alert PCAP)

Use this API to request a PCAP file related to an alert.

URI: /external/v2/alerts/

GET

Query parameters:

Name Description Example Required / Optional
id Alert ID from the on-premises management console /external/v2/alerts/pcap/<id> Required

Next steps

For more information, see the Defender for IoT API reference overview.