Kom i kontakt med oss!

Kontakta vår support!

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

Varför nyttjandedata är viktigt | Att flytta till Office 365 innebär inte bara att man flyttar en massa data till någon annans datacenter. Det är en förändring till ett modernare arbetssätt med fantastiska möjligheter kring samarbete både internt och externt, informationsspridning i ljud och bild, smarta hjälpmedel som drivs av maskininlärning och AI, intelligenta säkerhetslösningar som pratar med varandra, och mycket mer.


Att köpa en Office 365-licens till en användare innebär att den får tillgång till så mycket mer än bara E-post och ett intranät. För att driva på adoption och se till att användarna lär sig att nyttja dom nya möjligheterna på bästa sätt så måste man mäta hur de olika deltjänsterna används och hur mycket. Det är här nyttjandedata kommer in.
Microsoft har ett antal mätpunkter för varje deltjänst som man kan titta på genom rapporterna i adminportalen för Office 365/Microsoft 365. Microsoft sparar i regel data i 180 dagar. Det går också att läsa in data till Power BI med Microsoft 365 Usage Analytcs (tidigare Office 365 Adoption Content Pack).

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.

DataURL
Användares Outlook-aktivitethttps://graph.microsoft.com/v1.0/reports/getEmailActivityUserDetail(period='{period_value}’)
Användares OneDrive-aktivitethttps://graph.microsoft.com/v1.0/reports/getOneDriveActivityUserDetail(period='{period_value}’)
Användares SharePoint-aktivitethttps://graph.microsoft.com/v1.0/reports/getSharePointActivityUserDetail(period='{period_value}’)
M.fl.

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!

Skicka kommentar

E-postadressen publiceras inte. Obligatoriska fält är märkta *