Vue d’ensemble des propriétés étendues OutlookOutlook extended properties overview

Espace de noms: microsoft.graphNamespace: microsoft.graph

Les propriétés étendues vous permettent de stocker des données personnalisées et servent de mécanisme de secours aux applications qui souhaitent accéder aux données personnalisées des propriétés MAPI Outlook lorsque ces propriétés ne figurent pas déjà dans les métadonnées de l’API Microsoft Graph. Vous pouvez utiliser les propriétés étendues de l’API REST pour stocker ou obtenir ces données personnalisées dans les ressources utilisateur suivantes :Extended properties allow storing custom data and specifically serve as a fallback mechanism for apps to access custom data for Outlook MAPI properties when these properties are not already exposed in the Microsoft Graph API metadata. You can use extended properties REST API to store or get such custom data in the following user resources:

Ou, dans les ressources de groupe Microsoft 365 suivantes:Or, in the following Microsoft 365 group resources:

Utiliser des propriétés étendues ou des extensions d’ouverture ?Use extended properties or open extensions?

Dans les scénarios les plus courants, vous devriez pouvoir utiliser les extensions d’ouverture (représentées par openTypeExtension et anciennement appelées extensions de données Office 365) pour stocker et accéder aux données personnalisées pour les instances de ressource dans la boîte aux lettres d’un utilisateur. Utilisez les propriétés étendues uniquement si vous avez besoin d’accéder aux données personnalisées des propriétés MAPI Outlook qui ne figurent pas déjà dans les métadonnées de l’API Microsoft Graph.In most common scenarios, you should be able to use open extensions (represented by openTypeExtension, formerly known as Office 365 data extensions) to store and access custom data for resource instances in a user's mailbox. Use extended properties only if you need to access custom data for Outlook MAPI properties that are not already exposed in the Microsoft Graph API metadata.

Types de propriétés étenduesTypes of extended properties

Que vous envisagiez de stocker une ou plusieurs valeurs (du même type) dans une propriété étendue, vous pouvez créer une propriété étendue sous la forme d’un objet singleValueLegacyExtendedProperty ou multiValueLegacyExtendedProperty.Depending on whether you intend to store a single or multiple values (of the same type) in an extended property, you can create an extended property as a singleValueLegacyExtendedProperty, or multiValueLegacyExtendedProperty.

Chacun de ces types identifie la propriété par son ID et stocke les données dans valeur.Each of these types identifies the property by its id and stores data in value.

Vous pouvez utiliser id pour obtenir une instance de ressource spécifique avec cette propriété étendue, ou filtrer une propriété étendue à valeur unique pour obtenir toutes les instances dotées de cette propriété.You can use id to get a specific resource instance together with that extended property, or filter on a single-value extended property to get all the instances that have that property.

Remarque Vous ne pouvez pas utiliser l’API REST pour obtenir toutes les propriétés étendues d’une instance spécifique dans un seul appel.Note You cannot use the REST API to get all the extended properties of a specific instance in one call.

Formats d’IDid formats

Vous pouvez spécifier ID d’une propriété étendue dans un des trois formats :You can specify id of an extended property in one of three formats:

  • En tant que propriété nommée, identifiée par le type de propriété étendu, espace de noms et un nom de chaîne.As a named property, identified by the extended property type, namespace, and a string name.
  • En tant que propriété nommée, identifiée par le type de propriété étendu, espace de noms et un identifiant numérique.As a named property, identified by the extended property type, namespace, and a numeric identifier.
  • Dans un format proptag identifié par le type de propriété étendu et une balise de propriété MAPI.In a proptag format, identified by the extended property type and a MAPI property tag.

Les deux tableaux ci-dessous décrivent les formats qui sont pris en charge pour spécifier des propriétés étendues à valeur unique et à valeurs multiples.The next 2 tables describe these formats as applied to single and multi-value extended properties. {type} représente le type de la ou des valeurs de la propriété étendue.{type} represents the type of the value or values of the extended property. Les types illustrés dans les exemples sont les suivants : chaîne, nombre entier et tableaux.Shown in the examples are string, integer, and arrays of these types.

