Sicherheit: getRunHuntingQuery

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:

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"
        }
    ]
}