Utiliser l’API Recherche Microsoft pour interroger les données

Important

Les API sous la /beta version de Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur de version .

Vous pouvez utiliser l’API de Recherche Microsoft pour requérir les données Microsoft 365 dans vos applications.

Les demandes de recherche s’exécutent dans le contexte de l’utilisateur connecté, identifié à l’aide d’un jeton d’accès avec des autorisations déléguées.

Attention

Les ressources utilisées dans une demande et une réponse de l’API de recherche Microsoft ont été renommées ou supprimées, ou deviennent obsolètes. En savoir plus sur l’obsolescence. En conséquence, mettez à jour les requêtes de l’API de recherche dans les applications antérieures.

Cas d’utilisation courants

L’API Microsoft Search fournit une méthode requête pour effectuer une recherche dans l’ensemble de vos données dans Microsoft Search, où vous transférez un searchRequest dans le corps de la demande, en définissant les détails de votre recherche.

Cette section répertorie les cas d’utilisation courants de la méthode requête de , en fonction des propriétés et paramètres définis dans le corps requête searchRequest.

Les demandes de recherche s’exécutent pour le compte de l’utilisateur. Les résultats de la recherche sont délimités pour forcer tout contrôle d’accès appliqué aux éléments. Par exemple, dans un contexte des fichiers, les autorisations sur les fichiers sont évaluées dans le cadre de la demande de recherche. Les utilisateurs ne peuvent pas accéder aux autres éléments d’une recherche plutôt qu’à une opération obtenir correspondante avec les mêmes autorisations et contrôle d’accès.

Cas d’utilisation Propriétés à définir dans le corps de la demande de requête
Résultats de la recherche d’étendues basés sur des types d’entités entityTypes
Résultats de la page de et taille
Obtenez les messages les plus pertinents enableTopResults
Obtenir les propriétés sélectionnées fields
Utiliser KQL dans les conditions de requête Requête
Trier les résultats de recherche sort
Affiner les résultats à l’aide d’agrégations aggregations
Rechercher des types personnalisés importés à l’aide de connecteurs contentSources
Demander la correction orthographique queryAlterationOptions
Rechercher dans la disposition de l’affichage (préversion) resultTemplateOptions

Recherche d’étendue basée sur des types d’entités

Définissez l’étendue de la demande de recherche à l’aide de la propriété entityTypes dans la requête charge utile de la demande. Le tableau suivant décrit les types disponibles pour la requête et les autorisations prises en charge pour accéder aux données.

EntityType Étendue d’autorisation requise pour accéder aux éléments Source Commentaire
message Mail.Read, Mail.ReadWrite Exchange Online Messages électroniques.
event Calendars.Read, Calendars.ReadWrite Exchange Online Événements de calendrier.
drive Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint Bibliothèques de documents.
driveItem Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint et OneDrive Fichiers, dossiers, pages et actualités.
list Sites.Read.All, Sites.ReadWrite.All SharePoint et OneDrive Listes. Notez que les bibliothèques de documents sont également renvoyées sous forme de listes.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint et OneDrive Éléments de liste. Notez que les fichiers et les dossiers sont également retournés en tant qu’éléments de liste. listItem est la super classe de driveItem.
site Sites.Read.All, Sites.ReadWrite.All SharePoint Sites dans SharePoint.
externalItem ExternalItem.Read.All Connecteurs Microsoft Graph Tout le contenu géré par l’API connecteurs Microsoft Graph.
person People.Read Exchange Online Contacts personnels et contacts ou objets adressables dans votre organisation.

Résultats de la recherche de pages

Contrôlez la pagination des résultats de la recherche en spécifiant les deux propriétés suivantes dans le corps de demande de la requête :

  • de : un nombre entier indiquant le point de départ 0 pour répertorier les résultats de la recherche sur la page. La valeur par défaut est 0.

  • taille : un nombre entier indiquant le nombre de résultats devant être renvoyés pour une page. La valeur par défaut est 25 résultats. La valeur maximale est de 1 000 résultats.

Notez les limites suivantes si vous effectuez une recherche dans l’entité événement ou message :

  • de doit commencer à zéro dans la première demande de page, sinon les résultats de la requête génèrent un HTTP 400Bad request.
  • Le nombre maximal de résultats par page (taille) est de 25 pour message et événement.

Il n’existe pas de limite supérieure pour les éléments SharePoint ou OneDrive. Une taille de page raisonnable est de 200. Une plus grande taille de page entraîne généralement une latence plus élevée.

Meilleures pratiques :

  • Spécifiez une première page plus petite dans la demande initiale. Par exemple, spécifiez de sous la forme 0, taille comme 25.

  • Paginez les pages suivantes en mettant à jour les propriétés de et taille. Vous pouvez augmenter la taille de la page dans chaque demande suivante. Le tableau ci-dessous vous montre un exemple.

    Page de taille
    1 0 25
    2 25 50
    3 75 75
    4 150 100

Obtenez les messages les plus pertinents

Lorsque vous effectuez une recherche dans l’entité de message , en spécifiant enableTopResults comme true renvoie une liste hybride de messages : les trois premiers messages de la réponse sont triés par pertinence ; les autres messages sont triés par date/heure.

Obtenir les propriétés sélectionnées

Lors de la recherche d’un type d’entité (par exemple, message, événement, lecteur, driveItem, liste, listItem, site, externalItem), ou person, vous pouvez inclure dans les champs propriétés d’entité spécifiques de la propriété pour renvoyer les résultats de la recherche. Cela revient à utiliser l’option de requête système OData, $select dans les demandes REST. Les options de requête ne sont pas prises en charge techniquement par l’API de recherche, car le comportement est exprimé dans le corps du message.

Pour tous ces types d’entités, le fait de spécifier les champs propriété réduit le nombre de propriétés renvoyées dans la réponse, en optimisant la charge utile sur le réseau.

Les entités listItem et externalItem sont les seules prises en charge qui autorisent l’acquisition de champs récupérables étendus configurés dans le schéma. Vous ne pouvez pas extraire de propriétés étendues de toutes les autres entités à l’aide de l’API de recherche.. Par exemple, si vous avez créé un champ récupérable pour externalItem dans le schéma de recherche, ou si vous avez une colonne récupérable personnalisée dans une listItem, vous pouvez récupérer ces propriétés dans la recherche. Pour récupérer une propriété étendue sur un fichier, spécifiez le type de listItem dans la demande.

Si les champs spécifiés dans la requête ne sont pas présents dans le schéma ou ne sont pas marqués comme récupérables, ils ne sont pas retournés dans la réponse. Les champs non valides dans la demande sont ignorés silencieusement.

Si vous ne spécifiez pas de champs dans la demande, vous obtiendrez l’ensemble de propriétés par défaut pour tous les types. Pour les propriétés étendues, listItem et externalItem se comportent différemment lorsqu’aucun champ n’est transmis dans la demande :

  • listItem ne renvoie aucun champ personnalisé.
  • externalItem renvoie tous les champs marqués avec l’attribut retrievable dans le schéma de connecteur Microsoft Graph pour cette connexion particulière.

Prise en charge du langage de requête de mot clé (KQL)

Spécifier des mots clés de texte libre, des opérateurs (par exemple, AND, OR) et les restrictions de propriété dans la syntaxe KQL de la chaîne de requête de recherche (propriété de requête du corps de la demande de la requête). La syntaxe et la commande dépendent des types d’entité (dans la propriété entityTypes) que vous ciblez dans le même corps de la demande de la requête.

En fonction du type d’entité, les propriétés pouvant faire l’objet d’une recherche varient. pour plus de détails, consultez :

Trier les résultats de la recherche

Les résultats de la recherche dans la réponse sont triés dans l’ordre de tri par défaut suivant :

  • message et événement sont triés par date.
  • Tous les types de liens SharePoint, OneDrive, personne et de connecteur sont triés par pertinence.

La méthode de requête vous permet de personnaliser l’ordre de recherche en spécifiant le sortProperties sur le paramètre requests , qui est une collection d’objets searchRequest. Vous pouvez ainsi spécifier la liste d’une ou plusieurs propriétés triables et l’ordre de tri.

Notez que les résultats de tri sont actuellement pris en charge uniquement sur les types SharePoint et OneDrive suivants : driveItem, listItem, list et site.

Les propriétés sur lesquelles les clauses de tri sont appliquées doivent être triables dans le schéma de recherche SharePoint. Si la propriété spécifiée dans la demande n’est pas triable ou n’existe pas, la réponse renvoie une erreur, HTTP 400 Bad Request. Notez que vous ne pouvez pas spécifier de pertinence pour trier les documents à l’aide de sortProperty.

Lorsque vous spécifiez le nom d’un objet sortProperty, vous pouvez utiliser le nom de la propriété du type Microsoft Graph (par exemple, driveItem) ou le nom de la propriété gérée dans l’index de recherche.

Consultez trier les résultats de la recherche pour consulter des exemples qui montrent comment trier les résultats.

Affiner les résultats à l’aide d’agrégations

Les agrégations (également appelées affinements dans SharePoint) constituent un moyen très courant d’améliorer une expérience de recherche. Outre les résultats, ils fournissent un niveau d’informations d’agrégation sur l’ensemble de résultats de recherche correspondant. Par exemple, vous pouvez fournir des informations sur les auteurs les plus représentés des documents correspondant à la requête, ou sur les types de fichiers les plus représentés, etc.

Dans la searchRequest, spécifiez les agrégations à renvoyer en plus des résultats de recherche. La description de chaque agrégation est définie dans la aggregationOption, qui spécifie la propriété sur laquelle l’agrégation doit être calculée, ainsi que le nombre de searchBucket à renvoyer dans la réponse.

Les propriétés sur lesquelles l’agrégation est demandée doivent être utilisable dans une recherche approfondie dans le schéma de recherche SharePoint. Si la propriété spécifiée n’est pas utilisable dans une recherche approfondie ou n’existe pas, la réponse renvoie HTTP 400 Bad Request.

Une fois la réponse renvoyée contenant la collection des objets searchBucket, vous pouvez affiner la requête de recherche uniquement sur les éléments correspondants contenus dans une searchBucket. Pour ce faire, il suffit de renvoyer la valeur aggregationsFilterToken dans la propriété aggregationFilters de la searchRequestsuivante.

Les agrégations sont actuellement prises en charge pour toute propriété utilisable dans une recherche approfondie sur les types SharePoint et OneDrive suivants : driveItem, listItem, list, site, et sur les connecteurs Microsoft GraphexternalItem.

Pour consulter des exemples d’utilisation de l’agrégation afin d’améliorer et de restreindre les résultats de la recherche, consultez Affiner les résultats de recherche.

Demandez la correction orthographique

La correction orthographique est un moyen de traiter les in correspondances entre les fautes de frappe dans une requête d’utilisateur et les mots corrects dans le contenu mis en correspondance. Lorsque des fautes de frappe sont détectées dans la requête utilisateur d’origine, vous pouvez obtenir le résultat de recherche pour la requête utilisateur d’origine ou la requête de remplacement corrigée. Vous pouvez également obtenir les informations de correction orthographique pour les fautes de frappe dans la propriété queryAlterationResponse du searchResponse.

Dans searchRequest, spécifiez les queryAlterationOptions qui doivent être appliquées à la requête pour les corrections orthographiques. Pour plus d'informations sur la propriété queryAlterationOptions, consultez searchAlterationOptions.

Pour consulter des exemples d’utilisation des corrections d’orthographe, consulter Demander une correction orthographique.

Rechercher dans la disposition de l’affichage

L’API de recherche vous permet d’afficher les résultats de recherche à partir de connecteurs, à l’aide de la disposition d’affichage ou du modèle de résultat configuré par l’administrateur informatique pour chaque connecteur. Les modèles de résultats sont Cartes adaptatives, qui sont une combinaison sémantiquement significative de disposition et de données.

Pour obtenir le modèle de résultat dans le searchresponse, vous devez définir true la propriété enableResultTemplate, définie dans le resultTemplateOptions, dans le searchRequest. La réponse comprend un resultTemplateId pour chaque résultat de recherche, qui correspond à l'un des modèles d'affichage inclus dans le dictionnaire resultTemplates inclus dans la réponse.

Pour obtenir des exemples, consultez Utiliser la disposition d’affichage de recherche .

Gestion des erreurs

L’API de recherche renvoie les réponses aux erreurs telles qu’elles sont définies par définition d’objet d’erreur OData, qui sont des objets JSON contenant un code et un message.

Limitations connues

L’API de recherche présente les limitations suivantes :

  • La méthode de requête est définie pour autoriser le passage d’une collection d’une ou plusieurs searchRequest à la fois. Toutefois, le service prend actuellement en charge une seule searchRequest à la fois.

  • La ressource searchRequest prend en charge le passage de plusieurs types d’entités à la fois. Toutefois, pour l’instant, la seule combinaison prise en charge concerne les entityTypes SharePoint et OneDrive : driveItem, drive, site, list et listItem. Toutes les combinaisons impliquant message, événements, personne SharePoint et OneDrive, ou externalItem ne sont actuellement pas pris en charge.

  • La propriété contentSource, qui définit la connexion à utiliser, s’applique uniquement lorsque entityType est spécifié comme externalItem.

  • L’API de recherche ne prend pas en charge le tri personnalisé pour message, événement, personne ou externalItem.

  • L’API de recherche ne prend pas en charge les agrégations pour message, événement, site, personne ou lecteur.

  • Les personnalisations dans la recherche SharePoint, telles que les sources de résultats ou les schémas de recherche personnalisée, peuvent interférer avec l’opération de l’API de recherche Microsoft.

Avertissement de désapprobation du changement de schéma

Dans la version bêta, les propriétés utilisées dans une demande de recherche et une réponse ont été renommées ou supprimées. Dans la plupart des cas, les propriétés d’origine sont marquées comme obsolètes et remplacées par les propriétés actuelles, comme indiqué dans le tableau suivant.

Commencer à mettre à jour les applications existantes pour utiliser les noms de propriétés et de types actuels et obtenir les noms des propriétés actuelles dans la réponse. Pour assurer la compatibilité descendante, les propriétés et les types d’origine sont accessibles et fonctionnels jusqu’à ce que 31 décembre 2020, après quoi ils seront supprimés.

Ressource Type de modification Propriété d’origine Propriété actuelle
searchRequest Renommer la propriété stored_fields fields
searchQuery Renommer la propriété query_string queryString
searchQueryString Déprécier la ressource Non applicable Non applicable
searchHit Renommer la propriété _id hitId
searchHit Renommer la propriété _score rank
searchHit Supprimer une propriété _sortField Non applicable
searchHit Renommer la propriété _source resource
searchHit Renommer la propriété _summary summary
entityTypes Renommer une valeur d’énumération unknownfuturevalue unknownFutureValue

Voir aussi

Nouveautés

Pour en savoir plus sur le les dernières nouveautés et mises à jour pour cet ensemble d'API.