Freigeben über


Arbeiten mit Gruppen in Microsoft Graph

Gruppen sind Sammlungen von Prinzipalen mit freigegebenem Zugriff auf Ressourcen in Microsoft-Diensten oder in Ihrer App. Verschiedene Prinzipale wie Benutzer, andere Gruppen, Geräte und Anwendungen können Teil von Gruppen sein. Die Verwendung von Gruppen erspart Ihnen die Arbeit mit einzelnen Prinzipalen und vereinfacht die Verwaltung des Zugriffs auf Ihre Ressourcen.

Microsoft Graph macht den Gruppenressourcentyp und die zugehörigen APIs verfügbar, um verschiedene Gruppentypen und Gruppenfunktionen zu erstellen und zu verwalten.

Hinweis

  1. Gruppen können nur über Geschäfts-, Schul- oder Unikonten erstellt werden. Persönliche Microsoft-Konten unterstützen keine Gruppen.
  2. Für alle gruppenbezogenen Vorgänge in Microsoft Graph ist die Zustimmung durch einen Administrator erforderlich.

Gruppentypen in Microsoft Entra ID und Microsoft Graph

Microsoft Entra ID unterstützt die folgenden Gruppentypen.

Hinweis

Microsoft unterstützt auch dynamische Verteilergruppen , die nicht über Microsoft Graph verwaltet oder abgerufen werden können.

In Microsoft Graph kann der Typ der Gruppe anhand der Einstellungen der Eigenschaften groupTypes, mailEnabled und securityEnabled identifiziert werden. Die folgende Tabelle zeigt, wie Sie die Gruppen anhand ihrer Einstellungen unterscheiden und ob die Gruppentypen über die Microsoft Graph-Gruppen-APIs verwaltet werden können.

Typ groupTypes mailEnabled securityEnabled Erstellt und verwaltet über die Gruppen-APIs
Microsoft 365-Gruppen ["Unified"] true true oder false Ja
Sicherheitsgruppen [] false true Ja
E-Mail-aktivierte Sicherheitsgruppen [] true true Nein; Schreibgeschützt über Microsoft Graph
Verteilergruppen [] true false Nein; Schreibgeschützt über Microsoft Graph

Weitere Informationen zu Gruppen in Microsoft Entra ID finden Sie unter Vergleichen von Gruppen in Microsoft Entra ID.

Microsoft 365-Gruppen

Die Leistungsfähigkeit von Microsoft 365-Gruppen liegt an der Zusammenarbeitsfunktion, die für Personen, die an einem Projekt oder in einem Team zusammenarbeiten, ideal geeignet ist. Sie werden mit Ressourcen erstellt, die Mitglieder der Gruppe freigeben, einschließlich:

  • Outlook-Unterhaltungen auflisten
  • Outlook-Kalender
  • SharePoint-Dateien
  • OneNote-Notizbuch
  • SharePoint-Teamwebsite
  • Planner-Pläne
  • Intune-Geräteverwaltung

Das folgende JSON-Objekt zeigt eine Beispieldarstellung einer Gruppe, wenn Sie die Microsoft Graph-Gruppen-API aufrufen.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
    "id": "4c5ee71b-e6a5-4343-9e2c-4244bc7e0938",
    "deletedDateTime": null,
    "classification": "MBI",
    "createdDateTime": "2016-08-23T14:46:56Z",
    "description": "This is a group in Outlook",
    "displayName": "OutlookGroup101",
    "groupTypes": [
        "Unified"
    ],
    "mail": "outlookgroup101@service.microsoft.com",
    "mailEnabled": true,
    "mailNickname": "outlookgroup101",
    "preferredLanguage": null,
    "proxyAddresses": [
        "smtp:outlookgroup101@contoso.com",
        "SMTP:outlookgroup101@service.microsoft.com"
    ],
    "securityEnabled": false,
    "theme": null,
    "visibility": "Public"
}

Sicherheitsgruppen und E-Mail-aktivierte Sicherheitsgruppen

Sicherheitsgruppen dienen zum Steuern des Benutzerzugriffs auf Ressourcen. Durch Überprüfen, ob ein Benutzer ein Mitglied einer Sicherheitsgruppe ist, kann Ihre App Autorisierungsentscheidungen treffen, wenn dieser Benutzer versucht, auf sichere Ressourcen in Ihrer App zuzugreifen. Sicherheitsgruppen können Benutzer, andere Sicherheitsgruppen, Geräte und Dienstprinzipale als Mitglieder haben.

