Intune-Kurs · Teil 52 von 90 · Block G: Scripting & Automatisierung
Was du in dieser Sektion lernst
- Compliance-Richtlinien über die v1.0-API anlegen, inklusive Pflichtfeld für Aktionen
- Zuweisungen an Gruppen setzen, ohne bestehende Zuweisungen zu verlieren
- Settings-Catalog-Richtlinien als JSON-Vorlage exportieren und neu anlegen
- Schreibende Skripte mit -WhatIf und Dublettenprüfung absichern
ca. 11 Min. Lesezeit · Alle Sektionen im Überblick
In Sektion 51 hast du Graph nur gelesen: Geräte, Benutzer, Berichte. Jetzt schreibst du. Du legst eine Compliance-Richtlinie per Skript an, weist sie einer Gruppe zu und baust aus einer bestehenden Settings-Catalog-Richtlinie eine wiederverwendbare Vorlage.
Das lohnt sich vor allem dann, wenn du dieselbe Konfiguration öfter brauchst: für einen zweiten Mandanten, einen neuen Standort oder eine Testkopie, bevor du in Produktion etwas änderst. Im Portal klickst du jede Einstellung neu an. Ein Skript macht es jedes Mal gleich.
Grundlagen: Was sich beim Schreiben ändert
- Berechtigungen: Zum Anlegen und Zuweisen brauchst du
DeviceManagementConfiguration.ReadWrite.All. Das nennt Microsoft Learn sowohl beim Erstellen einer Compliance-Richtlinie als auch bei der assign-Aktion. Für das Nachschlagen der Gruppe reichtGroup.Read.All. Alles Weitere steht in der Berechtigungsreferenz. - v1.0 und beta: Klassische Compliance-Richtlinien gibt es in v1.0. Settings-Catalog-Richtlinien laufen über
/deviceManagement/configurationPoliciesund sind laut Microsoft Learn nur in beta dokumentiert. Microsoft unterstützt die Intune-beta-APIs, weist aber darauf hin, dass sie sich öfter ändern. - Wirkung: Jeder POST verändert deinen Mandanten sofort. Teste deshalb in einer Testumgebung oder mit einer Pilotgruppe, nie direkt mit „Alle Geräte“.
Die Anmeldung kennst du aus Sektion 50. Neu sind die Schreibrechte und eine kleine Funktion, die dir die Objekt-ID einer Gruppe über ihren Namen liefert. Gruppen lassen sich laut Microsoft Learn standardmäßig nach displayName filtern.
Get-GruppenId bricht bewusst ab, wenn es keinen oder mehrere Treffer gibt. Lieber ein klarer Fehler als eine Richtlinie, die an der falschen Gruppe hängt.
Praxis 1: Compliance-Richtlinie per Graph anlegen
Als Beispiel legst du eine Windows-Compliance-Richtlinie an, die BitLocker, Secure Boot und eine Mindestversion verlangt. Was diese Regeln fachlich bedeuten, hast du in Sektion 19 gesehen. Das Skript prüft vorher, ob es eine Richtlinie mit diesem Namen schon gibt. So kannst du es mehrfach laufen lassen, ohne Dubletten zu erzeugen.
- @odata.type legt fest, welche Plattform du anlegst. Hier ist es
#microsoft.graph.windows10CompliancePolicy, die verfügbaren Eigenschaften stehen in der Create-Dokumentation. - scheduledActionsForRule ist laut Ressourcenbeschreibung beim Anlegen Pflicht. Ohne diesen Block lehnt Graph die Anfrage ab.
- ruleName steht laut Microsoft Learn immer auf
PasswordRequired, weil Aktionen pro Richtlinie und nicht pro Regel gelten. Der Name ist also kein Hinweis auf eine Kennwortregel. - Genau eine block-Aktion muss enthalten sein.
gracePeriodHourslegt fest, wie viele Stunden ein Gerät Zeit hat, bevor es als nicht konform gilt, erlaubt sind laut Microsoft Learn 0 bis 8760. - ConvertTo-Json -Depth 10 ist wichtig. Mit der Standardtiefe schneidet PowerShell verschachtelte Objekte ab, und Graph bekommt unvollständiges JSON.
Praxis 2: Zuweisen, ohne etwas zu verlieren
Zugewiesen wird über die Aktion assign. Du schickst eine Liste von Zuweisungen, jede mit einem Ziel. Für eine Gruppe ist das ein groupAssignmentTarget mit der groupId, für Ausnahmen gibt es das exclusionGroupAssignmentTarget.
Wichtig: Behandle assign so, als würde es die komplette Liste setzen. Die Funktion unten liest deshalb erst die bestehenden Zuweisungen, hängt die neue Gruppe an und schickt dann alles zusammen. So fliegt keine Zuweisung raus, die ein Kollege im Portal gesetzt hat.
- SupportsShouldProcess schaltet
-WhatIfund-Confirmfür deine Funktion frei. Mit-WhatIfsiehst du nur, was passieren würde. Wie das im Detail funktioniert, erklärt der Deep Dive zu ShouldProcess. - Der Aufruf am Ende läuft absichtlich mit
-WhatIf. Erst wenn die Ausgabe passt, nimmst du den Schalter weg. - ZuweisungsTyp setzt bei Compliance-Richtlinien den Typ
deviceCompliancePolicyAssignment, so wie im Beispiel von Microsoft Learn. Für Settings-Catalog-Richtlinien lässt du ihn weg. - Ist die Gruppe schon zugewiesen, macht die Funktion nichts. Auch das macht das Skript wiederholbar.
Filter für Zuweisungen, die du aus Sektion 45 kennst, hängen ebenfalls am Ziel. Wenn du sie brauchst, liest du am besten eine im Portal erstellte Zuweisung über /assignments aus und übernimmst die Felder genau so.
Praxis 3: Settings Catalog als Vorlage exportieren
Beim Settings Catalog aus Sektion 16 besteht jede Einstellung aus einer settingDefinitionId und einem passenden Wert, oft mehrfach verschachtelt. Diese IDs von Hand zu schreiben ist fehleranfällig. Der praxistaugliche Weg: Du baust die Richtlinie einmal sauber im Portal und liest sie per Graph als Vorlage aus.
- /settings ist laut Ressourcenbeschreibung die Beziehung mit allen Einstellungen der Richtlinie. Die Grunddaten wie
platformsundtechnologieskommen aus dem Richtlinienobjekt selbst. - Nur settingInstance wird gesichert. IDs und Zeitstempel braucht die neue Richtlinie nicht, die vergibt Intune selbst.
- -Depth 30 reicht auch für tief verschachtelte Einstellungen mit
children. - Die JSON-Datei kannst du in Git ablegen. Damit siehst du später genau, welche Einstellung sich wann geändert hat.
Praxis 4: Aus der Vorlage eine neue Richtlinie anlegen
Jetzt drehst du den Weg um. Das Skript liest die JSON-Datei, legt daraus über Create deviceManagementConfigurationPolicy eine neue Richtlinie an und weist sie mit der Funktion aus Praxis 2 zu.
- Dublettenprüfung zuerst: Gibt es den Namen schon, bricht das Skript ab, statt eine zweite Richtlinie mit gleichem Namen zu erzeugen.
- templateReference schickst du nur mit, wenn die Vorlage wirklich auf einem Template basiert, etwa bei Endpoint-Security-Richtlinien. Für normale Settings-Catalog-Richtlinien ist die
templateIdleer. - Kein -WhatIf beim Import: Hier wird wirklich angelegt und zugewiesen. Lass das Skript deshalb zuerst gegen eine Testgruppe laufen.
Abkürzung für 1:1-Kopien: createCopy
Willst du eine Richtlinie im selben Mandanten nur duplizieren, etwa um eine Änderung zu testen, gibt es laut Microsoft Learn die Aktion createCopy. Du übergibst nur Namen und Beschreibung. Die Kopie ist zunächst nicht zugewiesen, die Zuweisung setzt du wie oben.
Troubleshooting: Typische Fehler
400 Bad Request beim Anlegen
- Bei Compliance-Richtlinien fehlt
scheduledActionsForRuleoder es steht nicht genau eineblock-Aktion darin. - Das JSON ist abgeschnitten, weil
-Depthfehlt. Gib$jsonvor dem POST einmal aus und prüfe es. - Ein Wert passt nicht zur
settingDefinitionId. Exportiere die Einstellung aus einer funktionierenden Richtlinie, statt sie selbst zusammenzubauen.
403 Forbidden
- Du bist nur mit Read-Rechten angemeldet. Prüfe mit
(Get-MgContext).Scopes, obDeviceManagementConfiguration.ReadWrite.Alldabei ist. - Bei App-Anmeldung fehlt die Administratorzustimmung für die Anwendungsberechtigung.
Zuweisung ist nach dem Skript weg
- Du hast
assignnur mit der neuen Gruppe aufgerufen. Lies vorher immer/assignmentsaus und schick die vollständige Liste.
Eigenschaft fehlt oder heißt plötzlich anders
- Bei beta-Endpunkten kann sich das Schema ändern. Prüfe nach Fehlern zuerst die aktuelle Seite auf Microsoft Learn und exportiere die Vorlage neu.
Best Practices
- Schreibrechte nur für Skripte, die wirklich schreiben. Berichte aus Sektion 51 bleiben bei Read.
- Jedes Skript prüft vorher, ob das Objekt schon existiert. Dann kannst du es gefahrlos wiederholen.
- Schreibende Funktionen mit
SupportsShouldProcessbauen und den ersten Lauf immer mit-WhatIfmachen. - Zuweisungen immer lesen, ergänzen und komplett zurückschreiben.
- Neue Richtlinien zuerst einer Pilotgruppe zuweisen und erst nach dem Test erweitern.
- Vorlagen als JSON versionieren, so hast du gleichzeitig ein Backup deiner Konfiguration.
- Einheitliche Namen wie „WIN – Bereich – Zweck“ verwenden. Das macht die Suche per Name im Skript zuverlässig.
Fazit
Mit POST und assign wird Graph vom Berichtswerkzeug zum Werkzeug für Konfiguration. Der Trick liegt weniger im Anlegen selbst als in der Absicherung drumherum: Dubletten vermeiden, bestehende Zuweisungen behalten und zuerst mit -WhatIf testen.
Zusammenfassend für deinen Workflow:
- Mit DeviceManagementConfiguration.ReadWrite.All und Group.Read.All anmelden.
- Compliance-Richtlinien in v1.0 anlegen, immer mit genau einer block-Aktion in scheduledActionsForRule.
- Settings-Catalog-Richtlinien im Portal bauen, als JSON exportieren und daraus neue anlegen.
- Zuweisungen erst lesen, dann ergänzen und mit -WhatIf prüfen, bevor du sie wirklich setzt.
In der nächsten Sektion schaust du dir das Intune PowerShell SDK als Alternative zur direkten API an: Wann dir fertige Cmdlets die Arbeit erleichtern und wann der direkte Aufruf wie hier die bessere Wahl ist. Einen Überblick über alle Sektionen findest du auf der Seite Intune-Kurs.
Quellen
- Microsoft Learn: windows10CompliancePolicy erstellen
- Microsoft Learn: deviceCompliancePolicy-Ressourcentyp
- Microsoft Learn: deviceComplianceScheduledActionForRule
- Microsoft Learn: deviceComplianceActionItem
- Microsoft Learn: assign-Aktion für Compliance-Richtlinien
- Microsoft Learn: groupAssignmentTarget
- Microsoft Learn: exclusionGroupAssignmentTarget
- Microsoft Learn: deviceManagementConfigurationPolicy erstellen (beta)
- Microsoft Learn: deviceManagementConfigurationPolicy-Ressourcentyp (beta)
- Microsoft Learn: createCopy-Aktion (beta)
- Microsoft Learn: Gruppen auflisten
- Microsoft Learn: Berechtigungsreferenz für Microsoft Graph
- Microsoft Learn: Alles über ShouldProcess