Ajout de données personnalisées à des ressources à l’aide des extensionsAdd custom data to resources using 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.Microsoft Graph provides a single API endpoint that gives you access to rich people-centric data and insights through a number of resources such as user and message. Vous pouvez également étendre Microsoft Graph avec vos propres données d'application.You can also extend Microsoft Graph with your own application data. Vous pouvez ajouter des propriétés personnalisées aux ressources Microsoft Graph sans utiliser de banque de données externe.You can add custom properties to Microsoft Graph resources without requiring an external data store.

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.For example, you might decide to keep your app lightweight and store app-specific user profile data in Microsoft Graph by extending the user resource. 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.Alternatively, you might want to retain your app’s existing user profile store, and simply add an app-specific store identifier to the user resource.

Microsoft Graph propose deux types d’extensions. Choisissez le type d’extension qui correspond le mieux aux besoins de votre application :Microsoft Graph offers two types of extensions. Choose the extension type that best suits your application needs:

  • Extensions d’ouverture : Un bonne prise en main pour les développeurs.Open extensions: A good way for developers to get started.
  • 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.Schema extensions: A more versatile mechanism for developers who care about storing typed data, making their schema discoverable and shareable, being able to filter, and in the future, being able to perform input data validation and authorization.

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.Important: You should not use extensions to store sensitive personally identifiable information, such as account credentials, government identification numbers, cardholder data, financial account data, healthcare information, or sensitive background information.

Ressources prises en chargeSupported resources

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).The following table lists the resources that support open and schema extensions, and indicates whether they have reached general availability (GA - available in both the v1.0 and beta endpoints) or are in preview (available only in the beta endpoint).

RessourceResource Extensions d’ouvertureOpen extensions Extensions de schémaSchema extensions
Administrative unitAdministrative unit Aperçu uniquementPreview only Aperçu uniquementPreview only
Calendar eventCalendar event DisponibleGA DisponibleGA
DeviceDevice DisponibleGA DisponibleGA
GroupGroup DisponibleGA DisponibleGA
Group calendar eventGroup calendar event DisponibleGA DisponibleGA
Group conversation postGroup conversation post DisponibleGA DisponibleGA
MessageMessage DisponibleGA DisponibleGA
OrganizationOrganization DisponibleGA DisponibleGA
Personal contactPersonal contact DisponibleGA DisponibleGA
UserUser DisponibleGA DisponibleGA

Vous pouvez utiliser les extensions de toutes ces ressources une fois connecté avec un compte scolaire ou professionnel.You can use extensions on all these resources when signed in with a work or school account. 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.In addition, you can use extensions on the event, post, group, message, contact, and user resources when signed in with a personal account.

Extensions d’ouvertureOpen extensions

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.Open extensions (formerly known as Office 365 data extensions) are open types that offer a flexible way to add untyped app data directly to a resource instance.

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.Open extensions, together with their custom data, are accessible through the extensions navigation property of the resource instance. La propriété extensionName est la seule propriété prédéfinie accessible en écriture dans une extension d’ouverture.The extensionName property is the only pre-defined, writable property in an open extension. Lorsque vous créez une extension d’ouverture, vous devez attribuer à la propriété extensionName un nom unique au sein du client.When creating an open extension, you must assign the extensionName property a name that is unique within the tenant.

Pour cela, utilisez un format DNS (Domain Name System) inversé qui dépend de votre propre domaine. Par exemple, Com.Contoso.ContactInfo.One way to do this is to use a reverse domain name system (DNS) format that is dependent on your own domain, for example, Com.Contoso.ContactInfo.

N’utilisez pas le domaine Microsoft (Com.Microsoft ou Com.OnMicrosoft) dans un nom d’extension.Do not use the Microsoft domain (Com.Microsoft or Com.OnMicrosoft) in an extension name.

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).You can create an open extension in a resource instance and store custom data to it all in the same operation (note known limitation for some of the supported resources).

Vous pouvez ensuite lire, mettre à jour ou supprimer l’extension et ses données.You can subsequently read, update, or delete the extension and its data.

Pour voir un exemple d’extension d’ouverture, consultez la rubrique : Ajout de données personnalisées à des utilisateurs à l’aide des extensions d’ouvertureOpen extension example: Add custom data to users using open extensions

