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 stellt die Gruppen-API zur Verfügung, um verschiedene Arten von Gruppen 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.
Nur Microsoft 365 und Sicherheitsgruppen können über die Microsoft Graph-Gruppen-API verwaltet werden. E-Mail-aktivierte und Verteilergruppen sind über Microsoft Graph schreibgeschützt.
In Microsoft Graph kann der Typ der Gruppe anhand der Einstellungen der Eigenschaften groupType, mailEnabled und securityEnabled identifiziert werden, wie in der folgenden Tabelle angegeben.
Typ | groupType | mailEnabled | securityEnabled | Erstellt und verwaltet über die Gruppen-API |
---|---|---|---|---|
Microsoft 365-Gruppen | ["Unified"] |
true |
true oder false |
Ja |
Sicherheitsgruppen | [] |
false |
true |
Ja |
E-Mail-aktivierte Sicherheitsgruppen | [] |
true |
true |
Nein |
Verteilergruppen | [] |
true |
false |
Nein |
Weitere Informationen zu Gruppen finden Sie in den folgenden Abschnitten. 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.
Einstellungen für Microsoft 365-Gruppen
Neben der Konfiguration der Standardgruppeneigenschaften können Sie auch die folgenden Einstellungen für Microsoft 365-Gruppen konfigurieren.
- Gruppenablauf
- Gruppeneinstellungen , z. B. ob die Gruppe Gäste als Mitglieder haben kann, wer Gruppen erstellen darf, zulässige Wörter in Gruppennamen usw.
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 im Exchange-Artikel 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
. Beispiel:user.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 groupType-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.
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. Microsoft Entra ID stellt sicher, dass die Lizenzen allen Mitgliedern der Gruppe zugewiesen werden. Allen neuen Mitgliedern, die der Gruppe beitreten, werden die entsprechenden Lizenzen zugewiesen. Wenn sie die Gruppe verlassen, werden diese Lizenzen entfernt. Das Feature kann nur in Sicherheitsgruppen und Microsoft 365-Gruppen mit securityEnabled=TRUE
verwendet werden. 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 | REST-Ressourcen | Siehe auch |
---|---|---|
Gruppen erstellen, Gruppenmerkmale verwalten | ||
Neue Gruppen erstellen, vorhandene Gruppen abrufen, die Eigenschaften für Gruppe aktualisieren und Gruppen löschen. Derzeit können nur Sicherheitsgruppen und Gruppen in Outlook über die API erstellt werden. | Gruppe | Neue Gruppen erstellen Gruppen auflisten Gruppen aktualisieren Gruppen löschen |
Gruppenmitgliedschaft verwalten | ||
Mitglieder einer Gruppe auflisten und Mitglieder hinzufügen oder entfernen. | user Gruppe |
Mitglieder auflisten Mitglied hinzufügen Mitglied entfernen |
Bestimmen, ob ein Benutzer Mitglied einer Gruppe ist, alle Gruppen abrufen, bei denen der Benutzer Mitglied ist. | user group servicePrincipal orgContact |
Mitgliedergruppen prüfen Mitgliedergruppen abrufen |
Besitzer einer Gruppe auflisten und Besitzer hinzufügen oder entfernen. | Benutzer Gruppe |
Besitzer auflisten Mitglied hinzufügen Mitglied entfernen |
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für