Identificateurs EWS dans Exchange
Découvrez les identificateurs dans Exchange et comment vous pouvez les utiliser dans vos applications EWS managed API et EWS.
Chaque objet dans la banque Exchange a un identificateur unique. Vous pouvez utiliser l’identificateur d’un objet pour référencer l’objet et le distinguer des autres objets. Les deux identificateurs les plus courants que vous pouvez utiliser sont les identificateurs de dossier et d’élément.
Pour comprendre les identificateurs et comment ils sont importants pour votre application, il est utile de comprendre la relation entre les objets dans Exchange. Lorsque votre API managée EWS ou votre application EWS communique avec Exchange, vous travaillez avec une hiérarchie d’objets qui inclut des objets de boîte aux lettres, de dossier et d’élément. Un magasin peut être l’un de ces types d’objets. Le plus souvent, il s’agit d’une boîte aux lettres sur le serveur Exchange, mais il peut également s’agir d’un dossier public sur le serveur Exchange. (N’oubliez pas que dans Exchange Online, Exchange Online dans le cadre de Office 365 et les versions d’Exchange à compter d’Exchange 2013, les dossiers publics ne sont qu’un autre type de boîte aux lettres et non un autre type de magasin.) Le magasin contient des dossiers et les dossiers contiennent des éléments, et chacun de ces dossiers et éléments a un identificateur, comme illustré dans la figure suivante.
Figure 1. Hiérarchie des boîtes aux lettres, des dossiers et des éléments
Identificateurs EWS
Les identificateurs qu’EWS utilise pour les dossiers et les éléments sont appelés identificateurs EWS, ou EwsIds. Les EwsIds se trouvent dans de nombreux objets différents au sein d’EWS, mais sont appelés quelque chose de différent pour différents objets. Étant donné que vous pouvez utiliser ces objets dans votre application, vous devez comprendre comment les identificateurs de ces objets sont liés à l’EwsId.
Les identificateurs dans EWS s’appliquent également à l’API managée EWS. Dans l’API managée EWS, les identificateurs sont des propriétés des objets et sont gérés en interne pour être mappés aux éléments EWS.
Tableau 1. Identificateurs d’objets dans EWS
| Object | Identifiant | Quel est son rapport avec EwsId ? |
|---|---|---|
| CalendarItem |
L’élément enfant ItemId contient l’identificateur unique de l’élément de calendrier. |
L’élément enfant ItemId est identique à l’EwsId pour cet élément. |
| ConversationId |
L’attribut Id contient l’identificateur de la conversation dont cet élément fait partie. |
L’attribut Id est identique à l’EwsId pour cet élément. |
| AttachmentId |
Fournit l’identificateur unique de la pièce jointe. L’attribut RootItemId contient l’identificateur unique de l’élément de magasin racine auquel la pièce jointe est attachée. |
Les pièces jointes peuvent être d’autres éléments dans la banque Exchange, auquel cas l’AttachmentId est identique à l’EwsId. Dans tous les cas, RootItemId est un EwsId, car il fait référence à un élément dans le magasin. |
| PersonaId |
L’attribut Id retourne une chaîne qui contient l’identificateur du personnage. |
L’attribut Id est identique à l’EwsId pour le personnage. |
| ContactId |
L’attribut Id retourne une chaîne qui contient l’identificateur du contact. |
L’attribut Id est identique à l’EwsId pour le contact. |
| GroupId |
L’attribut Id retourne une chaîne qui contient l’identificateur du groupe. |
L’attribut Id est identique à l’EwsId pour le groupe. |
| AssociatedCalendarItemId |
L’attribut Id identifie l’élément de calendrier associé à un Objet MeetingMessage, MeetingRequest, MeetingResponse ou MeetingCancellation. |
L’attribut Id est identique à l’EwsId de l’élément de calendrier. |
| UserConfigurationProperties |
La valeur Id de cet élément spécifie la propriété identifier. |
Cet identificateur ne correspond pas directement à l’EwsId, car il s’agit d’un identificateur de propriété et non d’un élément. |
| OccurrenceItemId |
L’attribut RecurringMasterId identifie la forme de base d’un élément périodique. |
La valeur OccurrenceItemId ne correspond pas directement à l’EwsId, contrairement à RecurringMasterId , car elle fait référence à l’objet de niveau supérieur de l’élément périodique. |
| StoreEntryId |
Contient l’identificateur de magasin Exchange d’un élément. |
La valeur StoreEntryId ne correspond pas à l’EwsId, mais elle donne l’identificateur du magasin dans lequel les éléments sont conservés. |
Utilisation des identificateurs
Le serveur Exchange gère les identificateurs de nombreuses façons différentes. Tenez compte des points suivants lorsque vous développez votre API managée EWS ou votre application EWS :
La valeur de l’élément ItemID pour les dossiers et les éléments respecte la casse. Si vous examinez l’ID d’élément d’un dossier ou d’un élément retourné par l’opération FindItem (ou la méthode d’API managée FindItems EWS), vous pouvez penser qu’il s’agit d’un doublon d’un autre ID d’élément ; Toutefois, un ou plusieurs caractères dans les ID d’élément pour les deux éléments ont une casse différente.
Si vous envisagez de stocker l’ID d’élément dans une base de données à récupérer ultérieurement, nous vous recommandons d’avoir une taille de champ de 512 octets, afin qu’il soit suffisamment grand pour contenir le GUID.
Ne supposez pas que votre ID d’élément sera toujours valide si vous devez récupérer l’élément ultérieurement. Si un élément est déplacé dans le magasin, l’ID peut changer en raison de la façon dont un déplacement est géré. Un élément est réellement copié, un nouvel ID est généré, puis l’élément d’origine est supprimé. Notez que les ID de dossier sont immuables et ne changent pas lorsqu’ils sont déplacés dans le magasin.
Les identificateurs dans Exchange sont opaques. Par exemple, l’EwsId est créé à partir de plusieurs informations qui ne sont pas importantes pour vous en tant que développeur, mais qui sont importantes pour Exchange.
Lorsque vous travaillez avec des éléments dans Exchange, l’attribut ChangeKey est une autre valeur à garder à l’esprit. Cette valeur, en plus de l’ID d’élément, est utilisée pour effectuer le suivi de l’état d’un élément. Chaque fois qu’un élément est modifié, une nouvelle clé de modification est générée. Lorsque vous effectuez une opération UpdateItem, par exemple, vous pouvez utiliser l’attribut ChangeKey pour informer le serveur que votre mise à jour est appliquée à la version la plus récente de l’élément. Si une autre application a apporté une modification à l’élément que vous mettez à jour, les clés de modification ne correspondent pas et vous ne pourrez pas effectuer la mise à jour.
ID de dossier unique
Exchange inclut un certain nombre de dossiers de boîtes aux lettres prédéfinis, chacun d’entre eux disposant d’un identificateur, appelé ID de dossier unique. Ceux-ci sont définis par l’énumération de l’API managée EWS WellKnownFolderName et l’élément EWS DistinguishedFolderId . Vous pouvez utiliser ces ID de dossier distingués pour référencer plus facilement l’un des dossiers prédéfinis. Par exemple, pour le dossier Boîte de réception, vous pouvez simplement utiliser « boîte de réception » pour l’identificateur, au lieu de déterminer l’identificateur du dossier.
Les autres dossiers que vous créez pour organiser les éléments de messagerie ont également un ID propre à ce dossier. Cet ID ne change pas même si vous modifiez d’autres propriétés sur le dossier.
Vous pouvez utiliser des ID de dossier unique comme point d’entrée pour l’accès délégué. Lorsque vous lancez l’accès délégué, vous recherchez des éléments ou des dossiers et fournissez l’ID de dossier unique pour spécifier l’emplacement de recherche. Lorsqu’un utilisateur délégué accède au serveur, un élément Mailbox qui est un enfant de l’élément DistinguishedFolderId est utilisé pour spécifier explicitement la boîte aux lettres à laquelle le délégué doit accéder.
Gestion des erreurs
Chaque programme est lié à l’obtention d’une erreur de temps en temps, et les applications EWS ne font pas exception (jeu de mots prévu). Vous pouvez recevoir des erreurs liées à l’identificateur dans l’élément ResponseCode EWS ou dans le cadre de l’énumération de l’API managée ServiceError EWS.
Les erreurs suivantes peuvent se produire dans votre API managée EWS ou votre application EWS. Si vous utilisez une application API managée EWS, les erreurs sont généralement des problèmes liés aux valeurs de propriété ; pour les applications EWS, les erreurs sont associées à des valeurs ou des opérations d’élément XML.
Tableau 2. Erreurs liées à l’identificateur
| Erreur | Se produit lorsque... | Description |
|---|---|---|
| ErrorCalendarCannotUseIdForOccurrenceId |
La valeur de l’OccurenceID ne correspond pas à un élément de calendrier périodique valide. |
La valeur de l’OccurenceId qui a été spécifiée dans la requête peut être valide dans la structure, mais la requête n’a pas pu la faire correspondre à un maître récurrent existant. L’élément périodique peut être supprimé du calendrier. Vérifiez que l’élément existe toujours et que vous utilisez l’identificateur correct. |
| ErrorCalendarCannotUseIdForRecurringMasterId |
L’attribut RecurringMasterId ne correspond pas à une occurrence valide de l’élément OccurrenceId. |
La valeur du RecurringMasterId qui a été spécifié dans la demande peut être valide dans la structure, mais la requête n’a pas pu la faire correspondre à une occurrence existante de l’élément. L’occurrence de l’élément peut être supprimée du calendrier. Vérifiez que l’élément existe toujours et que vous utilisez l’identificateur correct. |
| ErrorCannotUseFolderIdForItemId |
L’ID passé représente un dossier au lieu d’un élément. |
L’identificateur peut être valide au format, mais pas ce que le serveur attendait pour l’opération. Vérifiez que vous référencez l’identificateur correct pour l’opération. |
| ErrorCannotUseItemIdForFolderId |
L’ID qui a été passé représente un élément au lieu d’un dossier. |
L’identificateur peut être valide au format, mais pas ce que le serveur attendait pour l’opération. Vérifiez que vous référencez l’ID correct pour l’opération. |
| ErrorChangeKeyRequiredForWriteOperations |
Une clé de modification valide doit être fournie lorsque vous effectuez certaines opérations de mise à jour. |
Soit vous avez omis une valeur ChangeKey lorsque vous avez demandé une mise à jour, soit la clé de modification était incorrecte. Vérifiez que vous disposez de la clé de modification correcte lorsque vous effectuez des opérations de mise à jour. |
| ErrorInvalidAttachmentId |
La pièce jointe est introuvable dans la collection pièces jointes de l’élément. |
Vous pouvez recevoir ce code de réponse si vous avez un ID de pièce jointe, puis que la pièce jointe est supprimée et que vous essayez d’appeler l’opération GetAttachment sur l’ID de pièce jointe. Vérifiez que la pièce jointe existe dans la collection de pièces jointes. |
| ErrorInvalidChangeKey |
Une clé de modification non valide a été passée. |
Notez que de nombreuses opérations et méthodes ne nécessitent pas de clé de modification pour être passée. Toutefois, si vous fournissez une clé de modification, elle doit être valide, même si elle n’a pas nécessairement besoin d’être à jour. |
| ErrorInvalidFolderId |
L’ID de dossier est endommagé. |
Vérifiez que vous disposez d’un identificateur correctement mis en forme et valide. |
| ErrorInvalidId |
La structure de l’ID et/ou de la clé de modification est incohérente en interne. |
Exchange a rencontré un problème avec l’ID après son analyse. Une erreur s’est peut-être produite dans la conversion. Cela peut se produire, par exemple, si vous avez un IdFormatType.HexEntryId pour un élément dans Outlook, mais que vous le convertissez en un EwsId en pensant qu’il s’agissait d’un format IdFormatType.EntryId . Veillez à utiliser le type de conversion correct. |
| ErrorInvalidIdEmpty |
L’application a spécifié un ID vide. |
Votre application a passé une chaîne vide pour l’identificateur. Vérifiez que vous disposez d’un identificateur correctement mis en forme et valide. |
| ErrorInvalidIdMalformed |
La structure de l’ID est incohérente en interne. |
Exchange a rencontré un problème avec l’ID après son analyse. L’ID n’a peut-être pas été correctement converti. Veillez à utiliser le type de conversion correct. |
| ErrorInvalidIdMalformedEwsLegacyIdFormat |
Un ID de dossier ou d’élément qui utilise le format Exchange 2007 a été spécifié pour une requête avec une version d’Exchange 2007 SP1 ou ultérieure. |
Vous ne pouvez pas utiliser les ID Exchange 2007 dans les requêtes Exchange 2007 SP1 ou ultérieures. Vous devez d’abord utiliser l’opération EWS ConvertId ou la méthode d’API managée EWS ConvertId pour les convertir. |
| ErrorInvalidIdNotAnItemAttachmentId |
La propriété AttachmentId ne fait pas référence à une pièce jointe d’élément. |
L’identificateur peut être valide au format, mais pas ce que le serveur attendait pour l’opération. Vérifiez que vous référencez l’identificateur correct pour l’opération. |
| ErrorInvalidIdReturnedByResolveNames |
Un contact dans votre boîte aux lettres est endommagé. |
L’opération ResolveNames EWS ou la méthode d’API managée EWS ResolveName a retourné un ou plusieurs identificateurs, mais ils ne sont pas valides. Vous devrez peut-être recréer le contact. |
| ErrorInvalidIdStoreObjectIdTooLong |
La structure de l’ID est incohérente en interne. |
Exchange a rencontré un problème avec l’ID après son analyse. L’ID n’a peut-être pas été correctement converti. Veillez à utiliser le type de conversion correct. |
| ErrorInvalidIdTooManyAttachmentLevels |
Les hiérarchies d’attachement dépassent la profondeur maximale de 255 niveaux. |
La valeur de la propriété AttachmentId spécifiée dans la demande peut être valide dans la structure, mais la pièce jointe demandée est trop profonde dans la hiérarchie. Votre code a peut-être essayé d’attacher un élément au-delà de la limite de 255 niveaux. |
| ErrorInvalidImContactId |
Cette erreur peut être retournée lorsque le contact est introuvable dans le groupe de messagerie instantanée lorsque vous utilisez l’opération RemoveImContactFromGroup. Cette erreur s’applique aux clients qui ciblent Exchange Online et versions d’Exchange à compter d’Exchange 2013. |
La valeur de la propriété ContactId spécifiée dans la demande peut être valide dans la structure, mais aucun contact dans la boîte aux lettres ne correspond à cette structure. Le contact a peut-être déjà été supprimé. |
| ErrorInvalidImGroupId |
Cette erreur peut être retournée lorsque le groupe est introuvable dans la boîte aux lettres lorsque vous utilisez l’opération RemoveImGroup. Cette erreur s’applique aux clients qui ciblent Exchange Online et versions d’Exchange à compter d’Exchange 2013. |
La valeur de la propriété GroupId spécifiée dans la requête peut être valide dans la structure, mais aucun groupe de la boîte aux lettres ne correspond à cette structure. Le groupe a peut-être déjà été supprimé. |
| ErrorInvalidReferenceItem |
L’identificateur d’élément référencé n’est pas un MessageType ou ExchangeWebServices.CalendarItemTypeType, ni l’un de leurs descendants. L’identificateur d’élément de référence concerne un objet CalendarItemType et l’organisateur tente de répondre ou répondre à l’ensemble. |
L’identificateur peut être valide au format, mais pas ce que le serveur attendait pour l’opération. Vérifiez que vous référencez l’identificateur correct pour l’opération. |
| ErrorMissingManagedFolderId |
La propriété ID de stratégie, balise de propriété 0x6732, pour le dossier est manquante. |
Le dossier est endommagé. Envisagez de le recréer. |
Conversion d’identificateurs
Vous devrez peut-être convertir un identificateur d’un format à un autre. Par exemple, vous devrez peut-être convertir un identificateur externe à EWS, tel qu’un identificateur provenant d’une connexion MAPI, dans un format que votre application peut utiliser. Pour ce faire, vous pouvez utiliser l’opération ConvertId EWS ou la méthode d’API managée EWS ConvertId .
Par exemple, un EntryID est un identificateur unique généré par la banque de messages MAPI qui est affecté par le magasin lors de l’enregistrement de l’élément. Pour utiliser un EntryID dans votre application, vous devez d’abord le convertir en EwsId.
Outlook Web App utilise sa propre version des identificateurs, appelée OwaId, dans les URL pour accéder aux dossiers et aux éléments. Si votre application doit accéder à des éléments dans Outlook Web App, vous devez convertir l’OwaId en EwsId.
Vous pouvez utiliser l’opération ou la méthode ConvertId pour convertir plusieurs formats d’identificateur différents.
Tableau 3. Formats d’identificateur convertibles dans Exchange
| Format | Description |
|---|---|
| EwsLegacyId |
EwsId qui s’applique à Exchange 2007. |
| EwsId |
EwsId qui s’applique aux Exchange Online et versions d’Exchange à partir d’Exchange 2007 SP1. |
| Storeid |
Identificateur de la banque Exchange où les dossiers et les éléments sont stockés. |
| OwaId |
Identificateur Outlook Web App utilisé avec Outlook Web App dans Exchange 2007 et Exchange 2010. REMARQUE : Exchange Online et versions d’Exchange à partir d’Exchange 2013 utilisent l’EwsId pour Outlook Web App. |
| EntryId |
Identificateur MAPI communément appelé propriété PR_ENTRYID d’un message MAPI. |
| HexEntryId |
Représentation hexadécimale de la propriété PR_ENTRYID utilisée pour l’identificateur d’événement du calendrier de disponibilité. Il s’agit également du format d’identificateur utilisé par Outlook. |