Référence des API REST d’extensions de données Office 365 (version 2.0)

  • Article

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

L'API REST des extensions de données Office 365 permet aux applications de stocker dynamiquement des données personnalisées dans un message, un événement ou un contact du compte de l'utilisateur. 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 Office 365 et sélectionnez la version souhaitée.

Vue d’ensemble

Une extension de données dans l'API REST Outlook est un type ouvert OData v4 qui contient des propriétés que vous pouvez spécifier lors de l'exécution. Vous pouvez utiliser l'API des extensions de données pour étendre une instance d'un type d'entité déjà défini dans le modèle EDM (Entity Data Model) - un message, un événement ou un contact - en spécifiant dynamiquement des propriétés et des valeurs personnalisées dans une charge utile JSON. Cela rend la définition de ces types d'entités plus flexible, ce qui vous permet d'économiser le temps de définir de nouveaux types d'entités uniquement à cette fin.

La propriété extensionName est la seule propriété définie pour toutes les extensions. Pour vérifier que les noms d’extension sont uniques, utilisez une recherche DNS (Domain Name System) inversée qui dépend de votre propre domaine, par exemple Com.Contoso.Contact. N’utilisez pas le domaine Microsoft dans un nom d’extension.

Étant donné qu'une extension est un type ouvert, vous pouvez spécifier des données supplémentaires spécifiques à une instance d'une entité. Par exemple, vous pouvez créer une extension pour les contacts professionnels individuels qui suit les données personnalisées telles que le nom de l'entreprise et le référent initial, et spécifier les données dans la charge utile JSON comme suit :

POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions
{
   @odata.type: "Microsoft.OutlookServices.OpenTypeExtension",  
   "ExtensionName": "Com.Contoso.Customer",
   "CompanyName": "Alpine Skis",
   "InitialReferrer":  "Robin McCall"
}

Vous pouvez utiliser l'API des extensions de données pour effectuer des opérations CRUD sur une ressource nouvelle ou existante. En savoir plus sur les opérations prises en charge.

Pour plus d'informations sur le type ouvert OData, consultez la documentation OData v4 sur OData.org.

Utilisation de l'API REST des extensions de données

Des extensions de données ou des propriétés étendues ?

Les extensions de données sont la solution recommandée pour la plupart des scénarios impliquant le stockage et l'accès à des données personnalisées. Si, toutefois, 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, vous pouvez utiliser propriétés étendues et son API REST. Vous pouvez vérifier les propriétés exposées par les métadonnées sur https://outlook.office.com/api/{version}/$metadata, en remplaçant {version} par v2.0, beta, etc., pour la version de votre choix.

Authentification

Comme les autres API REST Outlook, pour chaque demande adressée à l'API des extensions de données, vous devez inclure un jeton d'accès valide. Pour obtenir un jeton d'accès, vous devez avoir enregistré et identifié votre application et obtenu l'autorisation appropriée.

Vous pouvez en savoir plus à propos de certaines options d'enregistrement et d'autorisation simplifiées pour vous. Gardez cela en tête lorsque vous procédez aux opérations spécifiques dans l'API des extensions de données.

Ressources REST prises en charge

Vous pouvez créer des extensions pour les instances des ressources suivantes dans le point de terminaison REST Outlook :

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 v2.0 et bêta :

https://outlook.office.com/api/v2.0/

https://outlook.office.com/api/beta/

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
contact_id chaîne L'ID du contact.
event_id chaîne L'ID de l’événement.
message_id chaîne L'ID du message.

Voir Utiliser l'API REST Outlook pour plus d'informations communes à tous les sous-ensembles de l'API REST Outlook et de l'API REST des extensions de données Office 365.

Opérations d’extension

Créer une extension dans un élément existant

Créez une extension et ajoutez des propriétés personnalisées pour l’instance spécifiée d’une ressource. La ressource peut être un message, un événement de calendrier ou un contact dans Office 365 ou Outlook.com. Les données dans la charge utile JSON peuvent être des types primitifs ou des tableaux de types primitifs.

Pour créer une extension pour chacune des ressources prises en charge :

POST https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions

Étendue minimale requise

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

Paramètre Type Description
Paramètres de corps
ExtensionName chaîne Un identificateur de texte unique pour une extension. Obligatoire.

Exemple de requête

