Freigeben über

Gruppe erstellen

  • Artikel

Namespace: microsoft.graph

Erstellen Sie eine neue Gruppe gemäß der Angabe im Anforderungstext. Sie können die folgenden Arten von Gruppen erstellen:

  • Microsoft 365-Gruppe (einheitliche Gruppe)
  • Sicherheitsgruppe

Dieser Vorgang gibt standardmäßig nur eine Teilmenge der Eigenschaften für jede Gruppe zurück. Diese Standardeigenschaften werden im Abschnitt Eigenschaften aufgeführt.

Um Eigenschaften abzurufen, die nicht standardmäßig zurückgegeben werden, führen Sie eine GET-Operation aus, und geben Sie die Eigenschaften in einer $select OData-Abfrageoption an.

Hinweis: Obwohl Microsoft Teams basierend auf Microsoft 365-Gruppen erstellt wurde, können Sie mit dieser API zur Zeit kein Team erstellen. Sie können die anderen Gruppen-APIs verwenden, um ein Team zu verwalten, das in der Microsoft Teams-Benutzeroberfläche erstellt wurde.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ✅ ✅ ✅

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Group.ReadWrite.All Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Group.Create Directory.ReadWrite.All, Group.ReadWrite.All

Wenn eine App eine Gruppe mit Besitzern oder Mitgliedern erstellt, während sie über die Berechtigung Group.Create verfügt, muss die App über die Berechtigungen zum Lesen des Objekttyps verfügen, den sie als Gruppenbesitzer oder -mitglied zuweisen möchte. Deshalb:

  • Die App kann sich selbst als Besitzer oder Mitglied der Gruppe zuweisen.
  • Um die Gruppe mit Benutzern als Besitzer oder Mitglieder zu erstellen, muss die App mindestens über die Berechtigung User.Read.All verfügen.
  • Um die Gruppe mit anderen Dienstprinzipalen als Besitzer oder Mitglieder zu erstellen, muss die App mindestens über die Berechtigung Application.Read.All verfügen.
  • Um die Gruppe mit Benutzern oder Dienstprinzipalen als Besitzer oder Mitgliedern zu erstellen, muss die App mindestens über die Berechtigung Directory.Read.All verfügen.

HTTP-Anforderung

POST /groups

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.
Content-Type application/json

Anforderungstext

Geben Sie im Anforderungstext eine JSON-Darstellung des Gruppenobjekts an.

In der folgenden Tabelle sind die Eigenschaften aufgeführt, die beim Erstellen der Gruppe erforderlich sind. Geben Sie bei Bedarf andere beschreibbare Eigenschaften für Ihre Gruppe an.

Eigenschaft Typ Beschreibung
displayName String Der Name der Gruppe, der im Adressbuch angezeigt wird. Maximale Länge: 256 Zeichen. Erforderlich.
mailEnabled Boolesch Für E-Mail-aktivierte Gruppen auf true setzen. Erforderlich.
mailNickname String Der E-Mail-Alias für die Gruppe, eindeutig für Microsoft 365-Gruppen in der Organisation. Die maximale Länge beträgt 64 Zeichen. Diese Eigenschaft darf nur Zeichen im ASCII-Zeichensatz 0 bis 127 mit Ausnahme der folgenden enthalten: @ () \ [] " ; : <> , SPACE. Erforderlich.
securityEnabled Boolean true für sicherheitsaktivierte Gruppen festlegen, einschließlich Microsoft 365-Gruppen. Erforderlich. Hinweis: Gruppen, die mit dem Microsoft Entra Admin Center oder dem Azure-Portal erstellt wurden, ist securityEnabled anfangs immer auf truefestgelegt.

