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

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.

• 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 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 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.

HTTP

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

C#

// 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.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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.

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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) 

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.

Java

// 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.

JavaScript

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

<?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.

PowerShell

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.

Python

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.

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. 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