Référence de l'API REST des propriétés étendues d'Outlook (version 2.0)

  • Article

S’applique à : Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com** **

L'API REST des propriétés étendues d'Outlook permet aux applications de stocker des données personnalisées et leur fournit un mécanisme de secours d'accès aux données personnalisées pour les propriétés MAPI Outlook lorsque ces propriétés ne sont pas déjà exposées dans les métadonnées de l'API REST Outlook. Vous pouvez utiliser l’API de Propriétés Étendues pour stocker ou obtenir des données personnalisées dans un message, un dossier de courrier, un événement, un calendrier, un contact, un dossier de contacts, une tâche ou un dossier de tâches dans le compte de l’utilisateur connecté. Il peut s’agir d’un compte Office 365 ou d’un compte Microsoft (Hotmail.com, Live.com, MSN.com, Outlook.com et Passport.com).

Notes

Afin de simplifier les explications, le reste de l’article utilise Outlook.com pour inclure ces domaines de comptes Microsoft.

La version 2.0 de l’API ne vous intéresse pas ? Dans la table des matières sur la gauche, accédez à la section Référence API REST pour Office 365 et sélectionnez la version souhaitée.

Utilisation de l'API REST des propriétés étendues

Propriétés étendues ou extensions de données ?

Utilisez les propriétés étendues et cette API REST uniquement si vous devez accéder à des données personnalisées pour les propriétés MAPI Outlook qui ne sont pas déjà exposées via les métadonnées de l'API REST Outlook. Pour la plupart des scénarios, vous devez utiliser les extensions de données Office 365 Data Extensions et son API REST pour stocker et accéder aux données personnalisées des éléments dans la boîte aux lettres de l'utilisateur. Vous pouvez vérifier quelles propriétés sont exposées par les métadonnées lors du https://outlook.office.com/api/{version}/$metadataremplacement de {version} par la version 2.0, bêta, etc., pour la version de votre choix.

Authentification

Comme les autres API REST Outlook, pour chaque requête envoyée à l’API des propriétés étendues, vous devez inclure un jeton d’accès valide. Pour obtenir un jeton d’accès, vous devez avoir inscrit et identifié votre application, et obtenu l’autorisation appropriée.

Vous pouvez en apprendre plus sur certaines options d’inscription et d’autorisation simplifiées pour vous. Gardez cela à l’esprit lorsque vous effectuez les opérations spécifiques à l’API REST des tâches.

Version de l’API

Cette API a été promue de la préversion au statut de disponibilité générale (GA). Elle est prise en charge dans les versions 2.0 et bêta de l’API REST d’Outlook.

Ressources REST prises en charge

Vous pouvez créer des propriétés étendues pour les instances des ressources suivantes :

La ressource doit figurer dans la boîte aux lettres de l'utilisateur connecté dans Office 365 ou Outlook.com.

Paramètres d’URL

Les exemples de cet article utilisent les espaces réservés aux ID suivants dans les paramètres des URL de requête REST. Vous devez spécifier l'ID de l'instance de la ressource pour laquelle vous souhaitez créer une extension.

Paramètre Type Description
Paramètres d’URL
calendar_id chaîne L'ID du calendrier.
contact_id chaîne L'ID des contacts.
contactFolder_id chaîne L'ID du dossier contacts.
event_id chaîne L'ID d'événement.
mailFolder_id chaîne L'ID du dossier courrier.
message_id chaîne L'ID de messagerie.
propertyId_value chaîne Une valeur PropertyId dans l'un des formats pris en charge.
property_value chaîne La valeur d’une propriété étendue.
task_id chaîne L'ID de tâche.
taskFolder_id chaîne L'ID du dossier des tâches.

Voir Utiliser l’API REST Outlook pour plus d’informations communes à tous les sous-ensembles de l’API REST Outlook.

Vue d'ensemble

Vous pouvez créer et stocker dynamiquement des données dans une propriété étendue de l'instance d'entité. Que vous envisagiez de stocker des valeurs uniques ou multiples (du même type), vous pouvez créer la propriété étendue sous la forme d’un objet singleValueLegacyExtendedProperty, ou multiValueLegacyExtendedProperty.

