Zum Inhalt
Kaffeeundcode

Sektion 54: Graph API: App-Zuweisungen automatisieren

Intune-Apps per Graph API Gruppen zuweisen, ohne bestehende Zuweisungen zu verlieren: Intents, Ziele, die assign-Aktion und Win32-Einstellungen.

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

Was du in dieser Sektion lernst

  • Die passende App im Tenant finden und nur veröffentlichte Apps zuweisen
  • Bestehende Zuweisungen lesen, bevor du etwas änderst
  • Intent und Zieltyp korrekt setzen, inklusive Ausschlussgruppen
  • Die assign-Aktion von einer einzelnen neuen Zuweisung unterscheiden und nichts überschreiben

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

In Sektion 52 hast du Richtlinien per Graph zugewiesen und gelernt, dass die assign-Aktion die komplette Liste erwartet. Denselben Gedanken brauchst du jetzt für Apps. Die Installationsabsichten required, available und uninstall kennst du schon aus Sektion 36; hier setzt du sie per Skript.

In Sektion 53 ist Microsoft Graph PowerShell dazugekommen. In dieser Sektion bleibt der direkte API-Aufruf der Leitfaden, und am Ende siehst du denselben Weg mit den passenden Cmdlets.

Berechtigungen und Anmeldung

Zum Lesen von Apps und Zuweisungen reicht laut Microsoft Learn unter anderem DeviceManagementApps.Read.All. Zum Anlegen oder Ändern brauchst du DeviceManagementApps.ReadWrite.All oder DeviceManagementConfiguration.ReadWrite.All, so steht es bei der assign-Aktion und beim Anlegen einer Zuweisung. Für die Suche nach Entra-Gruppen bleibt Group.Read.All wie in Sektion 52.

CodeKlick markiert alles · Strg+C kopiert
# App-Zuweisungen schreiben, Gruppen nur lesen
Connect-MgGraph -Scopes 'DeviceManagementApps.ReadWrite.All',
                        'Group.Read.All' -NoWelcome

