Partager via

Créer un groupe

Espace de noms: microsoft.graph

Créez un groupe comme spécifié dans le corps de la demande. Vous pouvez créer les types de groupes suivants :

  • Groupe Microsoft 365 (groupe unifié)
  • Groupe de sécurité

Cette opération renvoie par défaut uniquement un sous-ensemble de propriétés pour chaque groupe. Ces propriétés par défaut sont indiquées dans la section Propriétés.

Pour obtenir des propriétés qui ne sont pas renvoyées par défaut, effectuez une opération GET et spécifiez les propriétés dans une option de requête OData $select.

Remarque : Bien que Microsoft Teams soit basé sur les groupes Microsoft 365, vous ne pouvez pas créer actuellement d’équipe via cette API. Vous pouvez utiliser les API de l’autre groupe pour gérer une équipe qui a été créée dans l’interface utilisateur de Microsoft Teams.

Cette API est disponible dans les déploiements de cloud national suivants.

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet
✅ ✅ ✅ ✅

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire) Group.ReadWrite.All Directory.ReadWrite.All
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application Group.Create Directory.ReadWrite.All, Group.ReadWrite.All

Pour une application, créez un groupe avec des propriétaires ou des membres alors qu’elle dispose de l’autorisation Group.Create , l’application doit disposer des privilèges nécessaires pour lire le type d’objet qu’elle souhaite attribuer en tant que propriétaire ou membre du groupe. Donc:

  • L’application peut s’attribuer en tant que propriétaire ou membre du groupe.
  • Pour créer le groupe avec des utilisateurs en tant que propriétaires ou membres, l’application doit disposer au moins de l’autorisation User.Read.All .
  • Pour créer le groupe avec d’autres principaux de service en tant que propriétaires ou membres, l’application doit avoir au moins l’autorisation Application.Read.All .
  • Pour créer le groupe avec des utilisateurs ou des principaux de service en tant que propriétaires ou membres, l’application doit disposer au moins de l’autorisation Directory.Read.All .

Requête HTTP

POST /groups

En-têtes de demande

Nom Description
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
Content-Type application/json

Corps de la demande

Dans le corps de la demande, fournissez une représentation JSON de l’objet groupe.

Le tableau suivant répertorie les propriétés qui sont requises lorsque vous créez le groupe. Spécifiez d’autres propriétés accessibles en écriture selon les besoins de votre groupe.

Propriété Type Description
displayName String Nom à afficher dans le carnet d’adresses pour le groupe. Longueur maximale : 256 caractères. Obligatoire.
mailEnabled Boolean Définissez sur true pour les groupes à extension messagerie. Obligatoire.
mailNickname String Alias de messagerie du groupe, unique pour Microsoft 365 de l’organisation. Longueur maximale : 64 caractères. Cette propriété peut contenir uniquement des caractères dans le jeu de caractères ASCII 0 - 127 , à l’exception des caractères suivants : @ () \ [] " ; : <> , SPACE. Obligatoire.
securityEnabled Boolean Définissez sur true pour les groupes à sécurité activée, y compris les groupes Microsoft 365. Obligatoire. Note: Les groupes créés à l’aide de la centre d’administration Microsoft Entra ou de l’Portail Azure ont toujours défini securityEnabled sur true.

Importante

  • La création d’un groupe à l’aide de l’autorisation Group.Create application sans spécifier de propriétaires crée le groupe anonymement et le groupe n’est pas modifiable. Ajoutez des propriétaires au groupe lors de sa création afin que les propriétaires puissent gérer le groupe.

  • La création d’un groupe Microsoft 365 dans un contexte d’application uniquement et sans spécifier de propriétaires crée le groupe de manière anonyme. Cette opération peut entraîner une création non automatique du site SharePoint Online associé et une obligation d’action manuelle.

  • La création d’un groupe microsoft 365 ou de sécurité dans un contexte délégué, connecté en tant qu’utilisateur non administrateur et sans spécifier de propriétaires ajoute automatiquement l’utilisateur appelant en tant que propriétaire du groupe. Un utilisateur administrateur est automatiquement ajouté en tant que propriétaire du groupe Microsoft 365 qu’il crée, mais pas d’un groupe de sécurité.

  • Un utilisateur non administrateur ne peut pas s’ajouter à la collection propriétaires du groupe. Pour plus d’informations, consultez le problème connu associé.

  • Les propriétés suivantes ne peuvent pas être définies dans la requête POST initiale et doivent être définies dans une requête PATCH suivante : allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isSubscribeByMail, unseenCount.

Options de groupTypes

Utilisez la propriété groupTypes pour contrôler le type de groupe et ses membres, comme illustré.

Type de groupe Appartenance attribuée Appartenance dynamique
Microsoft 365 (groupe unifié) ["Unified"] ["Unified","DynamicMembership"]
Dynamique [] (null) ["DynamicMembership"]

Réponse

Si elle réussit, cette méthode renvoie un code de réponse 201 Created et un objet group dans le corps de la réponse. La réponse inclut uniquement les propriétés par défaut du groupe.

範例

Exemple 1 : créer un groupe Microsoft 365

L’exemple suivant permet de créer un groupe Microsoft 365. Étant donné que les propriétaires ne sont pas spécifiés, l’utilisateur appelant est automatiquement ajouté en tant que propriétaire du groupe.

Demande

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
}

Réponse

L’exemple suivant illustre la réponse. La valeur de la propriété preferredDataLocation est héritée de l’emplacement de données préféré du créateur du groupe.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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": []
}

Exemple 2 : créer un groupe avec des propriétaires et des membres

L’exemple suivant crée un groupe de sécurité avec un propriétaire et des membres spécifiés. Un maximum de 20 relations, telles que les propriétaires et les membres, peuvent être ajoutées dans le cadre de la création du groupe. Vous pouvez ensuite ajouter d'autres membres à l'aide du traitement par lots JSON ou API d’ajout de membres.

Un utilisateur non administrateur ne peut pas s’ajouter à la collection propriétaires du groupe. Pour plus d’informations, consultez le problème connu associé.

Demande

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

Réponse

L’exemple suivant montre une réponse réussie. Il inclut uniquement les propriétés par défaut. Vous pouvez ensuite obtenir les propriétés de navigation propriétaires ou membres du groupe pour vérifier les détails du propriétaire ou des membres. La valeur de la propriété preferredDataLocation est héritée de l’emplacement de données préféré du créateur du groupe.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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": []
}

Exemple 3 : Créer un groupe Microsoft 365 qui peut être affecté à un rôle Microsoft Entra

Demande

L’exemple suivant illustre une demande. L’utilisateur appelant doit se voir attribuer l’autorisation RoleManagement.ReadWrite.Directory pour définir la propriété isAssignableToRole ou mettre à jour l’appartenance de ces groupes.

Un groupe avec la propriété isAssignableToRole définie true sur ne peut pas être de type d’appartenance dynamique, son securityEnabled doit être défini sur et la valeur visibility ne peut être Privateque true.

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

Remarque : Un groupe avec la propriété isAssignableToRole définie sur true ne peut pas être de type d’appartenance dynamique et ne peut pas avoir de propriétaire. Pour plus d’informations, consultez Utilisation d’un groupe pour gérer Microsoft Entra attributions de rôles.

Réponse

L’exemple suivant illustre la réponse. Il inclut uniquement les propriétés par défaut. La valeur de la propriété preferredDataLocation est héritée de l’emplacement de données préféré du créateur du groupe.

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,
    "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": []
}