E-Mail-aktivierte Sicherheitsgruppen werden auf die gleiche Weise wie Sicherheitsgruppen verwendet, können aber zum Senden von E-Mails an Gruppenmitglieder verwendet werden. E-Mail-aktivierte Sicherheitsgruppen können nicht über die API erstellt oder aktualisiert werden. Stattdessen sind sie schreibgeschützt. Weitere Informationen finden Sie unter Verwalten von E-Mail-aktivierten Sicherheitsgruppen.

Das folgende JSON-Objekt zeigt eine Beispieldarstellung einer Gruppe, wenn Sie die Microsoft Graph-Gruppen-API aufrufen.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.group",
    "id": "f87faa71-57a8-4c14-91f0-517f54645106",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2016-07-20T09:21:23Z",
    "description": "This group is a Security Group",
    "displayName": "SecurityGroup101",
    "groupTypes": [],
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "",
    "preferredLanguage": null,
    "proxyAddresses": [],
    "securityEnabled": true
}

Gruppenmitgliedschaft

Die Mitgliedschaft zu Gruppen kann statisch oder dynamisch zugewiesen werden. Nicht alle Objekttypen können Sowohl Mitglieder von Microsoft 365 als auch Sicherheitsgruppen sein.

Die folgende Tabelle zeigt die Typen von Mitgliedern, die entweder Sicherheitsgruppen oder Microsoft 365-Gruppen hinzugefügt werden können.

Objekttyp Mitglied der Sicherheitsgruppe Mitglied einer Microsoft 365-Gruppe
Benutzer Kann Gruppenmitglied sein Kann Gruppenmitglied sein
Sicherheitsgruppe Kann Gruppenmitglied sein Kann kein Gruppenmitglied sein
Microsoft 365 Gruppe Kann kein Gruppenmitglied sein Kann kein Gruppenmitglied sein
Gerät Kann Gruppenmitglied sein Kann kein Gruppenmitglied sein
Dienstprinzipal Kann Gruppenmitglied sein Kann kein Gruppenmitglied sein
Organisationskontakte Kann Gruppenmitglied sein Kann kein Gruppenmitglied sein

Dynamische Mitgliedschaft

Microsoft 365 und Sicherheitsgruppen können dynamische Mitgliedschaftsregeln aufweisen, die der Gruppe basierend auf den Eigenschaften des Prinzipals automatisch Mitglieder hinzufügen oder daraus entfernen. Eine Gruppe „Marketing-Mitarbeiter“ kann zum Beispiel eine dynamische Mitgliedschaftsregel definieren, die besagt, dass nur Benutzer, deren Abteilungseigenschaft auf „Marketing“ eingestellt ist, Mitglieder der Gruppe sein können. In diesem Fall werden alle Benutzer, die die Abteilung verlassen, automatisch aus der Gruppe entfernt.

Nur Benutzer und Geräte werden als Mitglieder in dynamischen Mitgliedschaftsgruppen unterstützt. Sie können eine dynamische Mitgliedschaftsgruppe für Geräte oder Benutzer erstellen, aber nicht für beide.

Die dynamischen Mitgliedschaftsregeln werden bei der Gruppenerstellung über die Eigenschaft membershipRule angegeben. Ein einzelner Ausdruck folgt dieser Syntax: Property Operator Value.

  • Wird Property mit der folgenden Syntax definiert: object.property. Zum Beispiel user.department oder device.accountEnabled.
  • Die Regelsyntax unterstützt verschiedene Operatoren. Weitere Informationen finden Sie unter Unterstützte Ausdrucksoperatoren.
  • Ein Value vom Typ String muss in doppelte Anführungszeichen (") eingeschlossen werden. Sie müssen einen umgekehrten Schrägstrich verwenden, um doppelte Anführungszeichen in doppelten Anführungszeichen mit Escapezeichen zu versehen. Diese Anforderung gilt nicht, wenn der Regel-Generator im Microsoft Entra Admin Center verwendet wird, da der Ausdruck nicht in doppelte Anführungszeichen eingeschlossen ist.

Das folgende Beispiel zeigt eine vollständige Regel.

"membershipRule": "user.department -eq \"Marketing\"".

Sie können mehrere Ausdrücke in einer Regel kombinieren, indem Sie die andOperatoren , orund not verwenden.

Die groupTypes-Eigenschaft muss auch den "DynamicMembership" Wert in der Auflistung enthalten. Die dynamische Mitgliedschaftsregel kann über die EigenschaftmembershipRuleProcessingState aktiviert oder deaktiviert werden. Sie können eine Gruppe mit zugewiesener Mitgliedschaft aktualisieren, um eine dynamische Mitgliedschaft zu erhalten.

Die folgende Beispielanforderung erstellt eine neue Microsoft 365-Gruppe, die nur Mitarbeiter in der Marketingabteilung einschließen kann.

POST https://graph.microsoft.com/beta/groups
Content-type: application/json

{
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mailEnabled": true,
    "mailNickname": "marketing",
    "securityEnabled": false,
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "on"
}

Die Anforderung gibt einen 201 Created Antwortcode und das neu erstellte Gruppenobjekt im Antworttext zurück.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
    "id": "6f7cd676-5445-47c4-9c2b-c47da4671da2",
    "createdDateTime": "2023-01-20T07:00:31Z",
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mail": "marketing@contoso.com",
    "mailEnabled": true,
    "mailNickname": "marketing",
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "On"
}

