Groupe Upsert

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 .

Créez un objet de groupe s’il n’existe pas, ou mettez à jour les propriétés d’un objet de groupe existant. Vous pouvez créer ou mettre à jour les types de groupes suivants :

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

Par défaut, cette opération renvoie uniquement un sous-ensemble des propriétés pour chaque groupe. Pour obtenir la liste des propriétés renvoyées par défaut, consultez la section Propriétés de la ressource de groupe . 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 : Pour créer une équipe, commencez par créer un groupe, puis ajoutez-y une équipe. Pour plus d’informations, consultez Créer une équipe.

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.ReadWrite.All Directory.ReadWrite.All
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application Group.ReadWrite.All Directory.ReadWrite.All

Pour qu’une application disposant de l’autorisation Group.Create puisse créer un groupe avec des propriétaires ou des membres, elle 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. Par conséquent :

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

Requête HTTP

PATCH /groups(uniqueName='uniqueName')

En-têtes de demande

Nom Description
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et les autorisations.
Content-Type application/json. Obligatoire.
Préférence create-if-missing. Requis pour le comportement de mise à jour. Dans le cas contraire, la demande est traitée comme une opération de mise à jour.

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 si nécessaire pour votre groupe lors de sa création ou de sa mise à jour.

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é ne peut contenir que des caractères du jeu de caractères ASCII compris entre 0 et 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. Remarque : Les groupes créés à l’aide du centre d’administration Microsoft Entra ou du portail Azure ont toujours securityEnabled initialement défini sur true.

Importante

  • La création d’un groupe à l’aide de l’autorisation d’application Group.Create sans spécifier de propriétaires créera le groupe de manière anonyme et le groupe ne sera modifiable. Ajoutez des propriétaires au groupe lors de sa création pour indiquer ceux autorisés à modifier le groupe.
  • La création d’un groupe Microsoft 365 par programmation dans un contexte d’application uniquement et sans spécifier les propriétaires créera 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.
  • Un utilisateur non administrateur ne peut pas s’ajouter à la collection des propriétaires du groupe. Pour plus d’informations, voir le problème connu associé.
  • Les propriétés suivantes ne peuvent pas être définies dans la demande POST initiale et doivent être définies dans une demande PATCH ultérieure : accessType, allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount, welcomeMessageEnabled.

Étant donné que la ressource de groupe prend en charge les extensions,vous pouvez ajouter des propriétés personnalisées avec vos propres données au groupe lors de sa création.

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 un objet avec le nom unique n’existe pas, cette méthode retourne un 201 Created code de réponse et un nouvel objet de groupe dans le corps de la réponse.

Si un objet avec uniqueName n’existe pas et que l’en-tête Prefer: create-if-missingn’est pas spécifié, cette méthode retourne un 404 Not Found code d’erreur.

Si un objet dont le nom unique existe déjà, cette méthode met à jour l’objet du groupe et renvoie un 204 No Content code de réponse.

Exemples

Exemple 1 : créer un groupe Microsoft 365 s’il n’existe pas

L’exemple suivant crée un groupe Microsoft 365, car il n’existe pas de groupe avec la valeur uniqueName spécifiée. É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

PATCH https://graph.microsoft.com/beta/groups(uniqueName='uniqueName')
Content-type: application/json
Prefer: create-if-missing

{
  "description": "Self help community for golf",
  "displayName": "Golf Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "golfassist",
  "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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
    "id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2018-12-22T02:21:05Z",
    "description": "Self help community for golf",
    "displayName": "Golf Assist",
    "expirationDateTime": null,
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": null,
    "mail": "golfassist@contoso.com",
    "mailEnabled": true,
    "mailNickname": "golfassist",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": "CAN",
    "preferredLanguage": null,
    "proxyAddresses": [
        "SMTP:golfassist@contoso.onmicrosoft.com"
    ],
    "renewedDateTime": "2018-12-22T02:21:05Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": false,
    "securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
    "theme": null,
    "visibility": "Public",
    "uniqueName": "uniqueName",
    "onPremisesProvisioningErrors": []
}

Exemple 2 : créer un groupe de sécurité avec un propriétaire et des membres s’il n’existe pas

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

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

Demande

L’exemple suivant illustre une demande.

PATCH https://graph.microsoft.com/beta/groups(uniqueName='uniqueName')
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/beta/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/beta/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/beta/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

Réponse

L’exemple suivant illustre 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 des propriétaires ou des membres du groupe pour vérifier le propriétaire ou les 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/beta/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/1226170d-83d5-49b8-99ab-d1ab3d91333e/Microsoft.DirectoryServices.Group",
    "id": "1226170d-83d5-49b8-99ab-d1ab3d91333e",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:14:44Z",
    "createdByAppId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
    "organizationId": "84841066-274d-4ec0-a5c1-276be684bdd3",
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "expirationDateTime": null,
    "groupTypes": [],
    "infoCatalogs": [],
    "isAssignableToRole": null,
    "isManagementRestricted": 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:14:44Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-304486157-1236829141-2882644889-1043566909",
    "theme": null,
    "uniqueName": "uniqueName",
    "visibility": null,
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}

Exemple 3 : mettre à jour un groupe existant

Dans cet exemple, le groupe spécifié existe déjà, de sorte que l’opération est traitée comme une mise à jour.

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

Demande

L’exemple suivant illustre une demande.

POST https://graph.microsoft.com/beta/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/beta/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/beta/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/beta/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

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.

HTTP/1.1 204 No Content