Cet exemple crée une extension pour le message spécifié. Le corps de la requête comprend les éléments suivants pour l’extension :

  • Le type Microsoft.OutlookServices.OpenTypeExtension qui est défini comme un type ouvert OData dans les métadonnées de l'API REST Outlook.
  • Le nom de l’extension « Com.Contoso.Referral ».
  • Données supplémentaires à stocker en tant que propriétés personnalisées dans la charge utile JSON : CompanyName, DealValue, et ExpirationDate qui contiennent des types primitifs, et TopModels et TopSalespersons qui contiennent des tableaux de types primitifs.
POST https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions

Content-Type: application/json

{ 
  "@odata.type" : "Microsoft.OutlookServices.OpenTypeExtension", 
  "ExtensionName" : "Com.Contoso.Referral", 
  "CompanyName" : "Wingtip Toys",
  "DealValue@odata.type": "#Int64", 
  "DealValue" : 500050, 
  "ExpirationDate" : "2015-12-03T10:00:00.000Z",
  "TopModels": [
     3001,
     4002,
     5003
  ],
  "TopSalespersons": [
     "Dana Swope",
     "Fanny Downs",
     "Randi Welch"
  ]
}

Exemple de réponse

En cas de succès, la réponse indique un code de réponse HTTP 201 Created.

Le corps de la réponse inclut les éléments suivants pour la nouvelle extension :

  • La propriété par défaut extensionName.
  • La propriété id avec le nom complet de Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
  • Les données personnalisées à stocker.
{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue@odata.type": "#Int64",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "TopModels@odata.type": "#Collection(Int32)",
    "TopModels": [
      3001,
      4002,
      5003
    ],
    "TopSalespersons@odata.type": "#Collection(String)",
    "TopSalespersons": [
      "Dana Swope",
      "Fanny Downs",
      "Randi Welch"
    ]
}

Créer une extension dans un nouvel élément

Créez une ou plusieurs extensions lors de la création d'une nouvelle instance d'une ressource, toutes dans le même appel POST et ajoutez des propriétés personnalisées à l'extension. La ressource peut être un message, un événement de calendrier ou un contact dans Office 365 ou Outlook.com. Les données dans la charge utile JSON peuvent être des types primitifs ou des tableaux de types primitifs.

Pour créer une extension pour chacune des ressources prises en charge, effectuez un appel POST similaire à la création de cette ressource et incluez une extension dans le corps de la demande 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

Étendue minimale requise

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

Paramètre Type Description
Paramètres de corps
ExtensionName chaîne Un identificateur de texte unique pour une extension. Obligatoire.

Exemple de requête

Cet exemple crée un message et une extension dans le même appel. Le corps de la demande comprend les éléments suivants :

  • Les propriétés subject, bodyet toRecipients par défaut d’un nouveau message.
  • Pour l’extension :
    • Le type Microsoft.OutlookServices.OpenTypeExtension qui est défini comme un type ouvert OData dans les métadonnées de l'API REST Outlook.
    • Le nom de l’extension « Com.Contoso.Referral ».
    • Données supplémentaires à stocker en tant que propriétés personnalisées dans la charge utile JSON : CompanyName, ExpirationDate, et DealValue qui contiennent des types primitifs, et TopModels et TopSalespersons qui contiennent des tableaux de types primitifs.
POST https://outlook.office.com/api/v2.0/me/messages

Content-Type: application/json

{
  "Subject": "Annual review",
  "Body": {
    "ContentType": "HTML",
    "Content": "You should be proud!"
  },
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com"
      }
    }
  ],
  "Extensions": [
    {
      "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Exemple de réponse

En cas de succès, la réponse indique un code de réponse HTTP 201 Created.

Le corps de la réponse inclut les propriétés du nouveau message et les éléments suivants pour la nouvelle extension :

  • La propriété id avec le nom complet de Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
  • La propriété par défaut extensionName spécifiée dans la demande.
  • Les données personnalisées spécifiées dans la demande stockée sous la forme de propriétés personnalisées.
{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')",
  "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj\"",
  "Id": "AAMkAGEbs88AAB84uLuAAA=",
  "CreatedDateTime": "2015-10-30T03:03:43Z",
  "LastModifiedDateTime": "2015-10-30T03:03:43Z",
  "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj",
  "Categories": [ ],
  "ReceivedDateTime": "2015-10-30T03:03:43Z",
  "SentDateTime": "2015-10-30T03:03:43Z",
  "HasAttachments": false,
  "Subject": "Annual review",
  "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\nYou should be proud!\r\n</body>\r
\n</html>\r\n"
  },
  "BodyPreview": "You should be proud!",
  "Importance": "Normal",
  "ParentFolderId": "AQMkAGEwAAAIBDwAAAA==",
  "Sender": null,
  "From": null,
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com",
        "Name": "John Doe"
      }
    }
  ],
  "CcRecipients": [ ],
  "BccRecipients": [ ],
  "ReplyTo": [ ],
  "ConversationId": "AAQkAGEFGugh3SVdMzzc=",
  "IsDeliveryReceiptRequested": false,
  "IsReadReceiptRequested": false,
  "IsRead": true,
  "IsDraft": true,
  "WebLink": "https://outlook.office.com/owa/?
