Zum Inhalt
Kaffeeundcode

Sektion 53: Graph PowerShell SDK: Die Alternative zum direkten API-Aufruf

Microsoft Graph PowerShell statt direkter API-Aufrufe: Module gezielt installieren, Cmdlets finden, Geräte abfragen und Richtlinien per Cmdlet anlegen.

Intune-Kurs · Teil 53 von 90 · Block G: Scripting & Automatisierung

Was du in dieser Sektion lernst

  • Den Unterschied zwischen altem Intune PowerShell SDK und Microsoft Graph PowerShell kennen
  • Nur die nötigen Module installieren und passende Cmdlets mit Find-MgGraphCommand finden
  • Geräte abfragen, Sync anstoßen und Richtlinien per Cmdlet anlegen
  • Entscheiden, wann ein Cmdlet und wann der direkte API-Aufruf besser passt

ca. 10 Min. Lesezeit · Alle Sektionen im Überblick

In den Sektionen 50, 51 und 52 hast du Graph fast immer direkt angesprochen: URL zusammenbauen, Invoke-MgGraphRequest aufrufen, Seiten selbst nachladen. Das funktioniert immer, ist aber nicht der einzige Weg. Das SDK bringt für fast jeden Endpunkt ein fertiges Cmdlet mit.

In dieser Sektion schaust du dir an, was diese Cmdlets dir abnehmen, wo sie dich ausbremsen und wie du beide Wege im selben Skript kombinierst.

Erst klären: Welches „Intune PowerShell SDK“?

Wenn du nach „Intune PowerShell SDK“ suchst, landest du schnell bei zwei verschiedenen Dingen:

  • Das alte Modul Microsoft.Graph.Intune mit Connect-MSGraph. Es stammt aus dem Projekt Intune-PowerShell-SDK auf GitHub. Das letzte Release in der PowerShell Gallery ist Version 6.1907.1.0 vom Juli 2019. Viele ältere Blogartikel und Skripte nutzen es noch.
  • Microsoft Graph PowerShell mit Connect-MgGraph. Laut Microsoft Learn werden die Cmdlets automatisch aus dem Graph-Schema erzeugt und regelmäßig aktualisiert. Das SDK ersetzt auch die Module AzureAD und MSOnline.

Für neue Skripte nimmst du Microsoft Graph PowerShell. Die Anmeldung mit Connect-MgGraph kennst du schon aus Sektion 50, sie gehört zum selben SDK. Triffst du in einem alten Skript auf Connect-MSGraph oder Cmdlets wie Get-IntuneManagedDevice, ist das ein Kandidat zum Umschreiben.

Installation: Nur das, was du brauchst

Laut Installationsanleitung gibt es zwei Hauptmodule: Microsoft.Graph für v1.0 und Microsoft.Graph.Beta für beta. Jedes zieht über 47 Untermodule nach. Für Intune brauchst du davon nur wenige, und Cmdlets gibt es nur für die Module, die installiert sind.

CodeKlick markiert alles · Strg+C kopiert
# Nur die Module installieren, die du für Intune wirklich brauchst
Install-Module Microsoft.Graph.Authentication   -Scope CurrentUser -Repository PSGallery
Install-Module Microsoft.Graph.DeviceManagement -Scope CurrentUser -Repository PSGallery

# Optional: beta-Cmdlets, zum Beispiel für den Settings Catalog
Install-Module Microsoft.Graph.Beta.DeviceManagement -Scope CurrentUser -Repository PSGallery

# Kontrolle: Welche Graph-Module sind in welcher Version da?
Get-InstalledModule Microsoft.Graph* | Sort-Object Name | Format-Table Name, Version
  • PowerShell 7 empfiehlt Microsoft für das SDK. Windows PowerShell 5.1 funktioniert auch, braucht aber .NET Framework 4.7.2 und eine aktuelle PowerShellGet-Version.
  • v1.0 zuerst: Microsoft rät, Skripte auf v1.0 aufzubauen. Das beta-Modul nimmst du nur, wenn es den Endpunkt in v1.0 nicht gibt, etwa beim Settings Catalog.
  • Gemeinsam aktualisieren: Halte alle Graph-Module auf derselben Version und aktualisiere sie zusammen mit Update-Module.