Wichtig

  • Beim Erstellen einer Gruppe mit der Anwendungsberechtigung Group.Create ohne Angabe von Besitzern wird die Gruppe anonym erstellt, und die Gruppe kann nicht geändert werden. Fügen Sie der Gruppe während der Erstellung Besitzer hinzu, damit die Besitzer die Gruppe verwalten können.

  • Beim Erstellen einer Microsoft 365-Gruppe in einem reinen App-Kontext und ohne Angabe von Besitzern wird die Gruppe anonym erstellt. Dies kann dazu führen, dass die zugehörige SharePoint Online-Website nicht automatisch erstellt wird und weitere manuelle Aktionen nötig sind.

  • Beim Erstellen einer Microsoft 365- oder Sicherheitsgruppe in einem delegierten Kontext, angemeldet als Nicht-Administratorbenutzer und ohne Angabe von Besitzern wird der aufrufende Benutzer automatisch als Gruppenbesitzer hinzugefügt. Ein Administratorbenutzer wird automatisch als Gruppenbesitzer einer Microsoft 365-Gruppe hinzugefügt, die er erstellt, aber nicht einer Sicherheitsgruppe.

  • Ein Benutzer ohne Administratorrechte kann sich nicht selbst zur Sammlung der Gruppenbesitzer hinzufügen. Weitere Informationen finden Sie unter dem zugehörigen bekannten Problem.

  • Folgende Eigenschaften können in der ersten POST-Anfrage nicht gesetzt werden und müssen in einer nachfolgenden PATCH-Anfrage gesetzt werden: allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isSubscribedByMail, unseenCount.

groupTypes-Optionen

Verwenden Sie, wie dargestellt, die Eigenschaft groupTypes zum Steuern des Typs der Gruppe und ihrer Mitgliedschaft.

Typ der Gruppe Zugeordnete Mitgliedschaft Dynamische Mitgliedschaft
Microsoft 365 (auch einheitliche Gruppe genannt) ["Unified"] ["Unified","DynamicMembership"]
Dynamisch [] (null) ["DynamicMembership"]

Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 201 Created und ein group-Objekt im Antworttext zurückgegeben. Die Antwort enthält nur die Standardeigenschaften der Gruppe.

Beispiele

Beispiel 1: Eine Microsoft 365-Gruppe erstellen

Im folgenden Beispiel wird eine Microsoft 365-Gruppe erstellt. Da die Besitzer nicht angegeben wurden, wird der anrufende Benutzer automatisch als Besitzer der Gruppe hinzugefügt.

Anforderung

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

{
  "description": "Self help community for library",
  "displayName": "Library Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "library",
  "securityEnabled": false
}

Antwort

Das folgende Beispiel zeigt die Antwort. Der Wert der Eigenschaft preferredDataLocation-Eigenschaft wird vom bevorzugten Datenspeicherort des Gruppenerstellers geerbt.

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

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

{
    "id": "b320ee12-b1cd-4cca-b648-a437be61c5cd",
      "deletedDateTime": null,
      "classification": null,
      "createdDateTime": "2018-12-22T00:51:37Z",
      "description": "Self help community for library",
      "displayName": "Library Assist",
      "groupTypes": [
          "Unified"
      ],
      "mail": "library7423@contoso.com",
      "mailEnabled": true,
      "mailNickname": "library",
      "onPremisesLastSyncDateTime": null,
      "onPremisesSecurityIdentifier": null,
      "onPremisesSyncEnabled": null,
      "preferredDataLocation": "CAN",
      "proxyAddresses": [
          "SMTP:library7423@contoso.com"
      ],
      "renewedDateTime": "2018-12-22T00:51:37Z",
      "resourceBehaviorOptions": [],
      "resourceProvisioningOptions": [],
      "securityEnabled": false,
      "visibility": "Public",
      "onPremisesProvisioningErrors": []
}

Beispiel 2: Erstellen einer Gruppe mit Besitzern und Mitgliedern

Im folgenden Beispiel wird eine Sicherheitsgruppe mit einem angegebenen Besitzer und Mitgliedern erstellt. Bitte beachten Sie, dass maximal 20 Beziehungen, beispielsweise Besitzer und Mitglieder, als Teil im Rahmen der Gruppenerstellung hinzugefügt werden können. Sie können später weitere Mitglieder hinzufügen, indem Sie die API Mitglied hinzufügen oder die JSON-Batchverarbeitung nutzen.

