Connecter un bot à Search (aperçu)

  • Article

Le présent article explique comment créer un moteur de recherche fédéré personnalisé (avec votre bot) et le connecter au canal de recherche. Une fois que l’administrateur client a autorisé son client à utiliser votre fournisseur, les recherches des utilisateurs de l’entreprise, à partir d’Office.com, de SharePoint.com et de Bing.com, peuvent inclure des résultats provenant de votre moteur de recherche personnalisé.

La plateforme de recherche fédérée Microsoft vous permet de créer des fournisseurs de recherche fédérés personnalisés pour permettre à vos informations de participer à des expériences réponses et verticales de Recherche Microsoft sans avoir besoin de fusionner ces informations avec votre index Microsoft 365. Pour en savoir plus, reportez-vous à Annonce de l’aperçu du développeur de la plateforme de recherche fédérée Microsoft et Recherche fédérée Dynamics 365 (aperçu).

Remarque

Le canal de recherche est en préversion privée. Pour demander l’accès, utilisez le formulaire de préversion privée des développeurs de la Recherche Microsoft. À la question 7, sélectionnez Recherche fédérée.

Les étapes suivantes sont nécessaires pour connecter votre bot au canal de recherche. Ces étapes sont développées plus en détail ultérieurement dans cet article.

  1. Implémentez votre bot de manière à ce qu’il fonctionne comme un moteur de recherche.
  2. Si votre bot exige que les utilisateurs soient connectés :
    1. Dans le Portail Azure, exposez l’API de bot à la plateforme de recherche.
    2. Dans le code de votre bot, utilisez l’URI d’étendue généré pour créer un jeton d’utilisateur.
  3. Déployer votre bot sur Azure.
  4. Ajoutez le canal de recherche à votre bot.
  5. Demandez à votre administrateur informatique de passer en revue l’inscription de votre bot et de le publier sur le site du locataire.

Conseil

Nous vous recommandons d’activer le moteur de recherche dans un locataire de test avant de l’activer en production.

Prérequis

Vous pouvez implémenter votre bot dans l’un des langages pris en charge par le Kit de développement logiciel (SDK) Bot Framework. Le présent article utilise le bot de recherche fédéré C# comme exemple.

Conseil

Cette étape n’est nécessaire que si votre bot a besoin d’un accès aux ressources utilisateur protégées.

Dans certains flux de travail d’entreprise, un bot peut nécessiter des informations d’identification utilisateur pour effectuer une action au nom de l’utilisateur. Pour créer une expérience d’authentification unique (SSO) pour votre bot dans le canal de recherche, vous devez autoriser la plateforme de recherche à sécuriser un jeton d’accès à partir de Microsoft Entra ID pour le compte de l’utilisateur.

Pour générer un URI d’étendue et un ID d’application pour votre bot :

  1. Accédez au portail Azure.
  2. Si vous n’avez pas encore de ressource bot, créez une ressource Azure Bot.
  3. Accédez au service Microsoft Entra ID.
  4. Accédez au volet Inscriptions d’applications.
  5. Sélectionnez l’application associée à votre bot.
  6. Accédez au volet Exposer une API.
  7. Sélectionnez Ajouter une étendue.
    1. Dans le volet Ajouter une étendue, nous vous recommandons de conserver l’URI d’ID d’application autogénéré. Cliquez sur Enregistrer et continuer.
    2. Saisissez le nom de l’étendue.
    3. À la question Qui peut consentir ?, veuillez répondre administrateurs et/ou utilisateurs.
    4. Saisissez le nom complet de consentement administrateur et la description du consentement administrateur.
    5. Vous pouvez saisir le nom complet de consentement de l’utilisateur et la description de consentement de l’utilisateur.
    6. Vérifiez que l’état est défini sur Activé.
    7. Sélectionnez Ajouter une étendue.
  8. Sélectionnez Ajouter une application cliente.
    1. Dans le volet Ajouter une application cliente, définissez l’ID client sur 81473081-50b9-469a-b9d8-303109583ecb, l’ID client de la plateforme de Recherche.
    2. Dans la rubrique Étendues autorisées, sélectionnez l’URI d’étendue que vous avez créé à l’étape précédente.
    3. Sélectionnez Ajouter une application.
  9. Accédez au volet Vue d’ensemble. Copiez l’URI d’ID d’application. Vous en aurez besoin lors de l’inscription de votre bot dans le canal de Recherche.

Implémenter votre bot