Weitere Informationen zum Formulieren von Mitgliedschaftsregeln finden Sie unter Dynamische Mitgliedschaftsregeln für Gruppen in Microsoft Entra ID.

Hinweis

Regeln für dynamische Mitgliedschaften erfordern, dass der Mandant mindestens über eine Microsoft Entra ID P1-Lizenz für jeden eindeutigen Benutzer verfügt, der Mitglied einer oder mehrerer dynamischer Gruppen ist.

Andere Arten von Gruppen

Microsoft 365-Gruppen in Yammer werden verwendet, um die Zusammenarbeit von Benutzern über Yammer-Beiträge zu ermöglichen. Diese Art von Gruppe kann über eine Leseanforderung zurückgegeben werden, auf die Beiträge kann jedoch nicht über die API zugegriffen werden. Wenn Yammer-Beiträge und Unterhaltungs-Feeds für eine Gruppe aktiviert sind, werden standardmäßige Microsoft 365-Gruppenunterhaltungen deaktiviert. Weitere Informationen finden Sie in den Yammer-Entwickler-API-Dokumenten.

Zusätzliche Einstellungen für Sicherheits- und Microsoft 365-Gruppen

Neben dem Konfigurieren der Eigenschaften für die Gruppenressource können Sie auch die folgenden Einstellungen für Gruppen konfigurieren.

Einstellung Gilt für
Gruppenablauf Microsoft 365-Gruppen
Gruppeneinstellungen , z. B. ob die Gruppe Gäste als Mitglieder haben kann, zulässige Wörter in Gruppennamen, wer Gruppen erstellen darf usw. Microsoft 365-Gruppen
Einstellungen zum Synchronisieren lokaler Gruppen mit der Cloud, z. B. ob das Rückschreiben aktiviert ist Sicherheits- und Microsoft 365-Gruppen

Gruppensucheinschränkungen für Gastbenutzer in Organisationen

Mithilfe von Gruppensuchfunktionen kann die App nach Gruppen im Verzeichnis eines organization suchen, https://graph.microsoft.com/beta/groupsindem Abfragen für die /groups Ressource ausgeführt werden (z. B. ). Sowohl Administratoren als auch Benutzer, die Mitglieder sind, verfügen über diese Funktion. Gastbenutzer hingegen nicht.

