Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Namespace: microsoft.graph.security
Wichtig
Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.
Fragen Sie einen angegebenen Satz von Ereignis-, Aktivitäts- oder Entitätsdaten ab, die von Microsoft Defender XDR unterstützt werden, um proaktiv nach bestimmten Bedrohungen in Ihrer Umgebung zu suchen, indem Sie eine GET-Anforderung verwenden.
Diese Funktion ist der GET-basierte Begleiter der runHuntingQuery-Aktion . Sie akzeptiert eine Abfrage in Kusto Query Language (KQL) als URL-Parameter, führt sie für das erweiterte Suchschema aus und gibt die gleiche huntingQueryResults-Form wie die POST-Aktion zurück. Verwenden Sie diese Funktion in Szenarien, in denen keine authentifizierten POST-Anforderungen ausgegeben werden können, z. B. Power BI-Dashboards, die sich durch Web.Contentsauthentifizieren.
Erfahren Sie mehr über die Suche nach Bedrohungen über Geräte, E-Mails, Apps und Identitäten hinweg. Erfahren Sie mehr über KQL.
Informationen zur Verwendung der erweiterten Suche im Microsoft Defender-Portal finden Sie unter Proaktives Suchen nach Bedrohungen mit der erweiterten Suche in Microsoft Defender XDR.
Hinweis
Da die Abfrage in der URL übergeben wird, erhalten Aufrufer, deren Abfragezeichenfolge die Infrastruktur-URI-Grenzwerte überschreitet, eine 414 URI Too Long Antwort. Verwenden Sie die POST-Aktion runHuntingQuery für lange Abfragen.
API-Verfügbarkeit
Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.
| Weltweiter Service | US Government L4 | US Government L5 (DOD) | China, betrieben von 21Vianet |
|---|---|---|---|
| ✅ | ❌ | ❌ | ❌ |
Berechtigungen
Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.
| Berechtigungstyp | Berechtigungen mit den geringsten Berechtigungen | Berechtigungen mit höheren Berechtigungen |
|---|---|---|
| Delegiert (Geschäfts-, Schul- oder Unikonto) | ThreatHunting.Read.All | Nicht verfügbar. |
| Delegiert (persönliches Microsoft-Konto) | Nicht unterstützt | Nicht unterstützt |
| Application | ThreatHunting.Read.All | Nicht verfügbar. |
Wichtig
Der angemeldete Benutzer benötigt außerdem eine der folgenden Rollen:
- Eine Microsoft Defender XDR Unified Role-Based Access Control-Rolle (RBAC), die erweiterten Zugriff auf die Suche gewährt.
- Eine Microsoft Entra ID-Rolle , die nur die geringsten erforderlichen Berechtigungen bietet: Sicherheitsleseberechtigter, globaler Leser, Sicherheitsoperator oder Sicherheitsadministrator.
HTTP-Anforderung
GET /security/getRunHuntingQuery(query='{query}',timespan='{timespan}',workspaceId={workspaceId})
Funktionsparameter
Stellen Sie in der URL der Anforderung die folgenden Abfrageparameter mit Werten bereit.
| Parameter | Typ | Beschreibung |
|---|---|---|
| Abfrage | Zeichenfolge | Erforderlich. Die Suchabfrage in Kusto Query Language (KQL). Weitere Informationen finden Sie unter KQL-Kurzübersicht. Der Wert muss prozentcodiert sein, wenn er direkt über REST aufgerufen wird. |
| Zeitraum | Zeichenfolge | Optional. Das Zeitintervall für die Abfragen von Daten im ISO 8601-Format. Die Standardeinstellung beträgt 30 Tage. Wenn sowohl in der Abfrage als auch im Parameter timespan ein Zeitfilter angegeben ist, wird die kürzere Zeitspanne angewendet. |
| workspaceId | GUID | Optional. Die GUID eines bestimmten Log Analytics-Arbeitsbereichs, auf den abgezielt werden soll. Wenn diese Angabe weggelassen wird, verwendet der Dienst den primären Arbeitsbereich des Aufrufers. Wenn der Arbeitsbereich nicht gefunden wird oder nicht zugänglich ist, greift der Dienst auf den primären Arbeitsbereich des Aufrufers zurück. |
Die folgenden Beispiele zeigen die möglichen Formate für den timespan Parameter:
- Datum/Datum: "2026-02-01T08:00:00Z/2026-02-15T08:00:00Z" – Start- und Enddaten.
- Dauer/Enddatum: "P30D/2026-02-15T08:00:00Z" – Ein Zeitraum vor dem Enddatum.
- Start/Dauer: "2026-02-01T08:00:00Z/P30D" – Startdatum und Dauer.
- ISO8601 Dauer: "P30D" – Dauer von jetzt an rückwärts.
- Einzeldatum/-uhrzeit: "2026-02-01T08:00:00Z" – Startzeit, wobei die Endzeit standardmäßig auf die aktuelle Uhrzeit festgelegt ist.
Anforderungsheader
| Name | Beschreibung |
|---|---|
| Authorization | Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung. |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwort
Bei erfolgreicher Ausführung gibt diese Funktion einen 200 OK Antwortcode und ein microsoft.graph.security.huntingQueryResults im Antworttext zurück.
Beispiele
Beispiel 1: Ausführen einer Suchabfrage mit GET
Anforderung
Das folgende Beispiel gibt eine KQL-Abfrage an, die:
- Untersucht die AlertInfo-Tabelle im Schema für die erweiterte Suche.
- Projiziert zwei Spalten (
Timestamp,Title). - Beschränkt die Ausgabe auf zwei Datensätze.
GET https://graph.microsoft.com/beta/security/getRunHuntingQuery(query='AlertInfo%20%7C%20project%20Timestamp%2C%20Title%20%7C%20take%202',timespan='P1D')
Antwort
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.security.huntingQueryResults",
"schema": [
{
"name": "Timestamp",
"type": "DateTime"
},
{
"name": "Title",
"type": "String"
}
],
"results": [
{
"Timestamp": "2026-03-10T08:31:15.128Z",
"Title": "Suspicious PowerShell command line"
},
{
"Timestamp": "2026-03-10T08:29:41.017Z",
"Title": "Credential dumping attempt detected"
}
]
}
Beispiel 2: Ausführen einer Suchabfrage für einen bestimmten Arbeitsbereich
Anforderung
Das folgende Beispiel zeigt eine GET-Anforderung, die durch Übergeben des optionalen workspaceId-Parameters auf einen bestimmten Log Analytics-Arbeitsbereich abzielt.
GET https://graph.microsoft.com/beta/security/getRunHuntingQuery(query='AlertInfo%20%7C%20project%20Timestamp%2C%20Title%20%7C%20take%202',timespan='P1D',workspaceId=00000000-0000-0000-0000-000000000001)
Antwort
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.security.huntingQueryResults",
"schema": [
{
"name": "Timestamp",
"type": "DateTime"
},
{
"name": "Title",
"type": "String"
}
],
"results": [
{
"Timestamp": "2026-03-10T08:31:15.128Z",
"Title": "Suspicious PowerShell command line"
},
{
"Timestamp": "2026-03-10T08:29:41.017Z",
"Title": "Credential dumping attempt detected"
}
]
}