Le canal de Recherche envoie chaque requête utilisateur à votre bot en tant qu’activité d’appel avec le nom « application/recherche ». Votre bot retourne les résultats de la requête dans la réponse d’invocation. Utilisez le format de carte adaptative pour les résultats de la requête renvoyés au canal de recherche.

  1. Mettez à jour les packages Bot Framework et cartes adaptatives dans votre projet vers la dernière version.
  2. Vous pouvez ajouter du code d’authentification pour générer un jeton utilisateur.
  3. Implémentez une méthode de recherche de données pour chaque source de données à inclure.
  4. Générez la carte adaptative pour afficher les résultats.

Obtenir l’ID de suivi de la plateforme de recherche

La plateforme de recherche affecte un ID de suivi unique à chaque requête qu’elle envoie à votre bot. La plateforme l’ajoute aux données de canal de l’activité d’invocation. Vous pouvez décider de consigner l’ID de suivi de la demande. Utilisez la propriété des données traceId du canal pour obtenir l’ID de suivi.

Dans l’exemple de recherche fédérée, la méthode SearchHelper.GetSearchTraceId montre comment obtenir l’ID de suivi de l’activité d’invocation.

Ajouter une authentification

Si vous avez exposé votre API de bot à Recherche et que vous avez demandé l’authentification lorsque vous avez connecté votre bot à Recherche, vous pouvez obtenir le jeton d’authentification utilisateur à partir des données du canal de l’activité.

La propriété authorizations des données de canal peut contenir une liste de jetons d’authentification. Si vous exposez votre API de bot à la recherche, la liste contient le jeton local. Le jeton de la liste aura la structure suivante :

Nom de la propriété Type Description
authType entier Type de jeton d’authentification : 0 pour un jeton inconnu ou par défaut, ou 2 pour un jeton on-behalf-of.
token string Le jeton d’authentification lui-même.

Dans l’exemple de recherche fédérée :

  • La classe SearchBotAuthenticationToken et l’énumération AuthenticationTypes représentent ces informations.
  • La méthode SearchHelper.GetSearchOboToken montre comment obtenir le jeton à partir de l’activité d’invocation.

Une fois que vous avez le jeton, vous pouvez l’utiliser lorsque vous demandez des ressources protégées pour l’utilisateur. Pour en savoir plus sur l’utilisation des jetons on-behalf-of, reportez-vous à Plateforme d’identités Microsoft et flux On-Behalf-Of OAuth 2.0.

Requête auprès de chaque magasin de données

Le canal de recherche envoie une requête au bot en tant qu’activité invoke, avec les détails de la requête dans la propriété value de l’activité, qui représente un objet JSON ayant la structure suivante :

Nom de propriété Type Description
queryText string Texte de la requête.
kind string Type de requête : « search » lorsque les résultats sont affichés dans un onglet vertical personnalisé, ou « searchAnswer » lorsqu’un résultat s’affiche sous la forme d’une réponse dans l’onglet Tous.
queryOptions object Options de requête supplémentaires utilisées pour la pagination.
queryOptions.skip entier Index du premier résultat à envoyer.
queryOptions.top entier Nombre maximal de résultats à envoyer.

Les résultats de la recherche sont retournés dans la réponse à l’invocation :

  • Définissez toujours la propriété Status de l’objet de réponse d’invocation sur 200, ce qui indique que la connexion réseau est stable. La propriété Body de l’objet a un code d’état distinct.

  • La propriété Body représente un objet JSON avec la structure suivante :

    Nom de la propriété Type Description
    statusCode entier Code d’état HTTP utilisé pour indiquer si le bot a bien exécuté la requête.
    type string Type de la réponse d’invocation, définissant le format du champ valeur. Utilisez « application/vnd.microsoft.search.searchResponse » pour les résultats de la recherche ou « application/vnd.microsoft.error » pour un message d’erreur.
    value object Valeur correspondant à la valeur type.

    Pour les messages d’erreur, l’objet value contient :

    Nom de la propriété Type Description
    code string Code d’erreur défini par le bot, ou null s’il n’est pas spécifié.
    message string Message d’erreur ou null s’il n’est pas spécifié.

    Pour les résultats de la recherche, l’objet value contient :

    Nom de la propriété Type Description
    results Tableau d’objets des résultats de la recherche Résultats ou null si aucun.
    displayLayouts Tableau d’objets de présentation d’affichage Les présentations d’affichage, ou null si aucune.
    totalResultCount entier Résultats totaux disponibles, si la pagination est prise en charge ; sinon, null.
    moreResultsAvailable Boolean Indique si d’autres résultats sont disponibles.

    Les objets des résultats de la recherche contiennent :

    Nom de la propriété Type Description
    value string Identificateur ou valeur unique pour ce résultat de recherche.
    layoutId string ID de la présentation d’affichage à utiliser pour ce résultat.
    data.searchResultText string Texte de ce résultat.

    Les objets de présentation d’affichage contiennent :

    Nom de la propriété Type Description
    layoutId string ID de disposition.
    layoutBody string Corps de disposition en tant qu’objet JSON cartes adaptatives.