Extensions de schémaSchema extensions

Les extensions de schéma permettent de définir un schéma utilisable pour étendre un type de ressource.Schema extensions allow you to define a schema that you can use to extend a resource type. Tout d’abord, vous créez votre définition d’extension de schéma.First, you create your schema extension definition. Ensuite, utilisez-la pour étendre des instances de ressource avec des données personnalisées fortement typées.Then, use it to extend resource instances with strongly-typed custom data. En outre, vous pouvez contrôler l’état de votre extension de schéma et la rendre accessible aux autres applications.In addition, you can control the status of your schema extension and let it be discoverable by other apps. Ces applications peuvent alors utiliser l’extension pour leurs données et créer des expériences supplémentaires.These apps can in turn use the extension for their data and build further experiences on top of it.

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 :When creating a schema extension definition, you must provide a unique name for its id. There are two naming options:

  • 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}.If you already have a vanity .com,.net, .gov, .edu or a .org domain that you have verified with your tenant, you can use the domain name along with the schema name to define a unique name, in this format {domainName}_{schemaName}. Par exemple, si votre domaine personnel est contoso.com, vous pouvez définir un ID : contoso_mySchema.For example, if your vanity domain is contoso.com, you can define an id of, contoso_mySchema. Il s’agit de l’option recommandée.This is the preferred option.
  • 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.If you don’t have a verified vanity domain, you can just set the id to a schema name (without a domain name prefix), for example, mySchema. Microsoft Graph will assign a string ID for you based on the supplied name, in this format: ext{8-random-alphanumeric-chars}_{schema-name}. For example, 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.You will see this unique name in id used as the name of the complex type that will store your custom data on the extended resource instance.

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.Unlike open extensions, managing schema extension definitions (list, create, get, update, and delete) and managing their data (add, get, update, and delete data) are separate sets of API operations.

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 :Because schema extensions are accessible as complex types in instances of the targeted resources, you can do CRUD operations on the custom data in a schema extension in the following ways:

  • Utilisez la méthode de ressource POST pour spécifier les données personnalisées lorsque vous créez une instance de ressource.Use the resource POST method to specify custom data when creating a new resource instance. 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.Note that there is a known issue on the contact, event, message, and post resources that requires creating a schema extension using a PATCH operation.
  • Utilisez la méthode GET de ressource pour lire les données personnalisées.Use the resource GET method to read the custom data.
  • Utilisez la méthode de ressource PATCH pour ajouter ou mettre à jour les données personnalisées dans une instance de ressource existante.Use the resource PATCH method to add or update custom data in an existing resource instance.
  • 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.Use the resource PATCH method to set the complex type to null, to delete the custom data in the resource instance.

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émaSchema extension example: Add custom data to groups using schema extensions

Cycle de vie des extensions de schémaSchema extensions lifecycle

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.When your app creates a schema extension definition, the app is marked as the owner of that schema extension.

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.The owner app can move the extension through different states of a lifecycle, using a PATCH operation on its status property. Depending on the current state, the owner app may be able to update or delete the extension. Any updates to a schema extension should always only be additive and non-breaking.

ÉtatState Comportement de l’étatLifecycle state behavior
InDevelopmentInDevelopment
  • État initial après sa création. L’application propriétaire développe toujours l’extension de schéma. Initial state after creation. The owner app is still developing the schema extension.
  • 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).In this state, any app in the same directory where the owner app is registered can extend resource instances with this schema definition (as long as the app has permissions to that resource).
  • Seule l’application propriétaire peut mettre à jour la définition d’extension avec des modifications supplémentaires ou la supprimer.Only the owner app can update the extension definition with additive changes or delete it.
  • L’application propriétaire peut modifier l’état de l’extension de schéma de InDevelopment à Available.The owner app can move the extension from InDevelopment to the Available state.