Praxis 1: Das passende Cmdlet finden

Die Namen folgen dem Graph-Pfad. Aus GET /deviceManagement/managedDevices wird Get-MgDeviceManagementManagedDevice, beta-Cmdlets bekommen ein Beta dazu. Raten musst du trotzdem nicht: Find-MgGraphCommand übersetzt in beide Richtungen und zeigt dir die passenden Berechtigungen.

CodeKlick markiert alles · Strg+C kopiert
# Welches Cmdlet gehört zu einem Endpunkt, den du schon kennst?
Find-MgGraphCommand -Uri '/deviceManagement/managedDevices' -Method GET -ApiVersion v1.0 |
    Format-Table Command, Module, Method, URI

# Umgekehrt: Welchen Endpunkt ruft ein Cmdlet auf und welche Rechte braucht es?
$info = Find-MgGraphCommand -Command 'Sync-MgDeviceManagementManagedDevice' -ApiVersion v1.0
$info | Format-List Command, Module, Method, URI
$info.Permissions | Format-Table Name, IsAdmin

# Berechtigungen per Stichwort suchen
Find-MgGraphPermission devicemanagementmanageddevices -PermissionType Delegated
  • Mit -Uri gibst du einen Endpunkt an, den du aus der API-Dokumentation kennst, und bekommst das Cmdlet dazu.
  • Mit -Command siehst du, welchen Endpunkt ein Cmdlet aufruft. Für Sync-MgDeviceManagementManagedDevice ist das POST …/syncDevice.
  • Find-MgGraphPermission durchsucht laut Microsoft Learn die Berechtigungen nach einem Stichwort. Die Spalte Consent zeigt, ob ein Administrator zustimmen muss.
  • Achtung bei Aktionen: Hinter Set-MgDeviceManagementDeviceCompliancePolicy steckt nicht PATCH, sondern die assign-Aktion. Bei Aktionen lohnt sich der Blick mit -Command immer.

Praxis 2: Direkter Aufruf und Cmdlet im Vergleich

Die Abfrage nach nicht konformen Geräten aus Sektion 51 sieht mit dem SDK deutlich kürzer aus. Beide Varianten liefern dieselben Geräte.

CodeKlick markiert alles · Strg+C kopiert
Connect-MgGraph -Scopes 'DeviceManagementManagedDevices.Read.All' -NoWelcome

# Variante A: direkter Aufruf mit Get-GraphAll aus Sektion 51
$filter = [uri]::EscapeDataString("complianceState eq 'noncompliant'")
$direkt = @(Get-GraphAll -Uri ("https://graph.microsoft.com/v1.0/deviceManagement/managedDevices" +
    "?`$filter=$filter&`$select=deviceName,userPrincipalName,lastSyncDateTime"))

