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

  • Article

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.

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’usage courants de la méthode de requête, en fonction des propriétés et des paramètres que vous définissez dans le corps de la 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 ettaille
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
Réduire les résultats de la recherche collapseProperties
Trier les résultats de recherche sortProperties
Affiner les résultats à l’aide d’agrégations aggregations
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
Acronyme Acronyme.Read.All Recherche Microsoft Acronymes dans Microsoft Recherche dans votre organization.
bookmark Bookmark.Read.All Recherche Microsoft Signets dans Microsoft Recherche dans votre organization.
chatMessage Chat.Read, Chat.ReadWrite, ChannelMessage.Read.All Teams Messages Teams.
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.
qna QnA.Read.All Recherche Microsoft Questions et réponses dans Microsoft Recherche dans votre organization.
site Sites.Read.All, Sites.ReadWrite.All SharePoint Sites dans SharePoint.

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.

La limite supérieure pour les éléments SharePoint ou OneDrive est de 1 000. 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ésde 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), 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 unelistItem, 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 aucun champ dans la requête, vous obtenez le jeu 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é derequête du corps de la demande de la requête). L’opérateur XRANK augmente le rang dynamique des éléments en fonction de certaines occurrences de terme dans l’expression de correspondance, sans modifier les éléments correspondant à 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 obtenir des informations détaillées, voir :

Réduire les résultats de la recherche

La propriété collapseProperties contient un ensemble de critères, de champs et de taille de limite utilisés pour réduire les résultats dans un corps de réponse. L’utilisation de collapseProperties affecte uniquement le rappel, mais pas les actions de classement/tri.

La méthode de requête vous permet de personnaliser la propriété collapse en spécifiant collapseProperties sur le requests paramètre , qui est une collection d’objets collapseProperty . Cela vous permet de spécifier un ensemble d’une ou plusieurs propriétés de réduction.

Notez que la réduction des résultats est actuellement prise en charge pour les types d’entités suivants : driveItem, listItem, drive, list, site, externalItem.

Pour utiliser efficacement la clause de réduction, les propriétés que vous appliquez doivent être interrogeables et peuvent être triées ou redéfinissables. Lors de l’utilisation de la réduction à plusieurs niveaux, il est important de noter que la taille limite de chaque propriété suivante spécifiée dans une requête à plusieurs niveaux doit être égale ou inférieure à la précédente. Si la taille limite d’une propriété suivante dépasse la précédente, le serveur répond avec une HTTP 400 Bad Request erreur.

Pour plus d’exemples de résultats de réduction, consultez Réduire les résultats de la recherche .

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 requests paramètre, qui est une collection d’objets sortProperty . 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, vous devez renvoyer la valeur aggregationsFilterToken dans la propriété aggregationFilters de la requête searchRequest suivante.

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 obtenir des exemples qui montrent comment utiliser l’agrégation pour améliorer et affiner les résultats de recherche, voir 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 dusearchResponse.

Dans le corps de la demande de la méthode de requête, spécifiez les queryAlterationOptions qui doivent être appliquées à la requête pour les corrections orthographiques. La description de queryAlterationOptions est définie dans le searchrequest.

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 searchResponse , vous devez définir la propriété enableResultTemplate sur true, qui est définie dans resultTemplateOptions dans searchRequest. La réponse inclut un resultTemplateId pour chaque searchHit, qui est mapmé sur l’une des dispositions d’affichage incluses dans le dictionnaire resultTemplates qui fait partie de la réponse.

Pour obtenir des exemples qui montrent comment afficher les résultats de la recherche, voir Utiliser la disposition d’affichage de la 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. Le tableau suivant répertorie les combinaisons prises en charge.

    Type d’entité acronym bookmark message chatMessage Lecteur driveItem event externalItem liste listItem Personne qna site
    acronym True True - - - - - - - - - True -
    bookmark True True - - - - - - - - - True -
    chatMessage - - - Vrai - - - - - - - - -
    Lecteur - - - - True True - True True True - - True
    driveItem - - - - True True - True True True - - True
    event - - - - - - Vrai - - - - - -
    externalItem - - - - True True - True True True - - True
    liste - - - - True True - True True True - - True
    listItem - - - - True True - True True True - - True
    message - - Vrai - - - - - - - - - -
    Personne - - - - - - - - - - Vrai - -
    qna True True - - - - - - - - - True -
    site - - - - True True - True True True - - True

  • 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 les acronymes, signets, messages, chatMessage, event, person, qna ou externalItem.

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

  • L’API de recherche ne prend pas en charge xrank pour les acronymes, signets, message, chatMessage, event, person, qna ou externalItem.

  • La recherche d’invité ne prend pas en charge les recherches d’acronyme, de signet, de message, de chatMessage, d’événement, de personne, de qna ou d’externalItem.

  • Les personnalisations dans la recherche SharePoint, telles qu’un schéma de recherche personnalisé ou des sources de résultats, peuvent interférer avec les opérations de l’API Microsoft Recherche.

  • L’API de recherche ne prend pas en charge le schéma de recherche au niveau du site. Utilisez le schéma de recherche au niveau du locataire ou par défaut.

Contenu connexe