Chacun de ces types identifie la propriété par son propertyid et stocke les données dans Valeur.

Vous pouvez utiliser PropertyId pour obtenir une instance d'entité spécifique avec cette propriété étendue, ou filtrer une propriété étendue à valeur unique pour obtenir toutes les instances avec cette propriété.

Notes

Vous ne pouvez pas utiliser l’API REST pour obtenir toutes les propriétés étendues d’une instance spécifique en un seul appel.

Formats PropertyId

Lorsque vous créez une propriété étendue à valeur unique multiple, vous pouvez spécifier le PropertyId dans l’un des deux formats, basé soit sur un nom de chaîne ou un identificateur numérique, soit sur le type réel de la valeur ou des valeurs de la propriété. 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. {_type_} représente le type de la ou des valeurs de la propriété. Les types illustrés dans les exemples sont les suivants : chaîne, nombre entier et tableaux.

Étant donné que les propriétés étendues dans la plupart des cas sont interopérables avec des propriétés MAPI définies qui ne figurent pas, par souci de simplicité, dans les métadonnées de l’API REST Outlook, le format que vous choisissez doit indiquer si la propriété MAPI correspondante utilise une chaîne de caractères ou une valeur numérique dans son identificateur de propriété MAPI. 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] de la « Liste des propriétés de base des protocoles Exchange Server »de Microsoft Corporation.

Notes

Lorsque vous avez choisi un format pour le Propertyid, vous ne devez accéder à cette propriété étendue que par ce format.

Formats de Propertyid valides pour les propriétés étendues à valeur unique

Format Exemple Description
« {type} {guid} Nom {name} » "String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifie une propriété par l’espace de noms (GUID) auquel il appartient et par son nom.
« {type} {guid} Id {id} » "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" Identifie une propriété par l’espace de noms (GUID) auquel elle appartient et par son identificateur.

Formats Propertyid valides pour les propriétés étendues à valeurs multiples

Format Exemple Description
« {type} {guid} Nom {name} » "StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifie une propriété par son espace de noms (GUID) et son nom.
« {type} {guid} Id {id} » "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" Identifie une propriété par son espace de noms (GUID) et son identificateur.

Opérations de la propriété étendue

Créez une propriété étendue dans un élément existant

Créez une ou plusieurs propriétés étendues pour l'instance spécifiée d'une ressource prise en charge. Chaque propriété étendue peut être à valeur simple ou à valeurs multiples.

PATCH https://outlook.office.com/api/v2.0/me/messages('{message_id}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')
PATCH https://outlook.office.com/api/v2.0/me/tasks('{task_id}')
PATCH https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')
PATCH https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/taskfolders('{taskFolder_id}')

Étendue minimale requise

L’une des étendues en lecture/écriture suivantes, correspondant à la ressource ciblée :

Paramètre Type Description
Paramètres du corps
SingleValueExtendedProperties Collection (SingleValueLegacyExtendedProperty) Tableau d’une ou plusieurs propriétés étendues à valeur unique.
PropertyId chaîne Pour chaque propriété dans la collection SingleValueExtendedProperties spécifiez ceci pour identifier la propriété. Il doit obéir à l'un des formats pris en charge pour les propriétés étendues à valeur unique. Obligatoire.
Valeur chaîne Pour chaque propriété dans la collection SingleValueExtendedProperties spécifiez la valeur de la propriété. Obligatoire.
MultiValueExtendedProperties Collection (MultiValueLegacyExtendedProperty) Tableau d’une ou plusieurs propriétés étendues à valeurs multiples.
PropertyId chaîne Pour chaque propriété dans la collection MultiValueExtendedProperties spécifiez ceci pour identifier la propriété. Il doit obéir à l'un des formats pris en charge pour les propriétés étendues à valeurs multiples. Obligatoire.
Valeur Collection(string) Pour chaque propriété dans la collection MultiValueExtendedProperties, spécifiez les valeurs de cette propriété. Obligatoire.

Exemple de demande