# Variante B: dasselbe mit dem Cmdlet aus dem SDK
$sdk = @(Get-MgDeviceManagementManagedDevice -Filter "complianceState eq 'noncompliant'" `
    -Property deviceName, userPrincipalName, lastSyncDateTime -All)

"Direkt: {0} Geräte, SDK: {1} Geräte" -f $direkt.Count, $sdk.Count
$sdk | Sort-Object LastSyncDateTime |
    Format-Table DeviceName, UserPrincipalName, LastSyncDateTime
  • -All lädt laut Cmdlet-Referenz alle Seiten nach. Deine eigene Schleife über @odata.nextLink fällt weg.
  • -Property entspricht $select, -Filter entspricht $filter. Das URL-Encoding übernimmt das Cmdlet.
  • Typisierte Objekte: Die Eigenschaften heißen jetzt DeviceName statt deviceName. Da PowerShell bei Eigenschaftsnamen nicht auf Groß- und Kleinschreibung achtet, funktionieren deine bisherigen Where-Object- und Sort-Object-Aufrufe trotzdem.
  • Nur was du anforderst: Felder, die du nicht in -Property angibst, bleiben leer. Das ist kein Fehler, sondern dein $select.

Praxis 3: Geräteaktionen per Cmdlet

Aktionen wie Synchronisieren, Neustart oder Löschen laufen über eigene Endpunkte. Für syncDevice brauchst du laut Microsoft Learn die Berechtigung DeviceManagementManagedDevices.PrivilegedOperations.All. Das Lesen läuft weiter über Read.All.

CodeKlick markiert alles · Strg+C kopiert
# Lesen und Synchronisierung anstoßen: zwei getrennte Berechtigungen
Connect-MgGraph -Scopes 'DeviceManagementManagedDevices.Read.All',
                        'DeviceManagementManagedDevices.PrivilegedOperations.All' -NoWelcome

# Windows-Geräte, die sich seit 7 Tagen nicht gemeldet haben
$stichtag = (Get-Date).ToUniversalTime().AddDays(-7).ToString('yyyy-MM-ddTHH:mm:ssZ')
$alt = @(Get-MgDeviceManagementManagedDevice -Filter "lastSyncDateTime lt $stichtag" `
    -Property id, deviceName, operatingSystem, lastSyncDateTime -All |
    Where-Object OperatingSystem -eq 'Windows')

"{0} Windows-Geräte ohne Sync seit 7 Tagen" -f $alt.Count
foreach ($geraet in $alt) {
    # Erst mit -WhatIf prüfen, dann den Schalter entfernen
    Sync-MgDeviceManagementManagedDevice -ManagedDeviceId $geraet.Id -WhatIf
}
  • -WhatIf bringt Sync-MgDeviceManagementManagedDevice schon mit. Du musst also kein eigenes SupportsShouldProcess bauen wie in Sektion 52.
  • Filter einfach halten: Das Skript filtert serverseitig nur nach lastSyncDateTime und sortiert das Betriebssystem lokal mit Where-Object aus. So vermeidest du Fehler durch Filterkombinationen, die der Endpunkt nicht unterstützt.
  • Ein Sync stößt nur den Check-in an. Ist das Gerät aus oder offline, passiert erst etwas, wenn es wieder online ist.

Praxis 4: Richtlinien mit dem SDK anlegen

Beim Anlegen merkst du, dass das SDK am Ende dieselben Daten schickt wie in Sektion 52. Der Unterschied: Du übergibst die Hashtable direkt an -BodyParameter, so wie im Beispiel von Microsoft Learn. ConvertTo-Json brauchst du nicht mehr.

CodeKlick markiert alles · Strg+C kopiert
Connect-MgGraph -Scopes 'DeviceManagementConfiguration.ReadWrite.All',
                        'Group.Read.All' -NoWelcome

$name = 'WIN - Compliance - Basis (SDK)'

# Dublettenprüfung: Cmdlet statt eigener Paging-Schleife
$vorhanden = Get-MgDeviceManagementDeviceCompliancePolicy -All -Property id, displayName |
    Where-Object DisplayName -eq $name

if ($vorhanden) {
    $richtlinieId = $vorhanden[0].Id
    Write-Host "Existiert bereits: $richtlinieId"
}
else {
    # Gleicher Aufbau wie in Sektion 52, nur ohne ConvertTo-Json
    $richtlinie = @{
        '@odata.type'     = '#microsoft.graph.windows10CompliancePolicy'
        displayName       = $name
        description       = 'Per Graph PowerShell SDK erstellt'
        bitLockerEnabled  = $true
        secureBootEnabled = $true
        osMinimumVersion  = '10.0.22631'    # Beispielwert, an deine Umgebung anpassen
        scheduledActionsForRule = @(
            @{
                ruleName = 'PasswordRequired'
                scheduledActionConfigurations = @(
                    @{ actionType = 'block'; gracePeriodHours = 24 }
                )
            }
        )
    }
    $neu = New-MgDeviceManagementDeviceCompliancePolicy -BodyParameter $richtlinie
    $richtlinieId = $neu.Id
    Write-Host "Angelegt: $($neu.DisplayName) ($richtlinieId)"
}