ItemID=AAMkAGEbs88AAB84uLuAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
  "MentionedMe": null,
  "Mentioned": [ ],
  "InferenceClassification": "Focused",
  "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages
('AAMkAGEbs88AAB84uLuAAA%3D')/Extensions",
  "Extensions": [
    {
      "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
      "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels@odata.type": "#Collection(Int32)",
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons@odata.type": "#Collection(String)",
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Obtenir une extension

Obtenez une extension par nom ou ID dans l'instance spécifiée d'une ressource. La ressource peut être un message, un événement de calendrier ou un contact dans Office 365 ou Outlook.com.

L’obtention de l’extension par son nom ou son ID renvoie le même corps de réponse.

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

Étendue minimale requise

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

Paramètre Type Description
Paramètre d’URL
extensionId chaîne Cela peut être un nom d'extension qui est un identificateur de texte unique parmi toutes les extensions dans une instance de ressource, ou un nom qualifié complet qui concatène le type d'extension et l'identificateur de texte unique. Le nom qualifié complet est renvoyé dans la propriété id lorsque vous créez l'extension. Obligatoire.

Exemple de requête

Le premier exemple fait référence à une extension par son nom et obtient l’extension dans le message spécifié.

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

Le deuxième exemple fait référence à une extension par son ID (nom qualifié complet) et obtient l’extension dans le message spécifié.

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Exemple de réponse

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

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00Z"
}

Obtenir l'élément étendu avec l'extension

Obtenir une instance d'une ressource étendue avec l'extension spécifiée par un filtre sur le Id. La ressource peut être un message, un événement de calendrier ou un contact dans Office 365 ou Outlook.com.

Vous pouvez filtrer sur le Id par rapport au nom de l'extension ou au nom complet, puis avoir l'instance étendue avec l'extension, comme indiqué ci-dessous. Veillez à appliquer l’ encodage URL aux espaces dans la chaîne de filtre.

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

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

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

Étendue minimale requise

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

Paramètre Type Description
Paramètre d’URL
extensionId chaîne Cela peut être un nom d'extension qui est un identificateur de texte unique parmi toutes les extensions dans une instance de ressource, ou un nom qualifié complet qui concatène le type d'extension et l'identificateur de texte unique. Le nom qualifié complet est renvoyé dans la propriété id lorsque vous créez l'extension. Obligatoire.

Exemple de requête

L’exemple suivant obtient et étend le message spécifié en incluant l’extension renvoyée par un filtre. Le filtre renvoie l’extension qui a son Id correspondant à un nom qualifié complet.

Pour votre commodité, la demande est illustrée ci-dessous avec l’encodage URL du caractère réservé, espace.

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')?$expand=Extensions($filter=Id%20eq%20'Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Exemple de réponse

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

Le corps de la réponse inclut toutes les propriétés du message spécifié et l'extension renvoyée 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('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
    "Id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
    "Categories": [
    ],
    "CreateDateTime": "2015-06-19T02:03:31Z",
    "LastModifiedDateTime": "2015-08-13T02:28:00Z",
    "Subject": "Attached is the requested info",
    "BodyPreview": "See the images attached.",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "Importance": "Normal",
    "HasAttachments": true,
    "ParentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
    "From": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "Sender": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "ToRecipients": [
        {
            "EmailAddress": {
                "Address": "wendy@contoso.com",
                "Name": "Wendy Molina"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
    "ReceivedDateTime": "2015-06-19T02:05:04Z",
    "SentDateTime": "2015-06-19T02:04:59Z",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsDraft": false,
    "IsRead": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Users('desmond40contoso.com')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions", 
    "Extensions": [ 
      { 
        "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
        "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
        "ExtensionName": "Com.Contoso.Referral",
        "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
        "CompanyName": "Wingtip Toys",
        "DealValue": 500050,
        "ExpirationDate": "2015-12-03T10:00:00Z"
      }
     ]
}

Rechercher et étendre des éléments avec une extension

Vous pouvez trouver des instances d'une ressource contenant une extension correspondant à un filtre. En outre, dans la même requête, vous pouvez obtenir ces instances étendues avec l'extension. Les requêtes de cette section trouvent de telles instances, étendent et incluent l'extension dans la réponse.

La ressource peut être un message, un événement de calendrier ou un contact dans Office 365 ou Outlook.com.

Vous pouvez filtrer sur le Id par rapport au nom de l'extension ou au nom complet, puis avoir l'instance étendue avec l'extension, comme indiqué ci-dessous. Veillez à appliquer l’ encodage URL aux espaces dans la chaîne de filtre.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/events?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/contacts?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

Étendue minimale requise

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

Paramètre Type Description
Paramètre d’URL
extensionId chaîne Cela peut être un nom d'extension qui est un identificateur de texte unique parmi toutes les extensions dans une instance de ressource, ou un nom qualifié complet qui concatène le type d'extension et l'identificateur de texte unique. Le nom qualifié complet est renvoyé dans la propriété id lorsque vous créez l'extension. Obligatoire.

Exemple de requête

L’exemple suivant recherche dans tous les messages de la boîte de réception de l’utilisateur connecté pour trouver ceux qui contiennent une extension correspondant à un filtre et les étend en incluant l’extension. Le filtre renvoie les extensions qui ont le Id correspondant au nom de l'extension Com.Contoso.Referral.

Pour votre commodité, la demande est illustrée ci-dessous avec l’encodage URL du caractère réservé, espace.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id%20eq%20'Com.Contoso.Referral')&$expand=Extensions($filter=Id%20eq%20'Com.Contoso.Referral')

Exemple de réponse

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

Le corps de la réponse inclut tous les messages ayant une extension correspondante et toutes les propriétés du message. Dans cet exemple, la réponse contient deux messages.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.EventMessage",
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')",
            "@odata.etag": "W/\"DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn\"",
            "Id": "AAMkADIyDREAAA=",
            "CreatedDateTime": "2016-01-06T02:20:17Z",
            "LastModifiedDateTime": "2016-01-13T02:13:54Z",
            "ChangeKey": "DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:18Z",
            "SentDateTime": "2016-01-06T02:20:18Z",
            "HasAttachments": false,
            "InternetMessageId": "<BY1PR19MB0023E92E0B43F5E268406F0DF5F40@BY1PR19MB0023.namprd19.prod.outlook.com>",
            "Subject": "Accepted: Latin American Product Manual Group",
            "Body": {
                "ContentType": "Text",
                "Content": ""
            },
            "BodyPreview": "",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAAEJAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyWejUoYAg=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": true,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyDREAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "MeetingMessageType": "MeetingAccepted",
            "StartDateTime": {
                "DateTime": "2015-01-05T19:00:00.0000000",
                "TimeZone": "UTC"
            },
            "EndDateTime": {
                "DateTime": "2015-01-05T20:30:00.0000000",
                "TimeZone": "UTC"
            },
            "Location": {
                "DisplayName": "Mt. Adams"
            },
            "Type": "SeriesMaster",
            "Recurrence": {
                "Pattern": {
                    "Type": "RelativeMonthly",
                    "Interval": 2,
                    "Month": 0,
                    "DayOfMonth": 0,
                    "DaysOfWeek": [
                        "Monday"
                    ],
                    "FirstDayOfWeek": "Sunday",
                    "Index": "First"
                },
                "Range": {
                    "Type": "NoEnd",
                    "StartDate": "2015-01-05",
                    "EndDate": "0001-01-01",
                    "RecurrenceTimeZone": "tzone://Microsoft/Utc",
                    "NumberOfOccurrences": 0
                }
            },
            "IsOutOfDate": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyDREAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500300,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ],
            "Event@odata.associationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')/$ref",
            "Event@odata.navigationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')"
        },
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')",
            "@odata.etag": "W/\"CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq\"",
            "Id": "AAMkADIyAHVAAA=",
            "CreatedDateTime": "2016-01-06T02:20:02Z",
            "LastModifiedDateTime": "2016-01-13T02:24:50Z",
            "ChangeKey": "CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:02Z",
            "SentDateTime": "2016-01-06T02:20:01Z",
            "HasAttachments": false,
            "InternetMessageId": "<CY1PR19MB0032531C620A46068FDDD45DE3F40@CY1PR19MB0032.namprd19.prod.outlook.com>",
            "Subject": "International Launch Planning for XT2000",
            "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\nWe will be ready to ship XT 2000 on 10/1, how's the International launch plan going?<br>\r\n<div style=\"display:inline-block\">\r\n<table border=\"0\" cellspacing=\"0\" style=\"background-color:#F4F4F4\">\r\n<tbody>\r\n<tr>\r\n<td style=\"padding:20px; font-size:12px; color:#666666\">You're receiving this message because you're a subscribed member of the Engineering group.<br>\r\n<a href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=conversations&amp;source=EscalatedMessage\">View group conversations</a> |\r\n<a href=\"https://adatumltd.sharepoint.com/_layouts/groupstatus.aspx?id=dbcbe107-6244-40ba-b0f1-1c46ad35435d&amp;target=documents\">\r\nView group files</a> | <a id=\"BD5134C6-8D33-4ABA-A0C4-08581FDF89DB\" href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=unsubscribe&amp;source=EscalatedMessage\">\r\nUnsubscribe</a></td>\r\n</tr>\r\n</tbody>\r\n</table>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "BodyPreview": "We will be ready to ship XT 2000 on 10/1, how's the International launch plan going?\r\nYou're receiving this message because you're a subscribed member of the Engineering group.\r\nView group conversations | View group files | Unsubscribe",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAEMAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "Engineering",
                    "Address": "engineering@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "Garret Vargas",
                    "Address": "GarretV@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyLESZnSPc=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": false,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyAHVAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyAHVAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500050,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ]
        }
    ]
}