Ein Benutzer ohne Administratorrechte kann sich nicht selbst zur Sammlung der Gruppenbesitzer hinzufügen. Weitere Informationen finden Sie unter dem zugehörigen bekannten Problem.

Anforderung

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
  "description": "Group with designated owner and members",
  "displayName": "Operations group",
  "groupTypes": [
  ],
  "mailEnabled": false,
  "mailNickname": "operations2019",
  "securityEnabled": true,
  "owners@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

Antwort

Es folgt ein Beispiel für eine erfolgreiche Antwort. Es enthält nur Standardeigenschaften. Sie können anschließend die owners- oder members-Navigationseigenschaft der Gruppe abrufen, um den Besitzer oder die Mitglieder zu überprüfen. Der Wert der Eigenschaft preferredDataLocation-Eigenschaft wird vom bevorzugten Datenspeicherort des Gruppenerstellers geerbt.

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",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/21d05557-b7b6-418f-86fa-a3118d751be4/Microsoft.DirectoryServices.Group",
    "id": "21d05557-b7b6-418f-86fa-a3118d751be4",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:09:14Z",
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "expirationDateTime": null,
    "groupTypes": [],
    "isAssignableToRole": null,
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "operations2019",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": null,
    "preferredLanguage": null,
    "proxyAddresses": [],
    "renewedDateTime": "2021-09-21T07:09:14Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-567301463-1099937718-295959174-3827004813",
    "theme": null,
    "visibility": null,
    "onPremisesProvisioningErrors": []
}

Beispiel 3: Erstellen einer Microsoft 365-Gruppe, die einer Microsoft Entra Rolle zugewiesen werden kann

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Dem aufrufenden Benutzer muss die Berechtigung RoleManagement.ReadWrite.Directory zugewiesen werden, um die isAssignableToRole-Eigenschaft festzulegen oder die Mitgliedschaft solcher Gruppen zu aktualisieren.

Eine Gruppe, deren eigenschaft isAssignableToRole auf true festgelegt ist, darf nicht vom typ dynamic membership sein, ihre securityEnabled muss auf truefestgelegt werden, und die Sichtbarkeit kann nur sein Private.

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": true,
    "mailEnabled": true,
    "securityEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

Hinweis: Eine Gruppe, deren isAssignableToRole-Eigenschaft auf true festgelegt ist, kann nicht vom dynamischen Mitgliedschaftstyp sein und keinen Besitzer haben. Weitere Informationen finden Sie unter Verwenden einer Gruppe zum Verwalten Microsoft Entra Rollenzuweisungen.

Antwort

Das folgende Beispiel zeigt die Antwort. Enthält nur Standardeigenschaften. Der Wert der Eigenschaft preferredDataLocation-Eigenschaft wird vom bevorzugten Datenspeicherort des Gruppenerstellers geerbt.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/55ea2e8c-757f-4f2d-be9e-53c22e8c6a54/Microsoft.DirectoryServices.Group",
    "id": "55ea2e8c-757f-4f2d-be9e-53c22e8c6a54",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:23:06Z",
    "createdByAppId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
    "organizationId": "84841066-274d-4ec0-a5c1-276be684bdd3",
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "expirationDateTime": null,
    "groupTypes": [
        "Unified"
    ],
    "infoCatalogs": [],
    "isAssignableToRole": true,
    "isManagementRestricted": null,
    "mail": "contosohelpdeskadministrators@contoso.com",
    "mailEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": "EU",
    "preferredLanguage": null,
    "proxyAddresses": [
        "SMTP:contosohelpdeskadministrators@contoso.com"
    ],
    "renewedDateTime": "2021-09-21T07:23:06Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-1441410700-1328379263-3260260030-1416268846",
    "theme": null,
    "visibility": "Private",
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}