Le premier exemple crée une propriété étendue à valeur simple pour le message spécifié. Cette propriété étendue est le seul élément du tableau SingleValueExtendedProperties. Le corps de la requête inclut les éléments suivants pour la propriété étendue :

  • PropertyId spécifie le type de propriété comme string, le GUID et la propriété nommée Color.
  • Value spécifie Green en tant que valeur de la propriété Color.
PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

{
  "SingleValueExtendedProperties": [
      {
         "PropertyId":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "Value":"Green"
      }
    ]
}

Exemple de réponse

Une réponse correcte est indiquée par un code de réponse HTTP 200 OK et inclut le message spécifié dans le corps de la réponse, semblable à la réponse de mettre à jour un message. La réponse n’inclut pas la propriété étendue nouvellement créée.

Exemple de demande

Le second exemple crée une propriété étendue à valeurs multiples pour le message spécifié. Cette propriété est le seul élément du tableau MultiValueExtendedProperties. Le corps de la requête comprend :

  • PropertyId qui spécifie la propriété sous la forme d’un tableau de chaînes avec le GUID spécifié et le nom Palette.
  • Value qui spécifie Palette sous la forme d’un tableau de 3 valeurs de chaîne ["Green", "Aqua", "Blue"].
PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_as77AACHsLrBBBA=')

Content-Type: application/json

{
  "MultiValueExtendedProperties": [
      {
         "PropertyId":"StringArray {66f5a359-4659-4830-9070-00049ec6ac6e} Name Palette",
         "Value":["Green", "Aqua", "Blue"]
      }
    ]
}

Exemple de réponse

Une réponse correcte est indiquée par un code de réponse HTTP 200 OK et inclut le message spécifié dans le corps de la réponse, semblable à la réponse de mettre à jour un message. La réponse n’inclut pas la propriété étendue nouvellement créée.

Pour afficher la propriété étendue nouvellement créée, obtenez le message développé avec la propriété étendue.

Créez une propriété étendue dans un nouvel élément

Créez une ou plusieurs propriétés étendues lors de la création d'une nouvelle instance d'une ressource prise en charge, tous dans le même appel POST. Incluez la propriété ou les propriétés étendues dans le corps de la requête POST.

POST https://outlook.office.com/api/v2.0/me/messages
POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/contacts
POST https://outlook.office.com/api/v2.0/me/tasks
POST https://outlook.office.com/api/v2.0/me/mailfolders
POST https://outlook.office.com/api/v2.0/me/calendars
POST https://outlook.office.com/api/v2.0/me/contactfolders
POST https://outlook.office.com/api/v2.0/me/taskfolders

Étendue minimale requise

L’une des étendues en lecture/écriture suivantes, correspondant à la ressource ciblée :

Paramètre Type Description
Paramètres du corps
SingleValueExtendedProperties Collection (SingleValueLegacyExtendedProperty) Tableau d’une ou plusieurs propriétés étendues à valeur unique.
PropertyId chaîne Pour chaque propriété dans la collection SingleValueExtendedProperties spécifiez ceci pour identifier la propriété. Il doit obéir à l'un des formats pris en charge pour les propriétés étendues à valeur unique. Obligatoire.
Valeur chaîne Pour chaque propriété dans la collection SingleValueExtendedProperties spécifiez la valeur de la propriété. Obligatoire.
MultiValueExtendedProperties Collection (MultiValueLegacyExtendedProperty) Tableau d’une ou plusieurs propriétés étendues à valeurs multiples.
PropertyId chaîne Pour chaque propriété dans la collection MultiValueExtendedProperties spécifiez ceci pour identifier la propriété. Il doit obéir à l'un des formats pris en charge pour les propriétés étendues à valeurs multiples. Obligatoire.
Valeur Collection(string) Pour chaque propriété dans la collection MultiValueExtendedProperties, spécifiez les valeurs de cette propriété. Obligatoire.

Exemple de demande

Le premier exemple crée un nouvel événement et une propriété étendue à valeur simple. En dehors des propriétés que vous incluez normalement pour un nouvel événement, le corps de la requête inclut le tableau SingleValueExtendedProperties qui contient une propriété étendue à valeur simple et les éléments suivants pour la propriété :

  • PropertyId spécifie le type de propriété comme string, le GUID et la propriété nommée Fun.
  • Value spécifie Food en tant que valeur de la propriété Fun.