function Get-GruppenId {
    param([Parameter(Mandatory)][string]$Name)
    $filter = [uri]::EscapeDataString("displayName eq '$Name'")
    $treffer = @((Invoke-MgGraphRequest -Method GET -OutputType PSObject `
        -Uri "https://graph.microsoft.com/v1.0/groups?`$filter=$filter&`$select=id,displayName").value)
    if ($treffer.Count -ne 1) { throw "Gruppe '$Name' nicht eindeutig gefunden ($($treffer.Count) Treffer)." }
    $treffer[0].id
}

function Get-GraphAll {
    param([Parameter(Mandatory)][string]$Uri)
    $ergebnis = [System.Collections.Generic.List[object]]::new()
    while ($Uri) {
        $antwort = Invoke-MgGraphRequest -Method GET -Uri $Uri -OutputType PSObject
        foreach ($eintrag in $antwort.value) { $ergebnis.Add($eintrag) }
        $Uri = $antwort.'@odata.nextLink'
    }
    $ergebnis
}
  • Get-GruppenId und Get-GraphAll nimmst du unverändert aus Sektion 52 mit. So vermeidest du, dass eine Gruppe oder eine lange Appliste nur teilweise geladen wird.
  • Die Anmeldung mit Connect-MgGraph kennst du seit Sektion 50. Prüfe danach mit (Get-MgContext).Scopes, ob die Rechte in der Sitzung stecken.

Praxis 1: Die App finden

Alle mobilen Apps liegen unter GET /deviceAppManagement/mobileApps, dokumentiert im List-Endpunkt. Laut der mobileApp-Referenz ist das Auflisten mit $expand=assignments veraltet. Du holst zuerst die App-Liste ohne Zuweisungen und liest die Zuweisungen danach gezielt für eine einzelne App.

Dieselbe Referenz sagt klar: Die App kann nicht zugewiesen werden, solange sie nicht veröffentlicht wurde. Der Status steht in publishingState, mögliche Werte sind notPublished, processing und published.

CodeKlick markiert alles · Strg+C kopiert
# Beispiel-App in einem Tenant wie contoso.com; Namen bei Bedarf anpassen
$appName = 'Contoso HR-App'
$uri = 'https://graph.microsoft.com/v1.0/deviceAppManagement/mobileApps?$select=id,displayName,publisher,publishingState'
$apps = Get-GraphAll -Uri $uri | Where-Object { $_.displayName -eq $appName }

if ($apps.Count -ne 1) {
    throw "App '$appName' nicht eindeutig gefunden ($($apps.Count) Treffer)."
}
$app = $apps[0]
if ($app.publishingState -ne 'published') {
    throw "App '$appName' ist nicht veröffentlicht (Status: $($app.publishingState))."
}

$app | Select-Object id, displayName, publisher, publishingState
  • Der Anzeigename Contoso HR-App ist ein Beispiel, so wie du in einem Tenant von contoso.com arbeiten würdest. Ersetze ihn durch den exakten Namen in deinem Portal.
  • Lokal filtern: Die Liste kann sehr lang sein, weil Intune darin viele App-Typen führt. Das Skript lädt mit $select nur die nötigen Felder und filtert den Namen danach mit Where-Object. So bleibst du unabhängig davon, welche $filter-Varianten der Endpunkt gerade unterstützt.
  • Gibt es keinen oder mehrere Treffer, bricht das Skript ab. Eine Zuweisung auf die falsche App ist teurer als eine klare Fehlermeldung.

Praxis 2: Bestehende Zuweisungen lesen

Die Zuweisungen einer App holst du mit GET /deviceAppManagement/mobileApps/{id}/assignments. Das ist der Listen-Endpunkt für mobileAppAssignment. Jeder Eintrag hat laut Ressourcenreferenz mindestens intent, target und optional settings.

CodeKlick markiert alles · Strg+C kopiert
$zuweisungen = @((Invoke-MgGraphRequest -Method GET -OutputType PSObject `
    -Uri "https://graph.microsoft.com/v1.0/deviceAppManagement/mobileApps/$($app.id)/assignments").value)

$zuweisungen | ForEach-Object {
    [pscustomobject]@{
        Id        = $_.id
        Intent    = $_.intent
        Zieltyp   = $_.target.'@odata.type'
        GruppenId = $_.target.groupId
    }
}

Schau dir die Ausgabe an, bevor du schreibst. So siehst du, welche Gruppen schon zugewiesen sind, welcher Intent gilt und ob Ausschlüsse existieren. Diese Liste ist die Grundlage für jeden sicheren Schreibzugriff.

Intent und Ziele

Die Installationsabsicht intent kennt laut Microsoft die Werte available, required, uninstall und availableWithoutEnrollment. Die ersten drei entsprechen dem, was du in Sektion 36 im Portal gesetzt hast: verfügbar im Unternehmensportal, erforderliche Installation oder Deinstallation.

Das Ziel steckt in target. In v1.0 sind das vor allem diese Typen:

Assignment Filter, die du aus Sektion 45 kennst, hängst du in diesem Kurs noch nicht an das Ziel. Die Filtereigenschaften am Basis-Zieltyp dokumentiert Microsoft derzeit in der beta-Referenz; die Skripte hier bleiben bei Graph v1.0.

Zwei Wege: Eine Zuweisung anlegen oder die komplette Liste setzen

Zum Schreiben gibt es zwei Endpunkte, und du solltest sie nicht verwechseln:

  • POST …/assignments erstellt eine einzelne neue mobileAppAssignment. Die Antwort ist 201 Created.
  • POST …/assign ist die assign-Aktion. Im Body schickst du die Sammlung mobileAppAssignments. Bei Erfolg kommt 204 No Content.

Achtung beim Namen: Bei Richtlinien in Sektion 52 hieß die Sammlung assignments. Bei Apps heißt sie mobileAppAssignments. Ein falsch benanntes Feld ignoriert Graph, und die Aktion arbeitet nicht mit der Liste, die du meinst.

Die Aktion erwartet die komplette Liste. Schickst du nur den neuen Eintrag, fehlen die bisherigen Ziele in dem, was du übermittelst. Deshalb liest du zuerst alle vorhandenen Zuweisungen, behältst ihre Targets, Intents und Settings bei und hängst den neuen Eintrag an. Genau dieses Muster hast du in Sektion 52 für Richtlinien gebaut.

Praxis 3: Eine Gruppe hinzufügen, ohne etwas zu verlieren

Die Funktion Add-AppZuweisung macht genau das. Die Funktion liegt absichtlich nah an Add-RichtlinienZuweisung aus Sektion 52, inklusive -WhatIf über SupportsShouldProcess.

CodeKlick markiert alles · Strg+C kopiert
function Add-AppZuweisung {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory)][string]$AppId,
        [Parameter(Mandatory)][string]$GruppenId,
        [Parameter(Mandatory)]
        [ValidateSet('available', 'required', 'uninstall', 'availableWithoutEnrollment')]
        [string]$Intent,
        [hashtable]$Settings,
        [switch]$Ausschluss
    )
    $uri = "https://graph.microsoft.com/v1.0/deviceAppManagement/mobileApps/$AppId"
    $alt = @((Invoke-MgGraphRequest -Method GET -Uri "$uri/assignments" -OutputType PSObject).value)

    $zieltyp = if ($Ausschluss) {
        '#microsoft.graph.exclusionGroupAssignmentTarget'
    } else {
        '#microsoft.graph.groupAssignmentTarget'
    }

    $schonDa = $alt | Where-Object {
        $_.intent -eq $Intent -and
        $_.target.groupId -eq $GruppenId -and
        $_.target.'@odata.type' -eq $zieltyp
    }
    if ($schonDa) {
        Write-Host "Diese Zuweisung ist bereits vorhanden, nichts zu tun."
        return
    }

    $bestehende = foreach ($eintrag in $alt) {
        $item = @{
            '@odata.type' = '#microsoft.graph.mobileAppAssignment'
            intent        = $eintrag.intent
            target        = $eintrag.target
        }
        if ($eintrag.id) { $item['id'] = $eintrag.id }
        if ($eintrag.settings) { $item['settings'] = $eintrag.settings }
        $item
    }

    $neu = @{
        '@odata.type' = '#microsoft.graph.mobileAppAssignment'
        intent        = $Intent
        target        = @{
            '@odata.type' = $zieltyp
            groupId       = $GruppenId
        }
    }
    if ($Settings) { $neu['settings'] = $Settings }

    $liste = @($bestehende) + @($neu)
    $json = @{ mobileAppAssignments = @($liste) } | ConvertTo-Json -Depth 10

    if ($PSCmdlet.ShouldProcess($AppId, "Zuweisung $Intent an Gruppe $GruppenId")) {
        Invoke-MgGraphRequest -Method POST -Uri "$uri/assign" -Body $json -ContentType 'application/json' | Out-Null
        Write-Host "Zugewiesen: $(@($liste).Count) Ziel(e) insgesamt."
    }
}

