Mettre à jour un groupe

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Mettre à jour les propriétés d’un objet groupe .

Remarque

Lorsque vous utilisez members@odata.bind pour ajouter des membres via PATCH, cette demande peut entraîner des retards de réplication pour les groupes récemment créés. La réplication complète de l’objet de groupe sur les réplicas d’annuaire Microsoft Entra ID peut prendre un court laps de temps. Pendant cette fenêtre, les demandes d’ajout de membres au groupe peuvent retourner une 400 Bad Request erreur avec le message : « L’objet de ressource source ou l’un des objets référencés n’existe pas ».

Pour atténuer ce comportement :

  • Réessayez après un bref délai . Attendez quelques secondes et relancez la demande. Le délai est généralement bref.

Pour plus d’informations, consultez Conception pour la cohérence éventuelle de Microsoft Entra.

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

Service global Gouvernement américain L4 Gouvernement américain L5 (DOD) Chine exploitée par 21Vianet

Autorisations

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

Type d’autorisation Autorisations les moins privilégiées Autorisations à privilèges plus élevés
Déléguée (compte professionnel ou scolaire) Group-NestingSupport.ReadWrite.All Directory.ReadWrite.All, Group-PreferredDataLocation.ReadWrite.All, Group.ManageProtection.All, Group.ReadWrite.All
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application Group-NestingSupport.ReadWrite.All Directory.ReadWrite.All, Group-PreferredDataLocation.ReadWrite.All, Group.ManageProtection.All, Group.ReadWrite.All

Autorisations pour des scénarios spécifiques

  • L’autorisation déléguée Group.ManageProtection.All est l’autorisation de moindre privilège pour mettre à jour la propriété assignedLabels pour les groupes de sécurité cloud et la propriété writebackConfiguration pour tous les groupes. Les scénarios d’application uniquement ne sont pas pris en charge.

Requête HTTP

PATCH /groups/{id}

En-têtes de demande

Nom Type Description
Autorisation string Porteur {token}. Obligatoire. En savoir plus sur l’authentification et les autorisations.

Corps de la demande

Dans le corps de la demande, fournissez uniquement les valeurs des propriétés qui doivent être mises à jour. Les propriétés existantes qui ne sont pas incluses dans le corps de la demande conserveront leurs valeurs précédentes ou seront recalculées en fonction des modifications apportées à d’autres valeurs des propriétés.

Le tableau ci-dessous spécifie les propriétés pouvant être mises à jour.

Propriété Type Description
allowExternalSenders Boolean La valeur par défaut est false. Indique si les personnes extérieures à l’organisation peuvent envoyer des messages au groupe.
assignedLabels Collection assignedLabel Liste des paires d’étiquettes de confidentialité (ID d’étiquette, nom de l’étiquette) associées à un groupe Microsoft 365 ou à un groupe de sécurité cloud. Nécessite une licence Microsoft Entra ID P1. Cette propriété peut être spécifiée lors de la création ou de la mise à jour du groupe. Toutefois, pour les groupes de sécurité cloud, il est immuable une fois défini.
  • Pour les groupes Microsoft 365, cette propriété peut être mise à jour uniquement dans les scénarios délégués où l’appelant a besoin à la fois de l’autorisation Microsoft Graph et d’un rôle d’administrateur pris en charge.
  • L’autorisation déléguée Group.ManageProtection.All est l’autorisation de moindre privilège pour mettre à jour cette propriété pour les groupes de sécurité cloud. Les scénarios d’application uniquement ne sont pas pris en charge.
  • Pour en savoir plus sur la gestion de cette propriété pour Microsoft 365 et les groupes de sécurité cloud par rapport à ceux de Microsoft 365, consultez Principales différences par rapport à l’étiquetage de groupe Microsoft 365 .
autoSubscribeNewMembers Boolean La valeur par défaut est false. Indique si les nouveaux membres ajoutés au groupe seront automatiquement inscrits pour recevoir des notifications par courrier électronique. autoSubscribeNewMembers ne peut pas être true lorsque subscriptionEnabled est false sur le groupe.
description String Description facultative du groupe.
displayName String Nom complet du groupe. Cette propriété est requise lors de la création d’un groupe et ne peut pas être désactivée lors des mises à jour.
mailNickname String Alias de messagerie du groupe, unique pour Microsoft 365 de l’organisation. Longueur maximale : 64 caractères. Cette propriété ne peut contenir que des caractères dans le jeu de caractères ASCII 0 – 127, sauf les caractères suivants : @ () \ [] " ; : . <> , SPACE.
preferredDataLocation Chaîne Emplacement de données préféré pour le groupe Microsoft 365. Pour mettre à jour cette propriété, l’utilisateur appelant doit disposer d’au moins un des rôles Microsoft Entra suivants :
  • Administrateur de compte d’utilisateur
  • Rédacteur d’annuaire
  • Administrateur Exchange
  • Administrateur SharePoint

