Ajout de données personnalisées à des ressources à l’aide des extensions

Microsoft Graph fournit un seul point de terminaison d’API pour accéder à un vaste répertoire de données et de connaissances axées sur les contacts par l’intermédiaire de nombreuses ressources telles que user et message. Vous pouvez également étendre Microsoft Graph avec vos propres données d'application. Vous pouvez ajouter des propriétés personnalisées aux ressources Microsoft Graph sans utiliser de banque de données externe.

Par exemple, vous pouvez décider de limiter le volume de votre application et de stocker les données de profil utilisateur de celle-ci dans Microsoft Graph en étendant la ressource user. Par ailleurs, vous souhaiterez peut-être conserver le magasin de profils utilisateur de votre application et simplement ajouter un identificateur de magasin propre à l’application pour la ressource user.

Microsoft Graph propose deux types d’extensions. Choisissez le type d’extension qui correspond le mieux aux besoins de votre application :

  • Extensions d’ouverture : Un bonne prise en main pour les développeurs.
  • Extensions de schéma : Un mécanisme plus souple pour les développeurs qui veulent stocker des données typées, faciliter la détection et le partage de leur schéma, appliquer des filtres, ainsi que valider et autoriser les données d’entrée à l’avenir.

Important : Vous devez éviter d’utiliser des extensions pour stocker des informations d’identification personnelle sensibles, telles que les informations d’identification d’un compte, des numéros d’identification officiels, les données de titulaires de cartes, les données de comptes bancaires, des informations médicales ou d’autres informations personnelles sensibles.

Ressources prises en charge

Le tableau suivant indique les ressources qui prennent en charge les extensions ouvertes et de schéma, et indique si elles sont disponibles globalement (« Disponible ») (disponible pour les points de terminaison de la version 1.0 et de la version bêta) ou si elles sont encore en phase préliminaire (disponible uniquement dans le point de terminaison bêta).

Ressource Extensions d’ouverture Extensions de schéma
Administrative unit Aperçu uniquement Aperçu uniquement
Calendar event Disponible Disponible
Device Disponible Disponible
Group Disponible Disponible
Group calendar event Disponible Disponible
Group conversation post Disponible Disponible
Message Disponible Disponible
Organization Disponible Disponible
Personal contact Disponible Disponible
User Disponible Disponibilité générale
Tâche Disponible Disponible
Listes de tâches Disponibilité générale Disponible

Vous pouvez utiliser les extensions de toutes ces ressources une fois connecté avec un compte scolaire ou professionnel. En outre, vous pouvez utiliser les extensions sur les ressources event, post, group, message, contact et user lorsque vous êtes connecté avec un compte personnel.

Extensions d’ouverture

Extensions d’ouverture (anciennement appelées extensions de données Office 365) sont des types d’ouverture qui offrent une grande souplesse pour ajouter des données d’application non typées directement à une instance de ressource.

Les extensions d’ouverture, ainsi que leurs données personnalisées, sont accessibles via la propriété de navigation extensions de l’instance de ressource. La propriété extensionName est la seule propriété prédéfinie accessible en écriture dans une extension d’ouverture. Lorsque vous créez une extension d’ouverture, vous devez attribuer à la propriété extensionName un nom unique au sein du client.

Pour cela, utilisez un format DNS (Domain Name System) inversé qui dépend de votre propre domaine. Par exemple, Com.Contoso.ContactInfo.

N’utilisez pas le domaine Microsoft (Com.Microsoft ou Com.OnMicrosoft) dans un nom d’extension.

Vous pouvez créer une extension d’ouverture dans une instance de ressource et y stocker les données personnalisées en une même opération (notez la limitation connue pour certaines ressources prises en charge).