$gruppe = Get-GruppenId -Name 'GRP-Intune-Pilot-Geraete'
Add-AppZuweisung -AppId $app.id -GruppenId $gruppe -Intent 'required' -WhatIf
  • Zuerst werden die vorhandenen Zuweisungen gelesen. Ist dieselbe Gruppe mit demselben Intent und Zieltyp schon enthalten, passiert nichts.
  • Bestehende Einträge nimmst du inklusiver settings in die neue Liste auf. Sonst könntest du Win32-Benachrichtigungen oder Zeitfenster unbeabsichtigt zurücksetzen.
  • Der Parameter der Aktion heißt mobileAppAssignments, nicht assignments.
  • Der erste Aufruf im Beispiel läuft mit -WhatIf. Erst wenn die Meldung stimmt, lässt du den Schalter weg.

Praxis 4: Win32-Zuweisungseinstellungen und Ausschlüsse

Welche settings du schicken darfst, hängt vom App-Typ ab. Für Win32-LOB-Apps ist das win32LobAppAssignmentSettings. Darin steuern notifications die Hinweise (showAll, showReboot, hideAll) und deliveryOptimizationPriority die Priorität der Übermittlungsoptimierung (notConfigured oder foreground). Die DO-Priorität wird laut Microsoft in nationalen Cloudumgebungen nicht unterstützt.

Zusätzlich gibt es Neustart-, Installationszeit- und Auto-Update-Einstellungen. Im Beispiel setzt du nur das, was du bewusst steuern willst, und lässt den Rest weg.

CodeKlick markiert alles · Strg+C kopiert
$win32 = @{
    '@odata.type'                 = '#microsoft.graph.win32LobAppAssignmentSettings'
    notifications                 = 'showAll'
    deliveryOptimizationPriority  = 'notConfigured'
}

$gruppe = Get-GruppenId -Name 'GRP-Intune-Pilot-Geraete'
Add-AppZuweisung -AppId $app.id -GruppenId $gruppe -Intent 'required' -Settings $win32 -WhatIf

# Optional: eine Gruppe von der Zuweisung ausnehmen
$ausschluss = Get-GruppenId -Name 'GRP-Intune-Pilot-Ausschluss'
Add-AppZuweisung -AppId $app.id -GruppenId $ausschluss -Intent 'required' -Ausschluss -WhatIf
  • @odata.type in settings muss zum App-Typ passen. Das Beispiel in der Microsoft-Dokumentation nutzt oft windowsUniversalAppXAppAssignmentSettings, weil dort eine Universal-App gezeigt wird. Für eine Win32-App wäre das der falsche Typ.
  • Mit -Ausschluss setzt das Skript exclusionGroupAssignmentTarget. So nimmst du zum Beispiel eine Pilot-Ausnahmegruppe aus einer erforderlichen Zuweisung heraus, ohne die Hauptgruppe anzufassen.

Derselbe Weg mit dem SDK

Die Cmdlets liegen im Modul Microsoft.Graph.Devices.CorporateManagement, nicht im DeviceManagement-Modul aus Sektion 53. Installiere nur dieses Modul zusätzlich, wenn du die Cmdlets nutzen willst; Invoke-MgGraphRequest bleibt im Authentifizierungsmodul.

