Arbeiten mit Gruppen in Microsoft Graph

Artikel
05/23/2024

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 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/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"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Group
{
	Description = "Marketing department folks",
	DisplayName = "Marketing department",
	GroupTypes = new List<string>
	{
		"Unified",
		"DynamicMembership",
	},
	MailEnabled = true,
	MailNickname = "marketing",
	SecurityEnabled = false,
	MembershipRule = "user.department -eq \"Marketing\"",
	MembershipRuleProcessingState = "on",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.PostAsync(requestBody);

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.



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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewGroup()
description := "Marketing department folks"
requestBody.SetDescription(&description) 
displayName := "Marketing department"
requestBody.SetDisplayName(&displayName) 
groupTypes := []string {
	"Unified",
	"DynamicMembership",
}
requestBody.SetGroupTypes(groupTypes)
mailEnabled := true
requestBody.SetMailEnabled(&mailEnabled) 
mailNickname := "marketing"
requestBody.SetMailNickname(&mailNickname) 
securityEnabled := false
requestBody.SetSecurityEnabled(&securityEnabled) 
membershipRule := "user.department -eq \"Marketing\""
requestBody.SetMembershipRule(&membershipRule) 
membershipRuleProcessingState := "on"
requestBody.SetMembershipRuleProcessingState(&membershipRuleProcessingState) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Post(context.Background(), requestBody, nil)

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Group group = new Group();
group.setDescription("Marketing department folks");
group.setDisplayName("Marketing department");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
groupTypes.add("DynamicMembership");
group.setGroupTypes(groupTypes);
group.setMailEnabled(true);
group.setMailNickname("marketing");
group.setSecurityEnabled(false);
group.setMembershipRule("user.department -eq \"Marketing\"");
group.setMembershipRuleProcessingState("on");
Group result = graphClient.groups().post(group);

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.


const options = {
	authProvider,
};

const client = Client.init(options);

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

await client.api('/groups')
	.post(group);

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Group;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Group();
$requestBody->setDescription('Marketing department folks');
$requestBody->setDisplayName('Marketing department');
$requestBody->setGroupTypes(['Unified', 'DynamicMembership', 	]);
$requestBody->setMailEnabled(true);
$requestBody->setMailNickname('marketing');
$requestBody->setSecurityEnabled(false);
$requestBody->setMembershipRule('user.department -eq \"Marketing\"');
$requestBody->setMembershipRuleProcessingState('on');

$result = $graphServiceClient->groups()->post($requestBody)->wait();

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.


Import-Module Microsoft.Graph.Groups

$params = @{
	description = "Marketing department folks"
	displayName = "Marketing department"
	groupTypes = @(
	"Unified"
"DynamicMembership"
)
mailEnabled = $true
mailNickname = "marketing"
securityEnabled = $false
membershipRule = "user.department -eq "Marketing""
membershipRuleProcessingState = "on"
}

New-MgGroup -BodyParameter $params

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.


from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group

graph_client = GraphServiceClient(credentials, scopes)

request_body = Group(
	description = "Marketing department folks",
	display_name = "Marketing department",
	group_types = [
		"Unified",
		"DynamicMembership",
	],
	mail_enabled = True,
	mail_nickname = "marketing",
	security_enabled = False,
	membership_rule = "user.department -eq \"Marketing\"",
	membership_rule_processing_state = "on",
)

result = await graph_client.groups.post(request_body)

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

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/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/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 truefestgelegt 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	Create, Abrufen oder Löschen
Planen und Verwalten von Kalenderereignissen in einem Gruppenkalender	Create, Auflisten, Abrufen, Aktualisieren, Löschen
Verwalten von OneNote-Notizbüchern für eine Gruppe	Create, Liste
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 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 die Verwaltung aller Aspekte von 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

Nächster Schritt

Beginnen Sie mit der Arbeit mit Gruppen

Freigeben über

Arbeiten mit Gruppen in Microsoft Graph

Gruppentypen in Microsoft Entra ID und Microsoft Graph

Microsoft 365-Gruppen

Sicherheitsgruppen und E-Mail-aktivierte Sicherheitsgruppen

Gruppenmitgliedschaft

Dynamische Mitgliedschaft

Andere Arten von Gruppen

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

Gruppensucheinschränkungen für Gastbenutzer in Organisationen

Gruppenbasierte Lizenzierung

Allgemeine Anwendungsfälle

Microsoft Entra Rollen zum Verwalten von Gruppen

Nächster Schritt

Feedback

Feedback

Zusätzliche Ressourcen