Ajouter ou modifier des données dans une extension

Mettre à jour une extension avec les propriétés dans le corps de la demande :

  • Si une propriété dans le corps de la requête correspond au nom d’une propriété existante dans l’extension, les données dans l’extension sont mises à jour.
  • Sinon, cette propriété et ses données sont ajoutées à l’extension.

La ressource peut être un message, un événement de calendrier ou un contact dans Office 365 ou Outlook.com. Il peut être référencé par son nom ou son ID, et l'une ou l'autre manière renvoie la même réponse. Les données dans la charge utile JSON peuvent être des types primitifs ou des tableaux de types primitifs.

PATCH https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

Étendue minimale requise

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

Paramètre Type Description
Paramètre d’URL
extensionId chaîne Cela peut être un nom d'extension qui est un identificateur de texte unique parmi toutes les extensions dans une instance de ressource, ou un nom qualifié complet qui concatène le type d'extension et l'identificateur de texte unique. Le nom qualifié complet est renvoyé dans la propriété id lorsque vous créez l'extension. Obligatoire.
Paramètres de corps
ExtensionName chaîne Un identificateur de texte unique pour une extension. Obligatoire.

Exemple de requête

Chacun des deux exemples de cette section utilise l'extension dans l' exemple Obtenir une extension au dessus. Le premier fait référence à l'extension par son nom, le second par son ID. Leurs corps de demande et leurs réponses sont les mêmes.

