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
- Gruppen können nur über Geschäfts-, Schul- oder Unikonten erstellt werden. Persönliche Microsoft-Konten unterstützen keine Gruppen.
- 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.
- Microsoft 365-Gruppen
- Sicherheitsgruppen
- E-Mail-aktivierte Sicherheitsgruppen
- Verteilergruppen
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/v1.0/$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"
}
Weitere Informationen zu Microsoft 365-Gruppen finden Sie unter Übersicht über Microsoft 365-Gruppen in Microsoft Graph.
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 Sicherheitsgruppe, 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 | ||
Sicherheitsgruppe | ||
Microsoft 365 Gruppe | ||
Gerät | ||
Dienstprinzipal | ||
Organisationskontakte |
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 Beispieluser.department
oderdevice.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 and
Operatoren , or
und 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/v1.0/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/v1.0/$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/v1.0/groups
indem 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/v1.0/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 true
festgelegt ist.
Weitere Informationen zur gruppenbasierten Lizenzierung finden Sie unter Was ist die gruppenbasierte Lizenzierung in Microsoft Entra ID?.
Allgemeine Anwendungsfälle
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.