Pour plus d'informations sur cette propriété, voir OneDrive en ligne Multi-Geo.
securityEnabled Boolean Spécifie si le groupe est un groupe de sécurité, y compris les groupes Microsoft 365.
uniqueName String Identificateur unique qui peut être attribué à un groupe et utilisé comme clé secondaire. Peut être mis à jour uniquement si null et est immuable une fois défini.
visibility String Spécifie la visibilité d’un groupe Microsoft 365. Les valeurs possibles sont les suivantes : Private, Public ou vide (qui est interprété comme étant Public).
welcomeMessageEnabled Boolean La valeur par défaut est true. Indique si un message de bienvenue est envoyé aux nouveaux membres lorsqu’ils sont ajoutés au groupe Microsoft 365.
writebackConfiguration groupWritebackConfiguration Spécifie si un groupe est configuré pour écrire des propriétés d’objet de groupe dans Active Directory local. Ces propriétés sont utilisées lorsque l’écriture différée de groupe est configurée dans le client de synchronisation Microsoft Entra Connect.

Importante

  • Pour mettre à jour ces propriétés (accessType, allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount, welcomeMessageEnabled), vous devez :
    • Spécifiez-les dans leur propre requête PATCH sans inclure les autres propriétés du tableau précédent
    • Disposer de l’autorisation Group.ReadWrite.All (Directory.ReadWrite.All n’est pas pris en charge pour ces propriétés)
  • Seul un sous-ensemble de l’API de groupe qui se rapporte à l’administration et à la gestion du groupe principal prend en charge les autorisations d’application et déléguées. Tous les autres membres de l’API de groupe, y compris la mise à jour d’autoSubscribeNewMembers, prennent uniquement en charge les autorisations déléguées.
  • Les règles de mise à jour des groupes de sécurité à extension messagerie dans Microsoft Exchange Server peuvent être complexes. Pour en savoir plus, voir gérer les groupes de sécurité à extension messagerie dans Exchange Server.
  • Les autorisations d’application ne sont pas prises en charge lors de la mise à jour d’assignedLabels. Group.ManageProtection.All est l’autorisation de moindre privilège pour mettre à jour assignedLabels pour les groupes de sécurité cloud.

Gérer les extensions et les données associées

Utilisez cette API pour gérer le répertoire, le schéma et les extensions ouvertes et leurs données pour les utilisateurs, de la manière suivante :

  • Ajoutez, mettez à jour et stockez des données dans les extensions pour un groupe existant.
  • Pour les extensions de répertoire et de schéma, supprimez toutes les données stockées en définissant la valeur de la propriété d’extension personnalisée sur null. Pour les extensions ouvertes, utilisez l’API Supprimer une extension ouverte.

Réponse

En cas de réussite, cette méthode renvoie un 204 No Content code de réponse, à l’exception d’un 200 OK code de réponse lors de la mise à jour des propriétés suivantes : accessType, allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount, welcomeMessageEnabled.

Erreurs

Code d'état Code d’erreur Message d’erreur Description
400 Bad Request Request_BadRequest « L’objet de ressource source ou l’un des objets référencés n’existe pas. » Le groupe a été créé récemment et n’a pas été entièrement répliqué sur tous les réplicas d’annuaire. Cette erreur est spécifique aux opérations d’écriture de liens (ajout de membres via members@odata.bind). Relancez la demande après un bref délai.

Exemples

Exemple 1 : mise à jour du nom d’affichage et de la description d’un groupe

Demande

L’exemple suivant illustre une demande.

PATCH https://graph.microsoft.com/beta/groups/0d09007d-45b2-458c-b180-880dde3a302e
Content-type: application/json

{
   "description":"Contoso Life v2.0",
   "displayName":"Contoso Life Renewed"
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 204 No Content

Exemple 2 : appliquer une étiquette de confidentialité à un groupe Microsoft 365

Demande

Vous pouvez obtenir l’ID de l’étiquette que vous voulez appliquer à un groupe Microsoft 365 à l’aide de l’étiquette de liste. Vous pouvez ensuite mettre à jour la propriété assignedLabels du groupe avec l’ID d’étiquette.

Remarque : L’utilisation de cette API pour appliquer des étiquettes de confidentialité aux groupes Microsoft 365 n’est prise en charge que pour les scénarios d’autorisation déléguée.

PATCH https://graph.microsoft.com/beta/groups/{id}
Content-type: application/json

{
  "assignedLabels":
  [
    {
        "labelId" : "45cd0c48-c540-4358-ad79-a3658cdc5b88"
    }
  ]
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 204 No Content