POST https://outlook.office.com/api/v2.0/me/events

Content-Type: application/json

{
  "Subject": "Celebrate Thanksgiving",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together!"
  },
  "Start": {
      "DateTime": "2015-11-26T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-26T23:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    }
  ],
  "SingleValueExtendedProperties": [
     {
           "PropertyId":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "Value":"Food"
     }
  ]
}

Exemple de réponse

Une réponse correcte est indiquée par un code de réponse HTTP 201 Created et inclut le nouvel événement dans le corps de la réponse, semblable à la réponse de créer simplement un événement. La réponse n’inclut pas les propriétés étendues nouvellement créées.

Pour voir la propriété étendue nouvellement créée, développez l’élément avec la propriété étendue.

Exemple de demande

Le second exemple crée une propriété étendue à valeurs multiples dans un nouvel événement, tous dans la même opération POST. En dehors des propriétés que vous incluez normalement pour un nouvel événement, le corps de la requête inclut le tableau MultiValueExtendedProperties qui contient une propriété étendue.

Le corps de la requête inclut les éléments suivants pour cette propriété étendue à valeurs multiples :

  • PropertyId qui spécifie la propriété sous la forme d’un tableau de chaînes avec le GUID spécifié et le nom Recreation.
  • Value qui spécifie Recreation sous la forme d’un tableau de 3 valeurs de chaîne ["Food", "Hiking", "Swimming"].
POST https://outlook.office.com/api/v2.0/me/events

Content-Type: application/json

{
  "Subject": "Family reunion",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together this Thanksgiving!"
  },
  "Start": {
      "DateTime": "2015-11-26T09:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-29T21:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "Lauren@contoso.com",
        "Name": "Lauren Solis"
      },
      "Type": "Required"
    }
  ],
  "MultiValueExtendedProperties": [
     {
           "PropertyId":"StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
           "Value": ["Food", "Hiking", "Swimming"]
     }
  ]
}

Exemple de réponse

Une réponse correcte est indiquée par un code de réponse HTTP 201 Created et inclut le nouvel événement dans le corps de la réponse, semblable à la réponse de créer simplement un événement. La réponse n’inclut pas les propriétés étendues nouvellement créées.

Pour voir la propriété étendue nouvellement créée, développez l’élément avec la propriété étendue.

Développez l'élément avec la propriété étendue

Obtenez une instance d'une ressource prise en charge développée avec la propriété étendue qui est spécifiée par un filtre sur le PropertyId.

La chaîne {propertyId_value} que vous spécifiez dans le filtre pour le PropertyId doit suivre l'un des formats PropertyId pris en charge. Veillez à appliquer l’ encodage URL aux espaces dans la chaîne de filtre.

Développez l'élément avec des propriétés étendues à valeur simple correspondantes

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Développez un élément avec des propriétés étendues à valeurs multiples correspondantes

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Étendue minimale requise

L’une des étendues en lecture suivantes, correspondant à la ressource ciblée :

Exemple de demande

Le premier exemple obtient et développe le message spécifié en incluant une propriété étendue à valeur simple. Le filtre renvoie la propriété étendue qui a son PropertyId correspondant à la chaîne String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (avec l’encodage d’URL supprimé pour faciliter la lecture).

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')?$expand=SingleValueExtendedProperties($filter=PropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')

Exemple de réponse

En cas de succès, un code de réponse HTTP 200 OK est renvoyé.