# Zuweisen: Hinter Set-MgDeviceManagementDeviceCompliancePolicy steckt die assign-Aktion.
# Sie setzt die komplette Liste. Deshalb nur bei einer frisch angelegten Richtlinie direkt nutzen.
$gruppeId = Get-GruppenId -Name 'GRP-Intune-Pilot-Geraete'   # Hilfsfunktion aus Sektion 52
if ($neu) {
    $zuweisung = @{
        assignments = @(
            @{
                '@odata.type' = '#microsoft.graph.deviceCompliancePolicyAssignment'
                target = @{
                    '@odata.type' = '#microsoft.graph.groupAssignmentTarget'
                    groupId       = $gruppeId
                }
            }
        )
    }
    Set-MgDeviceManagementDeviceCompliancePolicy -DeviceCompliancePolicyId $richtlinieId `
        -BodyParameter $zuweisung -WhatIf
}
else {
    # Bestehende Richtlinie: Add-RichtlinienZuweisung aus Sektion 52 behält alte Zuweisungen
    Add-RichtlinienZuweisung -GruppenId $gruppeId `
        -RichtlinieUri "https://graph.microsoft.com/v1.0/deviceManagement/deviceCompliancePolicies/$richtlinieId" `
        -ZuweisungsTyp '#microsoft.graph.deviceCompliancePolicyAssignment' -WhatIf
}
  • @odata.type und scheduledActionsForRule bleiben Pflicht. Das SDK prüft dafür nichts zusätzlich, Graph lehnt fehlerhafte Anfragen genauso ab.
  • Set-MgDeviceManagementDeviceCompliancePolicy ruft laut Cmdlet-Referenz die assign-Aktion auf. Sie setzt die komplette Liste. Deshalb nutzt das Skript sie nur für eine frisch angelegte Richtlinie.
  • Bestehende Zuweisungen ergänzt du mit Add-RichtlinienZuweisung aus Sektion 52. Gemischte Skripte sind völlig normal, beide Wege nutzen dieselbe Anmeldung.

beta-Cmdlets für den Settings Catalog

Settings-Catalog-Richtlinien gibt es nur in beta, also brauchst du dafür das Modul Microsoft.Graph.Beta.DeviceManagement. Mit Get-MgBetaDeviceManagementConfigurationPolicy und Get-MgBetaDeviceManagementConfigurationPolicySetting bekommst du einen schnellen Überblick.

CodeKlick markiert alles · Strg+C kopiert
Connect-MgGraph -Scopes 'DeviceManagementConfiguration.Read.All' -NoWelcome

# Alle Settings-Catalog-Richtlinien über das beta-Modul
$richtlinien = @(Get-MgBetaDeviceManagementConfigurationPolicy -All `
    -Property id, name, platforms, technologies, settingCount)
$richtlinien | Sort-Object Name | Format-Table Name, Platforms, Technologies, SettingCount