Dans l’exemple de recherche fédérée, la méthode SearchHelper.RunFederatedSearch montre comment obtenir les informations de requête à partir de l’activité d’invocation et comment mettre en forme la réponse d’invocation.

Afficher les résultats de la recherche

Vous pouvez créer des secteurs verticaux de recherche et des types de résultats pour personnaliser les résultats de la recherche que les utilisateurs voient lorsqu’ils effectuent des recherches dans SharePoint, Office et Bing. Les secteurs verticaux permettent aux utilisateurs de trouver plus facilement les informations dont l’accès leur est autorisé. Pour en savoir plus, reportez-vous à la section Éléments de carte adaptative pris en charge.

Si votre bot reçoit une requête pour laquelle il n’a aucune réponse, son commentaire doit être vide.

Enregistrer votre bot dans Azure

Pour connecter votre bot au canal de recherche, vous devez disposer d’une ressource de bot approvisionnée dans Azure. Pour en savoir plus, reportez-vous au guide Inscription de bot avec Azure ou Déploiement de bot dans Azure.

Les instructions suivantes vous montrent comment connecter un bot à Recherche.

Conseil

Nous vous recommandons d’activer le moteur de recherche dans un locataire de test avant de l’activer en production.

  1. Accédez au portail Azure.

  2. Ouvrez votre ressource de bot.

  3. Ouvrez le volet Canaux (aperçu).

  4. Sélectionnez Rechercher.

  5. Dans l’onglet Paramètres de recherche, saisissez les informations de votre bot.

    Sample of the Search Settings tab

    1. Dans la rubrique Métadonnées du moteur de recherche, saisissez le nom à afficher dans l’IU de recherche.

    2. Dans la rubrique phrases déclencheurs, définissez les expressions qui représentent les requêtes auxquelles votre bot peut répondre.

      Remarque

      Pour les versions initiales, seul l’anglais (en-US) est disponible.

      • Chargez un fichier .csv qui contient les phrases. Le fichier doit contenir une colonne de données, sans en-têtes.
      • Dans la liste des langues choisies, sélectionnez la langue dans laquelle les phrases déclencheurs sont écrites.

    3. Dans la rubrique Authentification, indiquez si votre moteur de recherche nécessite l’authentification de l’utilisateur.

      • Si l’authentification est requise, saisissez l’URL d’authentification. Utilisez l’URI d’ID d’application que vous avez copié lorsque vous avez exposé l’API pour votre bot.

    4. Cliquez sur Suivant.

  6. Sous l’onglet Secteurs verticaux, si vous souhaitez que les résultats de votre moteur de recherche s’affichent dans son propre secteur vertical personnalisé dans la page des résultats de la recherche, saisissez le nom vertical dans le champ ; sinon, laissez ce champ vide. Sélectionnez ensuite Suivant.
    La page des résultats de recherche concerne Office.com, SharePoint.com et Bing.com.

  7. Dans l’onglet Publication du locataire, examinez vos paramètres et ajoutez des informations de publication.

    1. Examinez le nom du moteur de recherche et les modèles de requêtes. Revenez aux onglets précédents pour modifier ces informations, le cas échéant.
    2. Saisissez une description de votre moteur de recherche.
    3. Saisissez l’adresse e-mail du contact d’assistance. Utilisez l’e-mail d’un développeur ou d’un groupe de développeurs qui a accès au moteur de recherche.

  8. Sélectionnez Ajouter pour demander l’approbation à votre administrateur informatique.

Approuver un moteur de recherche dans un locataire

L’approbation du fournisseur de recherche dans le locataire est effectuée par un administrateur informatique dans la page Recherche &Intelligence de l’Centre d'administration Microsoft 365.

Tester la connexion

Nous vous recommandons d’activer le moteur de recherche dans un locataire de test avant de l’activer en production.

Modifier un moteur de recherche

Vous pouvez modifier le moteur de recherche avant de le soumettre pour révision par l’administrateur informatique. Vous devrez peut-être le faire si votre demande initiale est rejetée ou si votre service est désactivé.

  1. Dans le Portail Azure, accédez à la ressource de bot qui contient le moteur de recherche que vous souhaitez modifier.
  2. Reportez-vous au volet Canaux (aperçu).
  3. Sélectionnez le canal de Recherche, puis Modifier.
    1. Azure affiche le volet du Canal Recherche. Dans ce volet, vous pouvez modifier vos paramètres.
    2. Pour modifier les phrases déclencheurs, téléchargez le fichier, modifiez-le localement et chargez-le.
    3. Une fois que vous avez terminé vos modifications, sélectionnez Ajouter à nouveau pour envoyer un moteur de recherche pour examen par l’administrateur informatique.

Supprimer un moteur de recherche

Votre moteur de recherche sera supprimé si vous supprimez le canal de recherche de la ressource de bot.

Pour supprimer le canal de recherche de votre bot :

  1. Dans le portail Azure, accédez à votre ressource de bot.
  2. Reportez-vous au volet Canaux (aperçu).
  3. Sélectionnez le canal Rechercher.
  4. En haut du volet du canal de recherche, sélectionnez Supprimer le canal.
  5. Pour confirmer l’opération, sélectionnez Oui.

Pour supprimer vos ressources de bot :

  1. Dans le portail Azure, accédez à votre ressource de bot.
  2. Si ce n’est déjà fait, supprimez le canal de recherche de votre bot.
  3. En haut du volet Vue d’ensemble, sélectionnez Supprimer.
  4. Sélectionnez OK pour confirmer l’opération.

Informations supplémentaires

Le canal de recherche utilise la recherche fédérée et le schéma cartes adaptatives :

Pour en savoir plus sur le schéma de carte adaptative, reportez-vous à Cartes adaptatives pour les développeurs de bots.

À propos des phrases déclencheurs

Une phrase déclencheur est une expression que la plateforme de recherche utilise pour acheminer une requête vers votre moteur de recherche personnalisé avec votre bot. La recherche fédérée transfère l’énoncé d’un utilisateur à votre moteur de recherche lorsque l’énoncé est une correspondance étroite avec l’une des phrases déclencheurs.

Conseil

Si plusieurs moteurs de recherche sont disponibles, la recherche fédérée n’en choisit qu’une, en fonction des phrases déclencheurs fournies et de la requête de l’utilisateur.

Par exemple, pensez à un bot qui gère les horaires de vol et l’état.

  1. Pensez à quelques façons courantes pour un utilisateur de faire référence à votre bot ou de l’utiliser. Veillez à distinguer votre bot des autres.

    Au lieu d’un terme générique, tel que « Agenda » qui peut s’appliquer aux établissements d’enseignement et aux programmes TV, utilisez des expressions plus spécifiques, telles que « programme des vols » et « horaires de vols ».

  2. Incluez diverses expressions qui couvrent l’étendue des fonctionnalités de votre bot, telles que l’heure de départ et l’état actuel.

    Par exemple, incluez des requêtes sur les heures d’arrivée ou de départ et les aéroports.

Les phrases déclencheurs pour un tel bot sur les horaires et le statut des vols pourraient inclure :

  • Horaires de vols
  • Informations sur le vol
  • Heure de départ du vol 675
  • Quelle est l’heure de départ de mon vol ?
  • Heure d’arrivée du vol 468
  • Informations sur le vol de Tacoma à Seattle
  • Informations sur le vol d’Heathrow

Comme autre exemple, les phrases déclencheurs d’un bot de prévision météorologique peuvent inclure :

  • Prévisions météorologiques locales
  • Informations météorologiques
  • La météo de demain
  • Prévisions météorologiques à 10 jours
  • Pic de chaleur du jour
  • Probabilité de pluie aujourd’hui
  • Va-t-il neiger demain ?
  • Vitesse du vent demain ?
  • Y a-t-il du vent ?
  • Météo de Londres

Éléments de carte adaptative pris en charge

Un sous-ensemble du schéma de carte adaptative est pris en charge dans la recherche fédérée. Pour en savoir plus sur la mise en forme de vos résultats de recherche, reportez-vous à Personnaliser la page des résultats de la recherche.

La prise en charge inclut les éléments de carte adaptative suivants : TextBlock, RichTextBlock, Image, ColumnSet, ImageSet et FactSet. Pour en savoir plus, reportez-vous à Gérer la disposition des résultats de la recherche de Recherche Microsoft et à l’Explorateur de schémas de cartes adaptatives.

Vous pouvez créer chaque carte directement au format JSON, ou utiliser le package NuGet AdaptiveCards.

La recherche fédérée ne prend pas en charge le code HTML

Important

La recherche fédérée ne restitue pas le texte de carte adaptative qui contient du code HTML.

La plateforme de recherche n’inclut pas d’analyseur HTML. Toutefois, vous pouvez éliminer certaines des balises et utiliser le package NuGet Html2Markdown pour convertir du code HTML en Markdown :

  1. Supprime les éléments <span> et <u>.
  2. Remplacez les éléments <div> et <br> par des éléments de paragraphe (<p>).
  3. Convertissez le code HTML restant en Markdown.

Étapes suivantes