Le corps de la réponse inclut toutes les propriétés de la propriété étendue et du message spécifié qui ont été renvoyées par le filtre.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
    "Id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
    "CreatedDateTime": "2015-11-11T02:41:24Z",
    "LastModifiedDateTime": "2015-12-09T04:07:57Z",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H",
    "Categories": [
    ],
    "ReceivedDateTime": "2015-11-11T02:41:24Z",
    "SentDateTime": "2015-11-11T02:41:24Z",
    "HasAttachments": false,
    "InternetMessageId": "<SN2SR0101MB002977E7C30F9CA9AA55961484130@SN2SR0101MB0029.contoso.com>",
    "Subject": "RE: Talk about emergency prep",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=iso-8859-1\">\r\n<style type=\"text/css\" style=\"\">\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n</style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<hr tabindex=\"-1\" style=\"display:inline-block; width:98%\">\r\n<div id=\"divRplyFwdMsg\" dir=\"ltr\"><font face=\"Calibri, sans-serif\" color=\"#000000\" style=\"font-size:11pt\"><b>From:</b> Christine Irwin<br>\r\n<b>Sent:</b> Sunday, November 8, 2015 12:28:31 AM<br>\r\n<b>To:</b> Terrie Barrera<br>\r\n<b>Subject:</b> Talk about emergency prep<br>\r\n<b>When:</b> Sunday, November 8, 2015 7:00 PM-8:00 PM.<br>\r\n<b>Where:</b> The Commons</font>\r\n<div>&nbsp;</div>\r\n</div>\r\n<div>\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt; color:#000000; background-color:#FFFFFF; font-family:Calibri,Arial,Helvetica,sans-serif\">\r\n<p>Please see the attached before you come to the meeting.<br>\r\n</p>\r\n</div>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "________________________________",
    "Importance": "Normal",
    "ParentFolderId": "AQMkAGE1M2jgxCloXP1JupQN7j5uzzwAAAIBDwAAAA==",
    "Sender": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "From": null,
    "ToRecipients": [
        {
            "EmailAddress": {
                "Name": "Christine Irwin",
                "Address": "christine@contoso.com"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVlLTY0YjcxZWUzNTE1MAAQAHWT1sRiMChEmlQCIZUadoU=",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsRead": true,
    "IsDraft": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACHsLqWAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "HashtagDetailsPreview": null,
    "LikesPreview": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "UnsubscribeData": [
    ],
    "UnsubscribeEnabled": false,
    "SingleValueExtendedProperties@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/SingleValueExtendedProperties",
    "SingleValueExtendedProperties": [
        {
            "PropertyId": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "Value": "Green"
        }
    ]
}

Exemple de demande

Le deuxième exemple obtient et développe l'événement spécifié en incluant une propriété étendue à valeurs multiples. Le filtre renvoie la propriété étendue qui a son PropertyId correspondant à la chaîne StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation (avec l’encodage d’URL supprimé pour faciliter la lecture).

GET https://outlook.office.com/api/v2.0/me/events('AAMkAGE1M2_bs88AACbuFiiAAA=')?$expand=MultiValueExtendedProperties($filter=PropertyId%20eq%20'StringArray%20{66f5a359-4659-4830-9070-00050ec6ac6e}%20Name%20Recreation')

Exemple de réponse

En cas de succès, un code de réponse HTTP 200 OK est renvoyé.

Le corps de la réponse inclut toutes les propriétés de la propriété étendue et de l’événement spécifié renvoyées par le filtre.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE1M2_bs88AACbuFiiAAA=')",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAAm8k15A==\"",
    "Id": "AAMkAGE1M2_bs88AACbuFiiAAA=",
    "CreatedDateTime": "2015-12-09T05:18:05.9477979Z",
    "LastModifiedDateTime": "2015-12-09T05:18:06.197802Z",
    "ChangeKey": "mODEKWhc/Um6lA3uPm7PPAAAm8k15A==",
    "Categories": [
    ],
    "OriginalStartTimeZone": "Pacific Standard Time",
    "OriginalEndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "04000000828A332796D9",
    "ReminderMinutesBeforeStart": 15,
    "IsReminderOn": true,
    "HasAttachments": false,
    "Subject": "Family reunion",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nLet's get together this Thanksgiving!\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "Let's get together this Thanksgiving!",
    "Importance": "Normal",
    "Sensitivity": "Normal",
    "Start": {
        "DateTime": "2015-11-26T17:00:00.0000000",
        "TimeZone": "UTC"
    },
    "End": {
        "DateTime": "2015-11-30T05:00:00.0000000",
        "TimeZone": "UTC"
    },
    "Location": {
        "DisplayName": ""
    },
    "IsAllDay": false,
    "IsCancelled": false,
    "IsOrganizer": true,
    "Recurrence": null,
    "ResponseRequested": true,
    "SeriesMasterId": null,
    "ShowAs": "Busy",
    "Type": "SingleInstance",
    "Attendees": [
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Terrie Barrera",
                "Address": "Terrie@contoso.com"
            }
        },
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Lauren Solis",
                "Address": "Lauren@contoso.com"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACbuFiiAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "MultiValueExtendedProperties@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events('AAMkAGE1M2_bs88AACbuFiiAAA%3D')/MultiValueExtendedProperties",
    "MultiValueExtendedProperties": [
        {
            "PropertyId": "StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
            "Value": [
                "Food",
                "Hiking",
                "Swimming"
            ]
        }
    ]
}

