Gruppe erstellenCreate group

Namespace: microsoft.graphNamespace: microsoft.graph

Erstellen Sie eine neue Gruppe gemäß der Angabe im Anforderungstext.Create a new group as specified in the request body. Sie können die folgenden Arten von Gruppen erstellen:You can create the following types of groups:

  • Microsoft 365-Gruppe (einheitliche Gruppe)Microsoft 365 group (unified group)
  • SicherheitsgruppeSecurity group

Dieser Vorgang gibt standardmäßig nur eine Teilmenge der Eigenschaften für jede Gruppe zurück.This operation returns by default only a subset of the properties for each group. Diese Standardeigenschaften werden im Abschnitt Eigenschaften aufgeführt.These default properties are noted in the Properties section.

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.To get properties that are not returned by default, do a GET operation and specify the properties in a $select OData query option.

Hinweis : Obwohl Microsoft Teams basierend auf Microsoft 365-Gruppen erstellt wurde, können Sie mit dieser API zur Zeit kein Team erstellen.Note : Although Microsoft Teams is built on Microsoft 365 groups, you can't currently create a team via this API. Sie können die anderen Gruppen-APIs verwenden, um ein Team zu verwalten, das in der Microsoft Teams-Benutzeroberfläche erstellt wurde.You can use the other group APIs to manage a team that has been created in the Microsoft Teams UI.

BerechtigungenPermissions

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

BerechtigungstypPermission type Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged)
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.AllGroup.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) Nicht unterstütztNot supported.
ApplicationApplication Group.Create, Group.ReadWrite.All, Directory.ReadWrite.AllGroup.Create, Group.ReadWrite.All, Directory.ReadWrite.All

HTTP-AnforderungHTTP request

POST /groups

AnforderungsheaderRequest headers

NameName TypType BeschreibungDescription
AuthorizationAuthorization stringstring Bearer {token}. Erforderlich.Bearer {token}. Required.
Content-TypeContent-Type application/jsonapplication/json

AnforderungstextRequest body

Die folgende Tabelle enthält die Eigenschaften der group-Ressource, die Sie beim Erstellen einer Gruppe angeben müssen.The following table shows the properties of the group resource to specify when you create a group.

EigenschaftProperty TypType BeschreibungDescription
displayNamedisplayName stringstring Der Name der Gruppe, der im Adressbuch angezeigt wird.The name to display in the address book for the group. Maximale Länge: 256 Zeichen.Maximum length: 256 characters. Erforderlich.Required.
descriptiondescription Zeichenfolgestring Eine Beschreibung für die Gruppe.A description for the group. Max.Max. Länge: 1024 Zeichen.length: 1024 characters. Optional.Optional.
mailEnabledmailEnabled booleanboolean true für E-Mail-aktivierte Gruppen.Set to true for mail-enabled groups. Erforderlich.Required.
mailNicknamemailNickname stringstring Der E-Mail-Alias für die Gruppe.The mail alias for the group. Max.Max. Länge: 64 Zeichen.length: 64 characters. Diese Zeichen können nicht in der mailNickname: @()\[]";:.<>,SPACE verwendet werden.These characters cannot be used in the mailNickName: @()\[]";:.<>,SPACE. Erforderlich.Required.
securityEnabledsecurityEnabled Boolescher Wertboolean Für sicherheitsrelevante Gruppen, einschließlich Microsoft 365-Gruppen, auf true gesetzt.Set to true for security-enabled groups, including Microsoft 365 groups. Erforderlich.Required.
ownersowners Zeichenfolgenauflistungstring collection Diese Eigenschaft stellt die Besitzer für die Gruppe zum Zeitpunkt der Erstellung dar.This property represents the owners for the group at creation time. Optional.Optional.
membersmembers Zeichenfolgenauflistungstring collection Diese Eigenschaft stellt die Mitglieder der Gruppe zum Zeitpunkt der Erstellung dar.This property represents the members for the group at creation time. Optional.Optional.
visibilityvisibility StringString Gibt die Sichtbarkeit einer Microsoft 365-Gruppe an.Specifies the visibility of a Microsoft 365 group. Die folgenden Werte sind möglich: Private, Public, HiddenMembership, oder leer (als Public interpretiert).Possible values are: Private, Public, HiddenMembership, or empty (which is interpreted as Public).

Hinweis: Bei Gruppen, die mit dem Microsoft Azure-Portal erstellt wurden, ist securityEnabled anfänglich immer auf true festgelegt.Note: Groups created using the Microsoft Azure portal always have securityEnabled initially set to true.

Geben Sie bei Bedarf andere beschreibbare Eigenschaften für Ihre Gruppe an.Specify other writable properties as necessary for your group. Weitere Informationen finden Sie in Themen zu Eigenschaften der group-Ressource.For more information, see the properties of the group resource.