Vous pouvez ensuite [read](/graph/api/opentypeextension-get, mettre à jourou supprimer l’extension et ses données.

Pour voir un exemple d’extension d’ouverture, consultez la rubrique : Ajout de données personnalisées à des utilisateurs à l’aide des extensions d’ouverture

Extensions de schéma

Les extensions de schéma permettent de définir un schéma utilisable pour étendre un type de ressource. Tout d’abord, vous créez votre définition d’extension de schéma. Ensuite, utilisez-la pour étendre des instances de ressource avec des données personnalisées fortement typées. En outre, vous pouvez contrôler l’état de votre extension de schéma et la rendre accessible aux autres applications. Ces applications peuvent alors utiliser l’extension pour leurs données et créer des expériences supplémentaires.

Lorsque vous créez une définition d’extension de schéma, vous devez fournir un nom unique pour son id. Il existe deux options d’appellation :

  • Si vous possédez déjà un domaine personnel .com,.net, .gov, .edu ou .org que vous avez vérifié avec votre client, vous pouvez utiliser le nom de domaine, ainsi que le nom de schéma pour définir un nom unique, au format {NomDomaine}_{NomSchéma}. Par exemple, si votre domaine personnel est contoso.com, vous pouvez définir un ID : contoso_mySchema. Il s’agit de l’option recommandée.
  • Si vous ne possédez pas un domaine personnel vérifié, vous pouvez définir l’id sur un nom de schéma (sans préfixe de nom de domaine), par exemple, mySchema. Microsoft Graph vous attribue un ID de chaîne en fonction du nom fourni, au format suivant : ext{8 caractères alphanumériques aléatoires}_{nom de schéma}. Par exemple, extkvbmkofy_mySchema.

Vous verrez ce nom unique dans l’ID utilisé comme nom du type complexe qui stocke vos données personnalisées dans l’instance de ressource étendue.

Contrairement aux extensions d’ouverture, la gestion des définitions d’extension de schéma (list, create, get, update et delete) et la gestion de leurs données (ajouter, obtenir, mettre à jour et supprimer des données) sont des jeux d’opérations API distincts.

Dans la mesure où les extensions de schéma sont accessibles sous forme de types complexes dans les instances de ressource ciblées, vous pouvez effectuer les opérations sur les données personnalisées d’une extension de schéma comme suit :

  • Utilisez la méthode de ressource POST pour spécifier les données personnalisées lorsque vous créez une instance de ressource. Notez qu’il existe un problème connu sur les ressources contact, event, message et post qui requiert la création d’une extension de schéma à l’aide une opération PATCH.
  • Utilisez la méthode GET de ressource pour lire les données personnalisées.
  • Utilisez la méthode de ressource PATCH pour ajouter ou mettre à jour les données personnalisées dans une instance de ressource existante.
  • Utilisez la méthode de ressource PATCH pour définir le type complexe sur NULL, pour supprimer les données personnalisées dans l’instance de la ressource.

Pour voir un exemple d’extension de schéma, consultez la rubrique : Ajout de données personnalisées à des groupes à l’aide des extensions de schéma

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 via différents états d’un cycle de vie, à l’aide d’une opération PATCH sur sa propriété status. Selon l’état actuel, le propriétaire de l’application peut être en mesure de mettre à jour ou de supprimer l’extension. Les mises à jour d’une extension de schéma doivent être toujours uniquement additives et insécables.

É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).
  • Seule l’application propriétaire peut mettre à jour la définition d’extension avec des modifications supplémentaires ou la supprimer.
  • L’application propriétaire peut modifier l’état de l’extension de schéma de InDevelopment à 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 définit l’extension sur Available, une application peut simplement ajouter des données personnalisées aux instances de ces types de ressources indiquées dans l’extension (tant que l’application dispose des autorisations pour 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 modifier l’état de l’extension de schéma de Available à 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.
  • Les applications peuvent toutefois toujours lire, mettre à jour ou supprimer les valeurs de propriété de l’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.

Types de données des propriétés pris en charge

Les types de données suivants sont pris en charge quand vous définissez une propriété dans une extension de schéma :

Type de propriété Remarques
Binary 256 octets maximum.
Boolean Non pris en charge pour les messages, les événements et les billets.
Date/heure À indiquer au format ISO 8601. Conservées au format UTC.
Entier Version 32 bits. Non pris en charge pour les messages, les événements et les billets.
Chaîne 256 caractères maximum.

Remarque : les propriétés à valeurs multiples ne sont pas prises en charge.

Extensions de schéma de l’annuaire Azure AD

Azure AD prend en charge un type d’extension semblable, appelé extension de schéma de répertoire, sur quelques ressources DirectoryObject. Vous pouvez utiliser l’API Microsoft Graph pour gérer les définitions d’extensions de propriété et ajouter, obtenir, mettre à jour et supprimer des données dans les propriétés de ces extensions.

Autorisations

Les autorisations requises pour lire ou écrire une ressource spécifique sont également nécessaires pour lire ou écrire les données des extensions sur cette ressource. Par exemple, pour permettre à une application de mettre à jour le profil de l’utilisateur connecté avec des données d’application personnalisées, l’application doit disposer de l’autorisation User.ReadWrite.All.

De plus, pour créer et gérer les définitions d’extension de schéma, une application doit disposer de l’autorisation Directory.AccessAsUser.All.

Limites des données

Limites des extensions d’ouverture

Les limites suivantes s’appliquent aux ressources d’annuaire (utilisateur, groupe, appareil, administrativeUnit, organisation) :

  • Chaque extension d’ouverture peut avoir jusqu’à 2 Ko de données (y compris la définition d’extension).
  • Une application peut ajouter jusqu’à deux extensions d’ouverture par instance de ressource.

Les limites suivantes s’appliquent aux ressources Outlook (par exemple, message, event et contact) :

Limites des extensions de schéma

Une application ne peut pas créer plus de cinq définitions d’extension du schéma.

Limitations connues

Pour les limitations connues concernant l’utilisation des extensions, consultez la section relative aux extensions dans l’article sur les problèmes connus.

Exemples d’extension

Voir aussi