Hämta och analysera Office 365 nyttjandedata med PowerShell och Microsoft Graph API

Dessa två verktyg fungerar bra om man vill komma igång med adoption och få en överblick på hur nuläget ser ut och vilka effekter t.ex. en utbildning kan ha på nyttjandet av en tjänst. Vill man ta det till nästa nivå så finns det oändliga möjligheter att skräddarsy detta genom att läsa ut nyttjandedata och hantera den i egna skript och applikationer.

Hämta Office 365-nyttjandedata med Microsoft Graph

I Office 365/Microsoft 365-adminportalen så kan man exportera ut nyttjandedata till CSV-filer. Den CSV-data man får ut i portalen är densamma som man får ut med hjälp av Microsoft Graph (Microsoft använder antagligen också Graph). Jag som lever och andas PowerShell väljer såklart att jobba mot Microsoft Graph genom PowerShell-skript men det går lika bra att göra det från en .NET-applikation eller vad som helst som kan prata med ett REST API.

Med några smarta trick i PowerShell så kan vi omvandla CSV-datat som Graph returnerar till vanliga objekt i PowerShell. Sedan kan vi jobba med objekten som vi brukar i PowerShell, dvs Format-Table, Format-List, Out-GridView eller varför inte spara ner det till en SQL-databas för att jobba mot med Power BI.

Registrera en app för Microsoft Graph i Registrera en app för Microsoft Graph i Azure AD

För att vårt PowerShell-skript ska kunna ansluta till Graph och hämta ut datat så måste vi först registrera en app i Azure AD och tilldela behörigheter att läsa nyttjandedata. Vi gör detta via Azure Portal.

Gå in under Azure Active Directory och välj sedan App registrations I menyn.

Skapa en ny app och fyll i uppgifterna enligt nedan.

Notera Application ID då vi kommer avända det i skriptet.

Öppna upp egenskaperna för den nya appen och gå in under Keys. Skapa en ny nyckel genom att skriva in en Description och spara.

Notera nyckeln som dyker upp under Value (du kan bara se den en gång så spara undan den).

Klicka sedan på Required permissions och sedan på Add.

Välj Microsoft Graph under API.

Välj Read all usage reports under Select permissions och spara.

Godkänn till sist behörigheterna som vi har lagt till med Grant permissions. Detta måste göras av en administratör så om du saknar den behörigheten i Azure AD får du be en administratör gå in och godkänna detta.

PowerShell-funktion för att ansluta till Microsoft Graph

Följande funktion är generell och används för att ansluta till Graph och sedan anropa en URL som kommer returnera ett svar.

Den funktionen kommer vi att anropa i vår Get-UsageReportData funktion nedan. Get-UsageReportData är också den funktion som tar hand om rådatat som returneras och filtrerar ut CSV-innehållet samt konverterar det till vanliga PowerShell-objekt. Notera tricket där vi gör en split på ”\?\?\?” för att klippa bort den rådata som kommer innan CSV-delen i svaret från Microsoft Graph.

function Get-GraphApi {
 param (
 [parameter(Mandatory=$true)]
 $ClientID,

[parameter(Mandatory=$true)]
 $ClientSecret,

[parameter(Mandatory=$true)]
 $TenantName,

[parameter(Mandatory=$true)]
 $Url
 )


 # Graph API URLs.
 $LoginUrl = "https://login.microsoft.com"
 $RresourceUrl = "https://graph.microsoft.com"
 
 
 # Compose REST request.
 $Body = @{ grant_type = "client_credentials"; resource = $RresourceUrl; client_id = $ClientID; client_secret = $ClientSecret }
 $OAuth = Invoke-RestMethod -Method Post -Uri $LoginUrl/$TenantName/oauth2/token?api-version=1.0 -Body $Body
 
 
 # Check if authentication is successfull.
 if ($OAuth.access_token -eq $null)
 {
 Write-Error "No Access Token"
 }
 else
 {
 # Perform REST call.
 $HeaderParams = @{ 'Authorization' = "$($OAuth.token_type) $($OAuth.access_token)" }
 $Result = (Invoke-WebRequest -UseBasicParsing -Headers $HeaderParams -Uri $Url)

# Return result.
 $Result
 }
}

function Get-UsageReportData {
 param (
 [parameter(Mandatory = $true)]
 [string]$ClientID,

[parameter(Mandatory = $true)]
 [string]$ClientSecret,

[parameter(Mandatory = $true)]
 [string]$TenantName,
 
 [parameter(Mandatory=$true)]
 $GraphUrl
 )

try {
 # Call Microsoft Graph and extract CSV content and convert data to PowerShell objects.
 ((Get-GraphApi -ClientID $ClientID -ClientSecret $ClientSecret -TenantName $TenantName -Url $GraphUrl).RawContent -split "\?\?\?")[1] | ConvertFrom-Csv
 }
 catch {
 $null
 }
}

Med dessa två funktioner på plats så kan vi enkelt hämta nyttjandedata på följande vis.

$ClientID = "e05e2a69-26b0-4496-bc47-befd55b83f16" # You registered apps App ID.
$ClientSecret = "oo87Z52Ckr7Q0AzLKqtFH567Dne4FQvWeVs2rNYG/Pw=" # Your registered apps key.
$TenantName = "yourtenant.onmicrosoft.com" # Your tenant name.
$GraphUrl = "https://graph.microsoft.com/v1.0/reports/getTeamsUserActivityUserDetail(period='D7')" # The Graph URL to retrieve data.

$UsageData = Get-UsageReportData -ClientID $ClientID -ClientSecret $ClientSecret -TenantName $TenantName -GraphUrl $GraphUrl
$UsageData

Exempel på output:

Report Refresh Date : 2018-09-21
User Principal Name : user.username@altitude365.com
Last Activity Date : 2018-09-21
Is Deleted : False
Deleted Date :
Assigned Products : WINDOWS 10 ENTERPRISE E5+ENTERPRISE MOBILITY + SECURITY E5+OFFICE 365 ENTERPRISE E5 WITHOUT AUDIO CONFERENCING
Team Chat Message Count : 4
Private Chat Message Count : 333
Call Count : 3
Meeting Count : 1
Has Other Action : Yes
Report Period : 7

I det här fallet så hämtar vi ut all Teams-användardata från den senaste månaden. Mer information om just den här Graph URLen finns här:

https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/reportroot_getteamsuseractivityuserdetail

Samtliga nyttjandedatarapporter som man kan hämta finns i menyn på den här sidan.

https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/report

Här följer också några exempel på rapporter man kan hämta data ifrån.

Hur Altitude 365 använder detta

Även om dom inbyggda rapporterna är kraftfulla så kan vi genom att hämta nyttjandedatat vrida och vända på den ytterligare. Vi på Altitude 365 använder nyttjandedatat tillsammans med Power BI för att hjälpa våra kunder med adoption, licensoptimering, uppstädning, säkerhet och automatiska förbättringsförslag som inte hade varit möjligt utan att jobba mot Microsoft Graph. Kunden får fantastiska insikter i hur deras organisation använder Office 365.

Om ni har intresse av att bygga lösningar mot Microsoft Graph eller om ni vill ha hjälp med adoption, licensoptimering, mm så kan Altitude 365 hjälpa till. Kontakta oss gärna så berättar vi mer!

Relaterat inlägg: Hur vi jobbar med Office 365