Formats d’ID valides pour les propriétés étendues à valeur uniqueValid id formats for single-value extended properties

FormatFormat ExempleExample DescriptionDescription
"{type} {guid} Name {name}""{type} {guid} Name {name}" "String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifie une propriété par l’espace de noms (GUID) auquel il appartient et par un nom de chaîne.Identifies a property by the namespace (the GUID) it belongs to, and a string name.
"{type} {guid} Id {id}""{type} {guid} Id {id}" "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" Identifie une propriété par l’espace de noms (GUID) auquel il appartient et par son identificateur numérique.Identifies a property by the namespace (the GUID) it belongs to, and a numeric identifier.
« {type} {proptag} »"{type} {proptag}" "String 0x4001001E" Identifie une propriété prédéfinie par sa balise de propriété.Identifies a pre-defined property by its property tag.

Formats d’ID valides pour les propriétés étendues à valeurs multiplesValid id formats for multi-value extended properties

FormatFormat ExempleExample DescriptionDescription
"{type} {guid} Name {name}""{type} {guid} Name {name}" "StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifie une propriété par l’espace de noms (GUID) et par un nom de chaîne.Identifies a property by the namespace (the GUID) and a string name.
"{type} {guid} Id {id}""{type} {guid} Id {id}" "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" Identifie une propriété par l’espace de noms (GUID) et par son identificateur numérique.Identifies a property by the namespace (the GUID) and a numeric identifier.
« {type} {proptag} »"{type} {proptag}" "StringArray 0x4002101E" Identifie une propriété prédéfinie par sa balise de propriété.Identifies a pre-defined property by its property tag.

Utilisez un des formats de la propriété nommée pour définir une propriété étendue à valeur unique ou plusieurs valeurs en tant que propriété personnalisée.Use either of the named property formats to define a single-value or multi-value extended property as a custom property. Parmi les deux formats, le premier qui prend un nom de chaîne (nom) est le format par défaut pour la facilité de référence.Among the two formats, the first one that takes a string name (Name) is the preferred format for ease of reference. Les propriétés nommées ont leur identificateurs de propriété dans la plage 0 x 8000-0xfffe.Named properties have their property identifiers in the 0x8000-0xfffe range.

Utilisez le format proptag pour accéder aux propriétés prédéfinies par MAPI ou par un client ou serveur, et qui n’ont pas déjà été exposées dans Microsoft Graph.Use the proptag format to access properties predefined by MAPI, or by a client or server, and that have not already been exposed in Microsoft Graph. Ces propriétés ont des identificateurs de propriété dans la plage 0x7fff 0 x 0001.These properties have property identifiers in the 0x0001-0x7fff range. N’essayez pas de définir une propriété personnalisée en utilisant le format proptag.Do not try to define a custom property using the proptag format.

Vous trouverez des informations sur le mappage d’une propriété étendue vers une propriété MAPI existante, telles que l’identificateur de propriété et le GUID, dans [MS-OXPROPS] Microsoft Corporation, dans la rubrique relative à la liste de propriétés de base des protocoles Exchange Server.You can find information about mapping an extended property to an existing MAPI property, such as the property identifier and GUID, in [MS-OXPROPS] Microsoft Corporation, "Exchange Server Protocols Master Property List".

Remarque Lorsque vous avez choisi le format de l’ID, vous devez accéder à cette propriété étendue uniquement par ce format.Note After you have chosen one format for the id, you should access that extended property by only that format.

Opérations de l’API RESTREST API operations

Opérations d’une propriété étendue à valeur unique :Single-value extended property operations:

Opérations d’une propriété étendue à valeurs multiples :Multi-value extended property operations: