Utiliser l’API Recherche Microsoft pour rechercher des messages Outlook

  • Article

Utilisez l’API Recherche Microsoft dans Microsoft Graph pour rechercher des informations dans des messages électroniques, renvoyer des messages classés par pertinence et afficher une expérience de recherche dédiée. La recherche s’applique au corps et aux pièces jointes des messages dans la boîte aux lettres de l’utilisateur connecté.

Attention

Le schéma de l’API de recherche a changé dans la version bêta. Certaines propriétés d’une demande de recherche et d’une réponse ont été renommées ou supprimées. Pour plus d’informations, consultez Avertissement de dépréciation de modification de schéma. Les exemples de cette rubrique montrent le schéma à jour.

Une requête de recherche peut inclure des filtres que les utilisateurs finaux entrent dans la zone de texte Rechercher dans Outlook.

Les résultats de la recherche de message sont triés par receivedDateTime dans l’ordre décroissant.

La recherche de messages s’applique aux comptes professionnels ou scolaires. Les utilisateurs peuvent rechercher leur propre boîte aux lettres, mais pas dans les boîtes aux lettres déléguées. Pour plus d’informations, consultez Limitations connues.

La recherche de messages recherche également les pièces jointes. Les types de fichiers pris en charge pour la recherche de pièces jointes de message sont les mêmes que ceux de la recherche SharePoint Online.

Exemple 1 : Rechercher des messages dans la boîte aux lettres d’un utilisateur

L’exemple suivant interroge les messages de la boîte aux lettres de l’utilisateur connecté qui contiennent la chaîne « contoso » dans n’importe quelle partie du message (le nom de l’expéditeur, l’objet, le corps du message ou toutes les pièces jointes). La requête retourne les 25 premiers résultats. Les résultats de la recherche sont classés par DateTime décroissant.

Demande

POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "message"
      ],
      "query": {
        "queryString": "contoso"
      },
      "from": 0,
      "size": 25
    }
  ]
}

Réponse

Voici un exemple de réponse, qui contient un message qui correspond au critère de recherche.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
  "value": [
    {
      "searchTerms": [
        "contoso"
      ],
      "hitsContainers": [
        {
          "total": 1,
          "moreResultsAvailable": false,
          "hits": [
            {
              "hitId": "ptWLQ4o6HYpQg8xmAAATzOzRAAA=",
              "rank": 1,
              "summary": "Here is a summary of your messages from last week",
              "resource": {
                "@odata.type": "#microsoft.graph.message",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "receivedDateTime": "2019-10-07T10:00:09Z",
                "sentDateTime": "2019-10-07T09:59:52Z",
                "hasAttachments": false,
                "subject": "Weekly digest: Microsoft 365 changes",
                "bodyPreview": "Here is a summary of your messages from last week -   New Feature: Live captions in English-US a",
                "importance": "normal",
                "replyTo": [
                  {
                    "emailAddress": {
                      "name": "Goncalo Torres"
                    }
                  }
                ],
                "sender": {
                  "emailAddress": {
                    "name": "Office365 Message Center",
                    "address": "gtorres@contoso.com"
                  }
                },
                "from": {
                  "emailAddress": {
                    "name": "Office365 Message Center",
                    "address": "gtorres@contoso.com"
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Exemple 2 : Rechercher les principaux messages de résultats

L’exemple suivant utilise la requête de recherche présentée dans l’exemple 1 et trie les résultats par pertinence.

Demande

POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "message"
      ],
      "query": {
        "queryString": "contoso"
      },
      "from": 0,
      "size": 15,
      "enableTopResults": true
    }
  ]
}

Réponse

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
  "value": [
    {
      "searchTerms": [
        "contoso"
      ],
      "hitsContainers": [
        {
          "total": 1,
          "moreResultsAvailable": false,
          "hits": [
            {
              "hitId": "ptWLQ4o6HYpQg8xmAAATzOzRAAA=",
              "rank": 1,
              "summary": "Here is a summary of your messages from last week",
              "resource": {
                "@odata.type": "#microsoft.graph.message",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "receivedDateTime": "2019-10-07T10:00:09Z",
                "sentDateTime": "2019-10-07T09:59:52Z",
                "hasAttachments": false,
                "subject": "Weekly digest: Microsoft 365 changes",
                "bodyPreview": "Here is a summary of your messages from last week -   New Feature: Live captions in English-US a",
                "importance": "normal",
                "replyTo": [
                  {
                    "emailAddress": {
                      "name": "Goncalo Torres"
                    }
                  }
                ],
                "sender": {
                  "emailAddress": {
                    "name": "Office365 Message Center",
                    "address": "gtorres@contoso.com"
                  }
                },
                "from": {
                  "emailAddress": {
                    "name": "Office365 Message Center",
                    "address": "gtorres@contoso.com"
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Limitations connues

  • Vous pouvez accéder uniquement à la boîte aux lettres de l’utilisateur connecté. La recherche de boîtes aux lettres déléguées n’est pas prise en charge.
  • Pour les messages, la propriété total du type searchHitsContainer contient le nombre de résultats sur la page, et non le nombre total de résultats correspondants.
  • Le tri des résultats n’est pas pris en charge pour les événements. Une clause de tri dans la demande renvoie un code d’erreur de requête incorrecte dans la réponse.

Prochaines étapes