Chaque exemple met à jour l' extension ci-dessus en :

  • modifiant CompanyName en remplaçant Wingtip Toys par ; Wingtip Toys (USA)
  • modifiant DealValue en remplaçant 500050 par ; 500100
  • Ajout de nouvelles données en tant que propriété personnalisée Updated

Cet exemple fait référence à l'extension par son nom :

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Cet exemple fait référence à l’extension par son ID (nom complet) :

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Exemple de réponse

En cas de réussite la réponse indique un code de réponse HTTP 200 OK et l’extension mise à jour dans le corps de la réponse.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": 500100,
    "ExpirationDate": "2015-12-03T10:00:00Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Supprimer une extension

Supprimer une extension de l’instance spécifiée d’une ressource. La ressource peut être un message, un événement de calendrier ou un contact dans Office 365 ou Outlook.com.

Pour supprimer une extension dans une instance de chacune des ressources prises en charge :

DELETE https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extension_name}')

Étendue minimale requise

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

Paramètre Type Description
Paramètres d’URL
extension_name chaîne Un identificateur de texte unique pour une extension. Obligatoire.

Exemple de requête

Le premier exemple fait référence à une extension par son nom et supprime l’extension dans le message spécifié.

DELETE https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

Exemple de réponse

En cas de succès, la réponse indique un code de réponse HTTP 204 No Content.

Entités d'extension

Extension

Type : Microsoft.OutlookServices.Entity

Une entité abstraite avec l'entité Entité comme type de base.

OpenTypeExtension

Type : Microsoft.OutlookServices.Extension

Un type OData v4 ouvert abstrait qui prend en charge la spécification dynamique des propriétés et des données dans une charge utile JSON pour mettre à jour une instance d'un type d'entité.

Propriété Type Description Accessible en écriture ? Filtrable ?
ExtensionName chaîne Nom unique de l'extension. Utilisez un système de nom de domaine inversé basé sur votre propre domaine, par exemple, Com.Contoso.Contact. Oui Non

É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 :