AvailableAvailable
  • L’extension du schéma est disponible pour une utilisation par toutes les applications dans n’importe quel client.The schema extension is available for use by all apps in any tenant.
  • 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).After the owner app sets the extension to Available, any app can simply add custom data to instances of those resource types specified in the extension (as long as the app has permissions to that resource). 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.The app can assign custom data when creating a new instance or updating an existing instance.
  • Seule l’application propriétaire peut mettre à jour la définition d’extension avec des modifications supplémentaires.Only the owner app can update the extension definition with additive changes. Aucune application ne peut supprimer la définition d’extension dans cet état.No app can delete the extension definition in this state.
  • L’application propriétaire peut modifier l’état de l’extension de schéma de Available à Deprecated.The owner app can move the schema extension from Available to the Deprecated state.
DeprecatedDeprecated
  • La définition d’extension de schéma ne peut plus être lue ni modifiée.The schema extension definition can no longer be read or modified.
  • Aucune application ne peut afficher, mettre à jour, ajouter de nouvelles propriétés ou supprimer l’extension.No app can view, update, add new properties, or delete the extension.
  • Les applications peuvent toutefois toujours lire, mettre à jour ou supprimer les valeurs de propriété de l’extension existantes.Apps can, however, still read, update, or delete existing extension property values.

Types de données des propriétés pris en chargeSupported property data types

Les types de données suivants sont pris en charge quand vous définissez une propriété dans une extension de schéma :The following data types are supported when defining a property in a schema extension:

Type de propriétéProperty Type RemarquesRemarks
BinaryBinary 256 octets maximum.256 bytes maximum.
BooleanBoolean Non pris en charge pour les messages, les événements et les billets.Not supported for messages, events and posts.
Date/heureDateTime À indiquer au format ISO 8601. Conservées au format UTC.Must be specified in ISO 8601 format. Will be stored in UTC.
EntierInteger Version 32 bits. Non pris en charge pour les messages, les événements et les billets.32-bit value. Not supported for messages, events and posts.
ChaîneString 256 caractères maximum.256 characters maximum.

Remarque : les propriétés à valeurs multiples ne sont pas prises en charge.Note: Multi-value properties are not supported.

Extensions de schéma de l’annuaire Azure ADAzure AD directory schema extensions

Azure AD prend en charge un type d’extension similaire, appelé extension de schéma de répertoire, sur quelques ressources directoryObject. Bien que vous deviez utiliser l’API Graph Azure AD pour créer et gérer les définitions d’extensions de schéma d’annuaire, vous pouvez utiliser l’API Microsoft Graph pour ajouter, obtenir, mettre à jour et supprimer des données dans les propriétés de ces extensions.Azure AD supports a similar type of extension, known as directory schema extensions, on a few directoryObject resources. Although you have to use the Azure AD Graph API to create and manage the definitions of directory schema extensions, you can use the Microsoft Graph API to add, get, update and delete data in the properties of these extensions.

AutorisationsPermissions

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.The same permissions that are required to read from or write to a specific resource are also required to read from or write to any extensions data on that resource. 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.For example, for an app to be able to update the signed-in user's profile with custom app data, the app must have been granted the User.ReadWrite.All permission.

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.Additionally, to create and manage schema extension definitions, an application must be granted the Directory.AccessAsUser.All permission.

Limites des donnéesData limits

Limites des extensions d’ouvertureOpen extension limits

Les limites suivantes s’appliquent aux ressources de répertoire (telles que user, group, device) :The following limits apply to directory resources (such as user, group, device):

  • Chaque extension d’ouverture peut avoir jusqu’à 2 Ko de données (y compris la définition d’extension).Each open extension can have up to 2 KB of data (including the extension definition itself).
  • Une application peut ajouter jusqu’à deux extensions d’ouverture par instance de ressource.An application can add up to two open extensions per resource instance.

Les limites suivantes s’appliquent aux ressources Outlook (par exemple, message, event et contact) :The following limits apply to Outlook resources (such as message, event, and contact):

Limites des extensions de schémaSchema extension limits

Une application ne peut pas créer plus de cinq définitions d’extension du schéma.An application may create no more than five schema extension definitions.

Limitations connuesKnown limitations

Pour les limitations connues concernant l’utilisation des extensions, consultez la section relative aux extensions dans l’article sur les problèmes connus.For known limitations using extensions, see the extensions section in the known issues article.

Exemples d’extensionExtension examples

Voir aussiSee also