Obtenez un élément en appliquant un filtre à la propriété étendue

Obtenez les instances d’une ressource prise en charge qui ont la propriété étendue spécifiée par un filtre sur PropertyId et Value. Le filtre est appliqué à toutes les instances de la ressource dans la boîte aux lettres de l’utilisateur connecté. Ce filtrage prend en charge les propriétés étendues à valeur simple, mais pas celles à valeurs multiples.

La chaîne {propertyId_value} que vous spécifiez dans le filtre pour le PropertyId doit suivre l'un des formats PropertyId pris en charge.

Si {property_value} n’est pas une chaîne, veillez à convertir ep/value explicitement au type de données Edm approprié lors de la comparaison avec {property_value}. Voir des exemples de requêtes pour les types de propriétés qui ne sont pas en chaîne ci-dessous pour des exemples de telles conversions.

Veillez à appliquer l’encodage URL aux caractères suivants dans la chaîne de filtre. Il s’agit des deux-points, de la barre oblique et de l’espace.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/events?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/contacts?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/tasks?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/calendars?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

Étendue minimale requise

L’une des étendues en lecture suivantes, correspondant à la ressource ciblée :

Exemple de demande

Le premier exemple obtient les messages qui possèdent la propriété étendue à valeur simple spécifiée dans le filtre. Le filtre renvoie la propriété étendue qui a :

  • Son Propertyid correspondant à la chaîne String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (avec l'encodage URL supprimé ici pour une meilleure lecture).
  • Sa valeur qui est Green.
GET https://outlook.office.com/api/v2.0/Me/Messages?$filter=SingleValueExtendedProperties%2FAny(ep%3A%20ep%2FPropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2FValue%20eq%20'Green')

Les deux exemples suivants montrent comment obtenir des messages qui présentent des propriétés étendues à valeur unique de type autre qu’une chaîne. Pour faciliter la lecture, ils ne comportent pas le codage URL requis. L’exemple suivant montre un filtre qui recherche la propriété étendue possédant les éléments suivants :

  • Son PropertyId correspondant à la chaîne CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid.
  • Sa Valeur étant le GUID b9cf8971-7d55-4b73-9ffa-a584611b600b. Pour comparer la valeur de la propriété avec un GUID, convertissez ep/Value en Edm.Guid.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/Value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))

Le troisième et dernier exemple montre un filtre qui recherche la propriété étendue possédant les éléments suivants :

  • Son PropertyId correspondant à la chaîne Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete.
  • Sa Valeur est égale au nombre entier 12. Pour comparer la valeur de propriété avec un nombre entier, convertissez ep/Value en Edm.Int32.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/Value, Edm.Int32) eq 12)

Exemple de réponse

En cas de réussite, la réponse est indiquée par un code de réponse HTTP 200 OK et le corps de la réponse comprend toutes les propriétés des messages dont la propriété étendue correspond au filtre. Le corps de la réponse est semblable à celui de la réponse reçue lors de l’obtention d’une collection d’objets « message ». La réponse n’inclut pas la propriété étendue correspondante.

Étapes suivantes

Que vous soyez prêt à commencer à créer une application ou que vous souhaitiez simplement en apprendre plus, nous avons ce qu’il vous faut.

Ou, pour en savoir plus sur l’utilisation de la plateforme Office 365 :