CodeKlick markiert alles · Strg+C kopiert
Import-Module Microsoft.Graph.Devices.CorporateManagement

$appSdk = Get-MgDeviceAppManagementMobileApp -All -Property 'id,displayName,publisher,publishingState' |
    Where-Object { $_.DisplayName -eq 'Contoso HR-App' }
if (@($appSdk).Count -ne 1) { throw "App nicht eindeutig gefunden." }

Get-MgDeviceAppManagementMobileAppAssignment -MobileAppId $appSdk.Id -All |
    Select-Object Id, Intent

$gruppe = Get-GruppenId -Name 'GRP-Intune-Pilot-Geraete'
$params = @{
    '@odata.type' = '#microsoft.graph.mobileAppAssignment'
    intent        = 'required'
    target        = @{
        '@odata.type' = '#microsoft.graph.groupAssignmentTarget'
        groupId       = $gruppe
    }
}

# Eine einzelne Zuweisung zusätzlich anlegen
New-MgDeviceAppManagementMobileAppAssignment -MobileAppId $appSdk.Id -BodyParameter $params -WhatIf

# Die assign-Aktion setzt die komplette Liste; $liste zuvor wie in Add-AppZuweisung aufbauen
Set-MgDeviceAppManagementMobileApp -MobileAppId $appSdk.Id -MobileAppAssignments $liste -WhatIf

Troubleshooting: Typische Fehler

App wird nicht eindeutig gefunden

  • Prüfe den exakten Anzeigenamen im Intune-Portal. Zwei Apps mit demselben Namen, etwa in unterschiedlichen Versionen, muss das Skript ablehnen.

Zuweisung wird abgelehnt, Status ist nicht published

  • Laut mobileApp-Referenz kannst du die App erst zuweisen, wenn publishingState den Wert published hat. Warte bei processing, bis der Upload fertig ist.

Bestehende Zuweisungen sind verschwunden

  • Du hast POST …/assign oder Set-MgDeviceAppManagementMobileApp nur mit dem neuen Eintrag aufgerufen. Stelle die Liste aus einem Backup oder aus dem Änderungsprotokoll wieder her und nutze künftig Add-AppZuweisung.

403 Forbidden oder Zugriff verweigert

  • Prüfe (Get-MgContext).Scopes. Zum Schreiben fehlt oft DeviceManagementApps.ReadWrite.All. Zum Auflösen der Gruppe brauchst du außerdem Group.Read.All.

400 Bad Request beim Body

  • Häufige Ursache ist der falsche Sammlungsname (assignments statt mobileAppAssignments) oder ein settings-Typ, der nicht zur App passt. Mit -Debug an Invoke-MgGraphRequest siehst du die tatsächlich geschickte Anfrage.

Best Practices

  • Nur veröffentlichte Apps zuweisen und den Anzeigenamen eindeutig auflösen.
  • Zuweisungen immer zuerst lesen. Die assign-Aktion bekommt die vollständige Liste, inklusive vorhandener Settings.
  • Änderungen zuerst mit -WhatIf prüfen.
  • In den Beispielen weist du einer benannten Gruppe zu, nicht allen Benutzern oder allen Geräten. Die beiden Globalziele gibt es, sind in der Breite aber schwerer zu kontrollieren.
  • Wiederkehrende Teile wie das Lesen der Zuweisungen in eigene Funktionen packen, statt den Ablauf zu kopieren.
  • v1.0 verwenden, solange der Endpunkt dort existiert.

Fazit

App-Zuweisungen per Graph folgen derselben Regel wie Richtlinien: Erst lesen, dann die komplette Liste schicken. Neu ist vor allem der Body-Name mobileAppAssignments, der intent und die typabhängigen settings. Mit Add-AppZuweisung ergänzt du Gruppen, ohne bestehende Ziele oder Win32-Einstellungen zu verlieren.

Zusammenfassend für deinen Workflow:

  • App über GET /deviceAppManagement/mobileApps finden und publishingState prüfen, ohne $expand=assignments.
  • Vorhandene Zuweisungen lesen, bevor du schreibst.
  • Zum Ergänzen die assign-Aktion mit der vollständigen Sammlung mobileAppAssignments nutzen oder bewusst eine einzelne Zuweisung per POST …/assignments anlegen.
  • Intent, Zieltyp und Settings passend zur App setzen, Änderungen zuerst mit -WhatIf testen.

In der nächsten Sektion geht es um fortgeschrittenes Scripting: Du unterscheidest den Benutzerkontext vom Systemkontext und schaust, wann ein Skript in welchem Kontext laufen muss. Einen Überblick über alle Sektionen findest du auf der Seite Intune-Kurs.

Quellen


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