# Einstellungen einer Richtlinie anzeigen
$edge = $richtlinien | Where-Object Name -eq 'WIN - Edge - Basis' | Select-Object -First 1
if ($edge) {
    Get-MgBetaDeviceManagementConfigurationPolicySetting `
        -DeviceManagementConfigurationPolicyId $edge.Id -All |
        ForEach-Object { $_.SettingInstance.SettingDefinitionId }
}

Wann Cmdlet, wann direkter Aufruf?

  • Cmdlet: Für Abfragen mit Paging, für Aktionen mit -WhatIf und überall, wo dir Tab-Vervollständigung und typisierte Objekte helfen.
  • Direkter Aufruf: Wenn du JSON aus einem Export 1:1 zurückschreibst, etwa Settings-Catalog-Vorlagen wie in Sektion 52, oder wenn ein Feld frisch in der API steht und das Cmdlet es noch nicht kennt.
  • Fehlersuche: Wenn ein Cmdlet sich anders verhält als erwartet, vergleichst du mit dem direkten Aufruf. Invoke-MgGraphRequest gehört zum Authentifizierungsmodul und ist immer da.

Mit -Debug siehst du, welche HTTP-Anfrage ein Cmdlet tatsächlich schickt. Das ist der schnellste Weg, um Cmdlet und API-Dokumentation zusammenzubringen.

CodeKlick markiert alles · Strg+C kopiert
# Zeigt die HTTP-Anfrage, die das Cmdlet tatsächlich schickt
Get-MgDeviceManagementManagedDevice -Top 1 -Property deviceName -Debug

# Fällt dir kein Cmdlet ein oder fehlt ein Feld: direkter Aufruf, gleiche Anmeldung
Invoke-MgGraphRequest -Method GET -OutputType PSObject `
    -Uri 'https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$top=1&$select=deviceName'

Troubleshooting: Typische Fehler

Cmdlet wird nicht erkannt

  • Das passende Modul fehlt. Mit Find-MgGraphCommand -Command <Name> siehst du in der Spalte Module, welches du installieren musst.
  • Bei Get-MgBeta…-Cmdlets fehlt das beta-Modul. Das installierst du separat.

403 Forbidden oder Zugriff verweigert

  • Prüfe mit (Get-MgContext).Scopes, ob die Berechtigung aus Find-MgGraphCommand in deiner Sitzung steckt.
  • Für Geräteaktionen reicht ReadWrite.All nicht, dafür brauchst du PrivilegedOperations.All.

Eigenschaften sind leer

  • Du hast sie nicht in -Property angefordert. Ergänze sie oder lass den Parameter zum Testen weg.

Skript aus dem Internet nutzt Connect-MSGraph

  • Das ist das alte Modul Microsoft.Graph.Intune. Übernimm die Logik, aber ersetze Anmeldung und Cmdlets durch Microsoft Graph PowerShell. Find-MgGraphCommand -Uri hilft dir, für jeden Endpunkt das neue Cmdlet zu finden.

Best Practices

  • Nur die Graph-Module installieren, die du brauchst, und alle gemeinsam aktualisieren.
  • Für Skripte zuerst v1.0-Cmdlets nehmen, beta nur dort, wo es keinen v1.0-Endpunkt gibt.
  • Berechtigungen mit Find-MgGraphCommand nachschlagen, statt pauschal breite Rechte zu vergeben.
  • Bei Abfragen immer -Property setzen. Das macht Skripte schneller und Ausgaben übersichtlicher.
  • Aktionen zuerst mit -WhatIf laufen lassen.
  • Wiederkehrende Teile in eigene Funktionen packen, wie im Artikel PowerShell Best Practices für Intune beschrieben.

Fazit

Das Graph PowerShell SDK ist keine Alternative zur API, sondern eine bequemere Schicht darüber. Für Abfragen und Aktionen sparst du dir Paging, URL-Encoding und eigene -WhatIf-Logik. Sobald du rohes JSON 1:1 schicken willst, ist der direkte Aufruf oft einfacher.

Zusammenfassend für deinen Workflow:

  • Microsoft Graph PowerShell statt des alten Moduls Microsoft.Graph.Intune nutzen.
  • Nur Microsoft.Graph.Authentication, Microsoft.Graph.DeviceManagement und bei Bedarf das beta-Modul installieren.
  • Cmdlets und Berechtigungen mit Find-MgGraphCommand finden.
  • Cmdlets und Invoke-MgGraphRequest im selben Skript kombinieren, je nachdem, was einfacher ist.

In der nächsten Sektion automatisierst du App-Zuweisungen per Graph API: Du weist Apps per Skript Gruppen zu, ohne bestehende Zuweisungen zu verlieren. Einen Überblick über alle Sektionen findest du auf der Seite Intune-Kurs.

Quellen


↑ Zur Kursübersicht: Intune-Kurs (alle Sektionen)