Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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.
|
| 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 :
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