Hinweis: Das Erstellen einer Gruppe mit der Anwendungsberechtigung Group.Create ohne Angabe von Besitzern erstellt die Gruppe anonym und die Gruppe ist nicht änderbar.Note: Creating a group using the Group.Create application permission without specifying owners will create the group anonymously and the group will not be modifiable. Sie können die Operation POST verwenden und Besitzer zur Gruppe hinzufügen, während Sie diese erstellen, um Besitzer anzugeben, welche die Gruppe ändern können.You can use the POST operation and add owners to the group while creating it to specify owners who can modify the group.

Beim programmgesteuerten Erstellen einer Microsoft 365-Gruppe mit Nur-App-Kontext und ohne Angabe von Besitzern wird die Gruppe anonym erstellt.Creating a Microsoft 365 group programmatically with an app-only context and without specifying owners will create the group anonymously. Dies kann dazu führen, dass die zugehörige SharePoint Online-Website nicht automatisch erstellt wird und weitere manuelle Aktionen nötig sind.Doing so can result in the associated SharePoint Online site not being created automatically until further manual action is taken.

groupTypes-OptionengroupTypes options

Verwenden Sie, wie dargestellt, die Eigenschaft groupTypes zum Steuern des Typs der Gruppe und ihrer Mitgliedschaft.Use the groupTypes property to control the type of group and its membership, as shown.

Typ der GruppeType of group Zugeordnete MitgliedschaftAssigned membership Dynamische MitgliedschaftDynamic membership
Microsoft 365 (auch einheitliche Gruppe genannt)Microsoft 365 (aka unified group) ["Unified"] ["Unified","DynamicMembership"]
DynamischDynamic [] ( null )[] ( null ) ["DynamicMembership"]

AntwortResponse

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 201 Created und ein group-Objekt im Antworttext zurückgegeben.If successful, this method returns a 201 Created response code and a group object in the response body. Die Antwort enthält nur die Standardeigenschaften der Gruppe.The response includes only the default properties of the group.

BeispieleExamples

Beispiel 1: Eine Microsoft 365-Gruppe erstellenExample 1: Create a Microsoft 365 group

Im folgenden Beispiel wird eine Microsoft 365-Gruppe erstellt.The following example creates a Microsoft 365 group.

AnforderungRequest

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

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

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.Note: The response object shown here might be shortened for readability. Von einem tatsächlichen Aufruf werden alle Standardeigenschaften zurückgegeben.All the default properties are returned from an actual call.

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",
      "creationOptions": [],
      "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 MitgliedernExample 2: Create a group with owners and members

Im folgenden Beispiel wird eine Microsoft 365-Gruppe mit einem angegebenen Besitzer und Mitgliedern erstellt.The following example creates a Microsoft 365 group with an owner and members specified. Bitte beachten Sie, dass maximal 20 Beziehungen, beispielsweise Besitzer und Mitglieder, als Teil im Rahmen der Gruppenerstellung hinzugefügt werden können.Note that a maximum of 20 relationships, such as owners and members, can be added as part of group creation. Sie können später weitere Mitglieder hinzufügen, indem Sie die API Mitglied hinzufügen oder die JSON-Batchverarbeitung nutzen.You can subsequently add more members by using the add member API or JSON batching.

AnforderungRequest

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

{
  "description": "Group with designated owner and members",
  "displayName": "Operations group",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "operations2019",
  "securityEnabled": false,
  "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"
  ]
}

AntwortResponse

Es folgt ein Beispiel für eine erfolgreiche Antwort.The following is an example of a successful response. Es enthält nur Standardeigenschaften.It includes only default properties. Sie können anschließend die owners - oder members -Navigationseigenschaft der Gruppe abrufen, um den Besitzer oder die Mitglieder zu überprüfen.You can subsequently get the owners or members navigation properties of the group to verify the owner or members.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.Note: The response object shown here might be shortened for readability. Von einem tatsächlichen Aufruf werden alle Standardeigenschaften zurückgegeben.All the default properties are returned from an actual call.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "502df398-d59c-469d-944f-34a50e60db3f",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2018-12-27T22:17:07Z",
    "creationOptions": [],
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "groupTypes": [
        "Unified"
    ],
    "mail": "operations2019@contoso.com",
    "mailEnabled": true,
    "mailNickname": "operations2019",
    "onPremisesLastSyncDateTime": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": "CAN",
    "proxyAddresses": [
        "SMTP:operations2019@contoso.com"
    ],
    "renewedDateTime": "2018-12-27T22:17:07Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": false,
    "visibility": "Public",
    "onPremisesProvisioningErrors": []
}