Wenn der angemeldete Benutzer ein Gastbenutzer ist, kann eine App, abhängig von den ihr gewährten Berechtigungen, das Profil einer bestimmten Gruppe lesen (z. B. https://graph.microsoft.com/beta/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc); sie kann jedoch nicht die /groups-Ressource abfragen, wodurch potenziell mehr als eine einzelne Ressource zurückgegeben wird.

Mit den entsprechenden Berechtigungen kann die App die Profile von Gruppen lesen, die über Links in Navigationseigenschaften abgerufen werden, beispielsweise /groups/{id}/members.

Weitere Informationen dazu, was Gastbenutzer mit Gruppen tun können, finden Sie unter Vergleichen der Standardberechtigungen von Mitgliedern und Gästen.

Gruppenbasierte Lizenzierung

Sie können die gruppenbasierte Lizenzierung verwenden, um einer Microsoft Entra Gruppe eine oder mehrere Produktlizenzen zuzuweisen. Die Lizenzen werden dann von den Mitgliedern der Gruppe und automatisch von allen neuen Mitgliedern geerbt. Wenn Mitglieder die Gruppe verlassen, werden diese Lizenzen entfernt. Das Feature kann nur mit Sicherheitsgruppen und Microsoft 365-Gruppen verwendet werden, für die securityEnabled auf truefestgelegt ist.

Weitere Informationen zur gruppenbasierten Lizenzierung finden Sie unter Was ist die gruppenbasierte Lizenzierung in Microsoft Entra ID?.

Außerhalb des Standard Datenspeichers gespeicherte Eigenschaften

Während die Ressourcendaten der Gruppe größtenteils in Microsoft Entra ID gespeichert werden, werden einige eigenschaften wie autoSubscribeNewMembers und allowExternalSenders in Microsoft Exchange gespeichert. In den meisten Fällen können Sie diese Eigenschaften nicht im gleichen Create- oder Update-Anforderungstext wie andere Gruppeneigenschaften angeben.

Eigenschaften, die außerhalb des Standard Datenspeichers gespeichert sind, werden auch im Rahmen der Änderungsnachverfolgung nicht unterstützt. Daher führt eine Änderung an einer dieser Eigenschaften nicht dazu, dass ein Objekt in der Deltaabfrageantwort angezeigt wird.

Die folgenden Eigenschaften für das Gruppenobjekt werden außerhalb des Standard Datenspeichers gespeichert: accessType, allowExternalSenders, autoSubscribeNewMembers, cloudLicensing, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount, membershipRuleProcessingStatus, isArchived.

Häufige Anwendungsfälle für die Gruppen-API in Microsoft Graph

Mit Microsoft Graph können Sie die folgenden allgemeinen Operationen für Gruppen durchführen.

Anwendungsfälle API-Vorgänge
Gruppen erstellen, Gruppenmerkmale verwalten
Neue Gruppen erstellen, vorhandene Gruppen abrufen, die Eigenschaften für Gruppe aktualisieren und Gruppen löschen. Neue Gruppen erstellen
Gruppen auflisten
Gruppen aktualisieren
Gruppen löschen
Verlängern von Gruppen, die bald ablaufen
Wiederherstellen gelöschter Microsoft 365-Gruppen
Verwalten der Gruppenmitgliedschaft und des Besitzes
Mitglieder einer Gruppe auflisten und Mitglieder hinzufügen oder entfernen. Mitglieder auflisten
Mitglied hinzufügen
Mitglied entfernen
Bestimmen, ob ein Benutzer Mitglied einer Gruppe ist, alle Gruppen abrufen, bei denen der Benutzer Mitglied ist. Mitgliedergruppen prüfen
Mitgliedergruppen abrufen
Besitzer einer Gruppe auflisten und Besitzer hinzufügen oder entfernen. Besitzer auflisten
Besitzer hinzufügen
Besitzer entfernen
Gruppierungsfunktionen für Microsoft 365-Apps
Verwalten von Gruppenunterhaltungen Erstellen, Abrufen oder Löschen
Planen und Verwalten von Kalenderereignissen in einem Gruppenkalender Erstellen, Auflisten, Abrufen, Aktualisieren, Löschen
Verwalten von OneNote-Notizbüchern für eine Gruppe Erstellen, Auflisten
Aktivieren einer Microsoft-Gruppe für Microsoft Teams Create

Microsoft Entra Rollen zum Verwalten von Gruppen

Zum Verwalten von Gruppen in delegierten Szenarien müssen der App die entsprechenden Microsoft Graph-Berechtigungen gewährt werden, und der angemeldete Benutzer muss in einer unterstützten Microsoft Entra Rolle sein.

Die folgenden Microsoft Entra Rollen sind die am wenigsten privilegierten Rollen für alle Lese- und Schreibvorgänge in Gruppen über Microsoft Graph, mit Ausnahme von Gruppen, denen Rollen zugewiesen werden können. Die Rolle mit den geringsten Berechtigungen zum Verwalten von Gruppen, die Rollen zugewiesen werden können, ist Administrator für privilegierte Rollen.

  • Verzeichnisautoren
  • Gruppen Administrator
  • Benutzeradministrator

Eine Zusammenfassung der Administratorrollen mit den geringsten Berechtigungen für verschiedene gruppenbezogene Aufgaben finden Sie unter Am wenigsten privilegierte Rollen zum Verwalten von Gruppen.

Sie können auch benutzerdefinierte Rollen für gruppenbezogene Aufgaben erstellen. Informationen zum Identifizieren von Berechtigungen, die mit microsoft.directory/groups/ dem Ableiten der berechtigungsspezifischen Aufgaben beginnen, sowie das Erstellen einer benutzerdefinierten Rolle mit den ausgewählten Berechtigungen finden Sie im Microsoft Entra integrierten Rollenverweis.

Nächster Schritt