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

  • Article

Importante

Les API sous la version /beta dans 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 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’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 à plus d’éléments dans une recherche qu’ils ne peuvent obtenir à partir d’une opération GET correspondante avec les mêmes autorisations et le même 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
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
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. Les bibliothèques de documents sont également retournées sous forme de listes.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint et OneDrive Éléments de liste. Les fichiers et dossiers sont également retournés en tant qu’éléments de liste ; listItem est la super classe de driveItem.
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.
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), 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. L’API de recherche ne prend pas techniquement en charge ces options de requête, car le comportement est exprimé dans le corps POST.

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, driveItem et externalItem sont les seules entités prises en charge qui permettent d’obtenir des champs récupérables étendus configurés dans le schéma. Vous ne pouvez pas récupérer les 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 personnalisée récupérable sur un objet listItem ou driveItem, vous pouvez récupérer ces propriétés à partir de la recherche. Pour récupérer une propriété étendue sur un fichier, spécifiez le type listItem ou driveItem dans la requête.

Si les champs spécifiés dans la demande 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, driveItem et externalItem se comportent différemment lorsqu’aucun champ n’est transmis dans la requête :

  • listItem ne retourne aucun champ personnalisé.
  • driveItem retourne un listItem interne avec un champ vide.
  • 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 limite, qui sont utilisés pour réduire les résultats dans un corps de réponse. L’utilisation de collapseProperties affecte uniquement le rappel, mais pas le 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.

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

Les propriétés sur lesquelles la clause de réduction est appliquée doivent être interrogeables et triables ou redéfinissables. Pour la réduction à plusieurs niveaux, chaque taille de limite de propriété suivante spécifiée dans une requête à plusieurs niveaux doit être inférieure ou égale à la précédente ; sinon, la réponse retourne une HTTP 400 Bad Request erreur.

Pour obtenir des exemples qui montrent comment réduire les résultats, 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.

Le tri des résultats est actuellement pris en charge uniquement sur les types SharePoint et OneDrive suivants : driveItem, listItem, list, site.

Les propriétés sur lesquelles la clause de tri est appliquée 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 retourne une erreur, HTTP 400 Bad Request. Vous ne pouvez pas spécifier de trier les documents par pertinence à 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) sont un moyen populaire 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 redéfinissable ou n’existe pas, la réponse retourne HTTP 400 Bad Request.

Une fois la réponse retournée contenant la collection d’objets searchBucket , il est possible d’affiner la demande de recherche uniquement pour les éléments correspondants contenus dans un 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 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 dusearchResponse.

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 lesearchresponse, 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 .

L’API Recherche permet aux utilisateurs invités de rechercher des éléments dans SharePoint ou OneDrive qui ont été partagés avec eux. Pour accéder à la liste des utilisateurs invités, accédez à la Centre d'administration Microsoft 365, puis dans le volet de navigation de gauche, choisissez Utilisateurs, puis utilisateurs invités.

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.

Avertissement de désapprobation du changement de schéma

À compter du 31 août 2023, la version bêta de la ressource externalItem dans l’espace de noms Microsoft Graph sera déconseillée. À l’avenir, utilisez la version de la ressource dans l’espace de noms Microsoft.Graph.ExternalConnectors . Veillez à mettre à jour toutes les dépendances d’espace de noms avant la date spécifiée. Vous pouvez également passer à la version v1.0 de l’API.

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.

Nous vous recommandons de mettre à jour les applications existantes pour utiliser les noms de propriété et de type actuels, et pour obtenir les noms de propriétés actuelles dans la réponse. Pour une compatibilité descendante, les propriétés et les types d’origine sont accessibles et fonctionnels jusqu’au 30 septembre 2023, 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

Contenu connexe