Hello World för Microsoft 365 Defender REST API
Viktigt
Den förbättrade Microsoft 365 Defender-portalen är nu tillgänglig. Med den här nya upplevelsen kommer Defender för Endpoint, Defender för Office 365, 365 Microsoft 365 Defender och annat till Microsoft Defender for Cloud Apps. Läs om de senaste.
Gäller för:
- Microsoft 365 Defender
Viktigt
En del information gäller förinstallerad produkt som kan ha ändrats mycket innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som anges här.
Få incidenter med ett enkelt PowerShell-skript
Det bör ta 5 till 10 minuter att slutföra projektet. Den här tidsberäkningen omfattar registrering av programmet och att använda koden från PowerShell-exempelskriptet.
Registrera en app i Azure Active Directory
Logga in i Azure som en användare med rollen Global administratör.
Gå till Azure Active Directory > Appregistreringar > Ny registrering.

Välj ett namn på din ansökan i registreringsformuläret och välj sedan Registrera. Det är valfritt att välja en omdirigerings-URI. Du behöver ingen för att slutföra det här exemplet.
På programsidan väljer du API-behörigheter Lägg till > > behörighetS-API:er som min organisation använder >, skriver Microsoft Threat Protection och väljer Microsoft Threat Protection. Nu kan du komma åt Microsoft 365 Defender.
Tips
Microsoft Threat Protection är ett tidigare namn Microsoft 365 Defender namn och visas inte i den ursprungliga listan. Du måste börja skriva namnet i textrutan för att det ska visas.

- Välj Programbehörigheter > Incident.Read.All och välj Lägg till behörigheter.

Välj Bevilja administratörsmedgivande. Varje gång du lägger till en behörighet måste du välja Ge administratörsmedgivande för att den ska gälla.

Gör programmet hemligt. Välj Certifikat & , lägg till en beskrivning av hemligheten och välj sedan Lägg till.
Tips
När du har valt Lägg till väljer du kopiera det genererade hemliga värdet. Du kommer inte att kunna hämta det hemliga värdet när du har lämnat.

Spela in ditt program-ID och ditt klient-ID på ett säkert ställe. De visas under Översikt på din programsida.

Hämta en token med appen och använd token för att få åtkomst till API:t
Mer information om hur Azure Active Directory token finns i självstudiekursen för Azure AD.
Viktigt
Även om exemplet i den här demoappen uppmuntrar dig att klistra in i ditt hemliga värde för teständamål ska du aldrig hårdkoda hemligheter i ett program som körs i produktion. En tredje part kan använda din hemligt för att komma åt resurser. Du kan skydda dina apphemligheter med hjälp av Azure Key Vault. Ett praktiskt exempel på hur du kan skydda din app finns i Hantera hemligheter i dina serverappar med Azure Key Vault.
Kopiera skriptet nedan och klistra in det i din favorittextredigerare. Spara som Get-Token.ps1. Du kan även köra koden som den är i PowerShell ISE, men du bör spara den eftersom vi måste köra den igen när vi använder skriptet för hämtning av incidenter i nästa avsnitt.
Det här skriptet genererar en token och sparar den i arbetsmappen under namnet ochLatest-token.txt.
# This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory. # Paste in your tenant ID, client ID and app secret (App key). $tenantId = '' # Paste your directory (tenant) ID here $clientId = '' # Paste your application (client) ID here $appSecret = '' # # Paste your own app secret here to test, then store it in a safe place! $resourceAppIdUri = 'https://api.security.microsoft.com' $oAuthUri = "https://login.windows.net/$tenantId/oauth2/token" $authBody = [Ordered] @{ resource = $resourceAppIdUri client_id = $clientId client_secret = $appSecret grant_type = 'client_credentials' } $authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop $token = $authResponse.access_token Out-File -FilePath "./Latest-token.txt" -InputObject $token return $token
Verifiera token
Kopiera och klistra in den token du fått i JWT för att avkoda den.
JWT står för JSON Web Token. Den avkodade token innehåller ett antal JSON-formaterade objekt eller anspråk. Kontrollera att rollerna som anges i den avkodade token innehåller de önskade behörigheterna.
På följande bild kan du se en avkodad token som köpts från en app, med
Incidents.Read.AllIncidents.ReadWrite.All, ochAdvancedHunting.Read.Allbehörigheter:
Få en lista över de senaste incidenterna
Skriptet nedan använder en Get-Token.ps1 för att få åtkomst till API:et. Sedan hämtas en lista över incidenter som senast uppdaterades inom 48 timmar och listan sparas som en JSON-fil.
Viktigt
Spara skriptet i samma mapp som du sparade Get-Token.ps1.
# This script returns incidents last updated within the past 48 hours.
$token = ./Get-Token.ps1
# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents?$filter=lastUpdateTime+ge+$dateTime"
# Set the webrequest headers
$headers = @{
'Content-Type' = 'application/json'
'Accept' = 'application/json'
'Authorization' = "Bearer $token"
}
# Send the request and get the results.
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
# Extract the incidents from the results.
$incidents = ($response | ConvertFrom-Json).value | ConvertTo-Json -Depth 99
# Get a string containing the execution time. We concatenate that string to the name
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"
Out-File -FilePath $outputJsonPath -InputObject $incidents
Nu är allt klart! Du har lyckats:
- Skapat och registrerat ett program.
- Har gett det programmet behörighet att läsa aviseringar.
- Ansluten till API:t.
- Använde ett PowerShell-skript för att returnera incidenter som uppdaterats de senaste 48 timmarna.
Relaterade artiklar
- Microsoft 365 Defender API:er – översikt
- Få åtkomst Microsoft 365 Defender API:er
- Skapa ett program för åtkomst Microsoft 365 Defender utan en användare
- Skapa ett program för att Microsoft 365 Defender API:er för en användares räkning
- Skapa ett program med partner med flera klientorganisationens åtkomst Microsoft 365 Defender API:er
- Hantera hemligheter i dina serverappar med Azure-tangentvalvet
- OAuth 2.0-auktorisering för användar inloggning och API-åtkomst