type de ressource schemaExtension (extensions de schéma)

  • Article

Espace de noms: microsoft.graph

Les extensions de schémas vous permettent de définir un schéma pour étendre et ajouter des données personnalisées fortement typées à un type de ressource. Les données personnalisées apparaissent sous la forme d’un type complexe sur la ressource étendue. Les extensions de schéma sont prises en charge par les types de ressources suivantes :

Utilisez cette ressource et les méthodes associées pour gérer les définitions d’extension de schéma. Pour gérer les données d’extension de schéma sur l’instance de la ressource étendue, utilisez la même requête REST que celle que vous utilisez pour gérer l’instance de ressource. Consultez la rubrique Exemple d’extension de schéma pour savoir comment ajouter des données personnalisées à des groupes.

Pour plus d’informations sur l’extensibilité Microsoft Graph, y compris les limites d’extensions de schéma, consultez Ajout de propriétés personnalisées à des ressources à l’aide d’extensions.

Méthodes

Méthode Type renvoyé Description
Créer schemaExtension Créez une définition d’extension de schéma et sa propriété d’extension de schéma associée.
Répertorier schemaExtension Répertoriez les définitions d’extension de schéma disponibles et leurs propriétés.
Obtenir schemaExtension Lisez les propriétés d’une définition d’extension de schéma spécifique.
Mettre à jour schemaExtension Mettez à jour une définition d’extension de schéma. Utilisez cette opération pour mettre à jour la description, les status, les types cibles ou ajouter des propriétés à la définition d’extension de schéma.
Supprimer Aucun Supprimez une définition d’extension de schéma.

Propriétés

Propriété Type Description
description String Description de l’extension du schéma. Prend en charge $filter (eq).
id Chaîne Identificateur unique pour la définition d’extension de schéma.
Vous pouvez assigner une valeur de deux manières :
  • Concaténer le nom de l’un de vos domaines vérifiés avec un nom pour l’extension de schéma afin de former une chaîne unique dans ce format, {domainName}_{schemaName}. Par exemple : contoso_mySchema.
  • Fournissez un nom de schéma et laissez Microsoft Graph utiliser ce nom de schéma pour terminer l’attribution d’ID au format suivant : ext{8-random-alphanumeric-chars}_{schema-name}. Par exemple, extkvbmkofy_mySchema.
Cette propriété ne peut pas être modifiée après sa création. Prend en charge $filter (eq). Remarque : nous recommandons que votre ID commence par une lettre alphabétique entre A et Z, car les fonctionnalités de requête peuvent être limitées pour les ID qui commencent par des nombres complets.

Prend en charge $filter (eq).
owner String Valeur appId de l’application propriétaire de l’extension de schéma. Le propriétaire de la définition de schéma doit être explicitement spécifié pendant les opérations de création et de mise à jour, sinon il sera implicite et attribué automatiquement par Microsoft Entra ID comme suit :
  • Dans l’accès délégué :
    • L’utilisateur connecté doit être le propriétaire de l’application qui appelle Microsoft Graph pour créer la définition d’extension de schéma.
    • Si l’utilisateur connecté n’est pas le propriétaire de l’application appelante, il doit spécifier explicitement la propriété owner et lui attribuer l’appId d’une application dont il est propriétaire.
  • Dans l’accès à l’application uniquement :
    • La propriété owner n’est pas requise dans le corps de la demande. Au lieu de cela, l’application appelante se voit attribuer la propriété de l’extension de schéma.

Par exemple, si vous créez une définition d’extension de schéma à l’aide de Graph Explorer, vous devez fournir la propriété owner. Une fois définie, cette propriété est affichée en lecture seule et ne peut pas être modifiée. Prend en charge $filter (eq).
propriétés collection extensionSchemaProperty Collection de types et de noms de propriété qui composent la définition d’extension de schéma.
status Chaîne État du cycle de vie de l’extension du schéma. Les états possibles sont InDevelopment, Available et Deprecated. Automatiquement défini sur InDevelopment lors de la création. Pour plus d’informations sur les transitions et comportements d’état possibles, consultez Schema d’extensions du cycle de vie. Prend en charge $filter (eq).
targetTypes String collection Définissez des types de Microsoft Graph (prenant en charge les extensions) auxquels peut s’appliquer l’extension de schéma. Sélectionnez à partir d’administrativeUnit, contact, appareil, événement, groupe, message, organisation, publication, tâche à faire, todoTaskList, ou utilisateur.

Cycle de vie des extensions de schéma

Quand votre application crée une définition d’extension de schéma, l’application est marquée comme étant propriétaire de cette extension de schéma.

L’application propriétaire peut déplacer l’extension dans différents états d’un cycle de vie, à l’aide d’une opération PATCH sur sa propriété status. Selon l’état actuel, l’application propriétaire peut être en mesure de mettre à jour ou de supprimer l’extension. Les mises à jour d’une extension de schéma doivent toujours être additives et non cassants.

État Comportement de l’état
InDevelopment
  • État initial après sa création. L’application propriétaire développe toujours l’extension de schéma.
  • Dans cet état, toute application du même annuaire où l'application propriétaire est enregistrée peut étendre les instances de ressources avec cette définition de schéma (à condition que l'application dispose des autorisations sur cette ressource).
  • Pour une application propriétaire multilocataire, seule la instance de l’application propriétaire qui se trouve dans un répertoire différent du répertoire de base peut étendre les instances de ressources avec cette définition de schéma (si l’application dispose d’autorisations sur cette ressource) ou lire les données d’extension.
  • Seule l’application propriétaire peut mettre à jour la définition d’extension avec des modifications supplémentaires.
  • Seule l’application propriétaire peut supprimer la définition d’extension.
  • L’application propriétaire peut déplacer l’extension de InDevelopment à l’état Available .
Available
  • L’extension du schéma est disponible pour une utilisation par toutes les applications dans n’importe quel client.
  • Une fois que l’application propriétaire a défini l’extension sur Available, toute application peut ajouter des données personnalisées aux instances des types de ressources spécifiés dans l’extension (si l’application dispose d’autorisations sur cette ressource). L’application peut attribuer des données personnalisées lors de la création d’une nouvelle instance ou de la mise à jour d’une instance existante.
  • Seule l’application propriétaire peut mettre à jour la définition d’extension avec des modifications supplémentaires. Aucune application ne peut supprimer la définition d’extension dans cet état.
  • L’application propriétaire peut déplacer l’extension de schéma de Available vers l’état Deprecated .
Deprecated
  • La définition d’extension de schéma ne peut plus être lue ni modifiée.
  • Aucune application ne peut afficher, mettre à jour, ajouter de nouvelles propriétés ou supprimer l’extension.
  • Toutefois, les applications peuvent toujours lire, mettre à jour ou supprimer les valeurs de propriété d’extension existantes.

Remarque

Les définitions d’extension de schéma (marquées comme Available) créées par d’autres développeurs d’autres locataires sont visibles par tous les développeurs (en répertoriant toutes les extensions de schéma). Il en est de même pour les autres API qui renvoient uniquement les données propres au locataire. En revanche, les données d’extension créées sur la base des définitions d’extension de schéma, sont propres au client et sont accessibles uniquement par les applications disposant de l’autorisation explicite.

Représentation JSON

La représentation JSON suivante montre le type de ressource.

{
  "description": "String",
  "id": "String (identifier)",
  "owner": "String",
  "properties": [{"@odata.type": "microsoft.graph.extensionSchemaProperty"}],
  "status": "String",
  "targetTypes": ["String"]
}

Contenu connexe