Connessione un bot per la ricerca (anteprima)

Questo articolo descrive come creare un provider di ricerca federato personalizzato (power by your bot) e connetterlo al canale di ricerca. Quando l'amministratore tenant abilita il provider nel tenant, le ricerche degli utenti aziendali, da Office.com, SharePoint.com e Bing.com, possono includere i risultati del provider di ricerca personalizzato.

Microsoft Federated Search Platform consente di creare provider di ricerca federati personalizzati per consentire alle informazioni di partecipare alle esperienze Answers & Vertical di Microsoft Search senza la necessità di unire tali informazioni con l'indice di Microsoft 365. Per altre informazioni, vedere Annuncio dell'anteprima per sviluppatori della piattaforma di ricerca federativa Microsoft e della ricerca federativa di Dynamics 365 (anteprima).

Nota

Il canale di ricerca è in anteprima privata. Per richiedere l'accesso, usare il modulo Anteprima privata per sviluppatori di Microsoft Search. In questione 7 selezionare Ricerca federata.

Per connettere il bot al canale di ricerca sono necessari i passaggi seguenti. Questi passaggi sono descritti in modo più dettagliato più avanti in questo articolo.

1. Implementare il bot per funzionare come provider di ricerca.
2. Se il bot richiederà l'accesso degli utenti:
   1. Nella portale di Azure esporre l'API bot alla piattaforma di ricerca.
   2. Nel codice del bot usare l'URI dell'ambito generato per generare un token utente.
3. Distribuire il bot in Azure.
4. Aggiungere il canale di ricerca al bot.
5. Chiedere all'amministratore IT di esaminare la registrazione del bot e pubblicare il bot nel tenant.

Suggerimento

È consigliabile abilitare il provider di ricerca in un tenant di test prima di abilitarlo nell'ambiente di produzione.

Prerequisiti

• Conoscenza delle nozioni di base del servizio Bot Framework e come creare un bot con Bot Framework SDK.
• Bot da connettere al canale.
• Se non si ha un account Azure, creare un account gratuito prima di iniziare.

È possibile implementare il bot in uno dei linguaggi supportati da Bot Framework SDK. Questo articolo usa il bot di ricerca federato C# come esempio.

Esporre l'API bot alla ricerca

Suggerimento

Questo passaggio è necessario solo se il bot richiede l'accesso alle risorse utente protette.

In alcuni flussi di lavoro aziendali, un bot potrebbe richiedere credenziali utente per eseguire un'azione per conto dell'utente. Per creare un'esperienza single sign-on (SSO) per il bot nel canale di ricerca, è necessario consentire alla piattaforma di ricerca di proteggere un token di accesso da Microsoft Entra ID per conto dell'utente.

Per generare un URI di ambito e un ID applicazione per il bot:

1. Vai al portale di Azure.
2. Se non si ha già una risorsa bot, creare una risorsa di Azure Bot.
3. Passare al servizio Microsoft Entra ID .
4. Passare al riquadro Registrazioni app.
5. Selezionare l'applicazione associata al bot.
6. Passare al riquadro Esporre un'API.
7. Seleziona Aggiungi un ambito.
   1. Nel riquadro Aggiungi un ambito è consigliabile mantenere l'URI DELL'ID applicazione generato automaticamente. Selezionare Salva e continua.
   2. Immettere un nome ambito.
   3. Per Chi può fornire il consenso? Amministrazione e gli utenti è preferibile, ma entrambe le opzioni funzioneranno.
   4. Immettere un nome visualizzato del consenso Amministrazione e una descrizione del consenso Amministrazione.
   5. Facoltativamente, immettere un nome visualizzato di consenso utente e una descrizione del consenso utente.
   6. Verificare che State sia impostato su Abilitato.
   7. Seleziona Aggiungi ambito.
8. Seleziona Aggiungi applicazione client.
   1. Nel riquadro Aggiungi un'applicazione client impostare ID client su 81473081-50b9-469a-b9d8-303109583ecb, l'ID client della piattaforma di ricerca.
   2. In Ambiti autorizzati selezionare l'URI dell'ambito creato nel passaggio precedente.
   3. Seleziona Aggiungi applicazione.
9. Passare al riquadro Panoramica . Copiare l'URI ID applicazione. Questa operazione sarà necessaria quando si registra il bot nel canale di ricerca.

Implementare il bot

Il canale di ricerca invia ogni query utente al bot come attività invoke con il nome "applicazione/ricerca". Il bot restituisce i risultati della query nella risposta invoke. Usare il formato scheda adattiva per i risultati della query inviati al canale di ricerca.

1. Aggiornare tutti i pacchetti bot Framework e schede adattive nel progetto alla versione più recente.
2. Facoltativamente, aggiungere il codice di autenticazione per generare un token utente.
3. Implementare un metodo di ricerca dati per ogni origine dati da includere.
4. Generare la scheda adattiva per visualizzare i risultati.

Ottenere l'ID traccia della piattaforma di ricerca

La piattaforma di ricerca assegna un ID di traccia univoco a ogni query inviata al bot. La piattaforma lo aggiunge ai dati del canale dell'attività invoke. È possibile decidere di registrare l'ID di traccia della richiesta. Usare la proprietà dei dati del traceId canale per ottenere l'ID di traccia.

Nell'esempio di ricerca federata il SearchHelper.GetSearchTraceId metodo illustra come ottenere l'ID di traccia dall'attività invoke.

Aggiungere l'autenticazione

Se l'API del bot è stata esposta a Ricerca ed è stata richiesta l'autenticazione quando è stato connesso il bot a Search, è possibile ottenere il token di autenticazione utente dai dati del canale dell'attività.

La proprietà dei dati del authorizations canale può contenere un elenco di token di autenticazione. Se si espone l'API del bot alla ricerca, l'elenco conterrà il token on-behalf-of. Il token nell'elenco avrà la struttura seguente:

Nome proprietà	Type	Descrizione
Authtype	integer	Tipo di token di autenticazione: 0 per token sconosciuto o predefinito o 2 per il token on-behalf-of.
token	string	Token di autenticazione stesso.

Nell'esempio di ricerca federata:

• La SearchBotAuthenticationToken classe e l'enumerazione AuthenticationTypes rappresentano queste informazioni.
• Il SearchHelper.GetSearchOboToken metodo illustra come ottenere il token dall'attività invoke.

Dopo aver ottenuto il token, è possibile usarlo quando si richiedono risorse protette per l'utente. Per informazioni sull'uso di token on-behalf-of, vedere Flusso On-Behalf-Of di Microsoft Identity Platform e OAuth 2.0.

Eseguire query su ogni archivio dati

Il canale di ricerca invia una query al bot come invoke attività, con i dettagli della query nella proprietà dell'attività value , che rappresenta un oggetto JSON con la struttura seguente:

Nome proprietà	Type	Descrizione
queryText	string	Testo della query.
kind	string	Tipo di query: "ricerca" quando i risultati verranno visualizzati in una scheda verticale personalizzata o "searchAnswer" quando un risultato verrà visualizzato come risposta nella scheda Tutti.
Queryoptions	oggetto	Opzioni di query aggiuntive usate per la paginazione.
queryOptions.skip	integer	Indice del primo risultato da inviare.
queryOptions.top	integer	Numero massimo di risultati da inviare.

I risultati della ricerca sono restituiti nella risposta invoke:

• Impostare sempre la proprietà dell'oggetto Status di risposta invoke su 200, che indica che la connessione di rete è corretta. La proprietà dell'oggetto Body ha un codice di stato separato.

• La Body proprietà rappresenta un oggetto JSON con la struttura seguente:

  Nome proprietà	Type	Descrizione
  statusCode	integer	Codice di stato HTTP usato per indicare se il bot è riuscito a eseguire correttamente la query.
  type	string	Tipo della risposta invoke, che definisce il formato del campo valore. Usare "application/vnd.microsoft.search.searchResponse" per i risultati della ricerca o "application/vnd.microsoft.error" per un messaggio di errore.
  value	oggetto	Valore che corrisponde al valore type.

  Per i messaggi di errore, l'oggetto value contiene:

  Nome proprietà	Type	Descrizione
  codice	string	Codice di errore definito dal bot o null se non specificato.
  messaggio	string	Messaggio di errore o null se non specificato.

  Per i risultati della ricerca, l'oggetto value contiene:

  Nome proprietà	Type	Descrizione
  Risultati	matrice di oggetti risultato di ricerca	Risultati o null se nessuno.
  displayLayouts	matrice di oggetti layout di visualizzazione	Layout di visualizzazione o null se nessuno.
  totalResultCount	integer	I risultati totali disponibili, se l'impaginazione è supportata; in caso contrario, null.
  moreResultsAvailable	Booleano	Indica se sono disponibili più risultati.

  Gli oggetti risultato della ricerca contengono:

  Nome proprietà	Type	Descrizione
  value	string	Identificatore univoco o valore per questo risultato della ricerca.
  layoutId	string	ID del layout di visualizzazione da utilizzare per questo risultato.
  data.searchResultText	string	Testo per questo risultato.

  Gli oggetti layout di visualizzazione contengono:

  Nome proprietà	Type	Descrizione
  layoutId	string	ID layout.
  layoutBody	string	Corpo del layout come oggetto JSON schede adattive.

Nell'esempio di ricerca federata il SearchHelper.RunFederatedSearch metodo illustra come ottenere le informazioni sulla query dall'attività invoke e come formattare la risposta invoke.

Visualizzare i risultati della ricerca

È possibile creare verticali di ricerca e tipi di risultati per personalizzare i risultati della ricerca visualizzati dagli utenti durante la ricerca in SharePoint, Office e Bing. I verticali rendono più semplice per gli utenti trovare le informazioni che dispongono dell'autorizzazione per visualizzare. Per altre informazioni, vedere la sezione Elementi della scheda adattiva supportati.

Se il bot riceve una query per cui non ha risposta, la risposta deve contenere una risposta vuota.

Registrare il bot in Azure

Per connettere il bot al canale di ricerca, è necessario disporre di una risorsa bot di cui è stato effettuato il provisioning in Azure. Per altre informazioni, vedere Registrare un bot con Azure o come distribuire il bot in Azure.

Connessione il bot per la ricerca

Le istruzioni seguenti illustrano come connettere un bot alla ricerca.

Suggerimento

È consigliabile abilitare il provider di ricerca in un tenant di test prima di abilitarlo nell'ambiente di produzione.

1. Vai al portale di Azure.

2. Aprire la risorsa bot.

3. Aprire il riquadro Canali (anteprima).

4. Seleziona Cerca.

5. Nella scheda Cerca Impostazioni immettere le informazioni per il bot.

   

   1. In Search Provider Metadata (Metadati provider di ricerca) immettere il nome da visualizzare nell'interfaccia utente di ricerca.

   2. In Frasi trigger definire le frasi che rappresentano le query a cui il bot può rispondere.

      Nota

      Per le versioni iniziali, è disponibile solo l'inglese (en-US).

      • Caricare un .csv file contenente le frasi. Il file deve contenere una colonna di dati, senza intestazioni.
      • Nell'elenco Preferenza lingua selezionare la lingua in cui vengono scritte le frasi trigger.

   3. In Autenticazione indicare se il provider di ricerca richiede l'autenticazione utente.

      • Se è necessaria l'autenticazione, immettere l'URL di autenticazione. Usare l'URI ID applicazione copiato quando è stata esposta l'API per il bot.

   4. Seleziona Avanti.

6. Nella scheda Verticali, se si desidera che i risultati del provider di ricerca venga visualizzato nel proprio verticale personalizzato nella pagina dei risultati della ricerca, quindi immettere il nome verticale nel campo; in caso contrario, lasciare vuoto questo campo. Quindi seleziona Avanti.
   La pagina dei risultati della ricerca è destinata a Office.com, SharePoint.com e Bing.com.

7. Nella scheda Pubblicazione tenant esaminare le impostazioni e aggiungere le informazioni di pubblicazione.

   1. Esaminare il nome del provider di ricerca e le query di esempio. Tornare alle schede precedenti per modificare queste informazioni, se necessario.
   2. Immettere una descrizione del provider di ricerca.
   3. Immettere un messaggio di posta elettronica di contatto del supporto. Usare l'indirizzo di posta elettronica di uno sviluppatore o di un gruppo di sviluppatori che ha accesso al provider di ricerca.

8. Selezionare Aggiungi per richiedere l'approvazione dall'amministratore IT.

Approvare un provider di ricerca in un tenant

L'approvazione del provider di ricerca nel tenant viene effettuata da un amministratore IT nella pagina Ricerca e intelligence nel interfaccia di amministrazione di Microsoft 365.

Testare la connessione

È consigliabile abilitare il provider di ricerca in un tenant di test prima di abilitarlo nell'ambiente di produzione.

Modificare un provider di ricerca

È possibile modificare il provider di ricerca prima di inviarlo per la revisione da parte dell'amministratore IT. Potrebbe essere necessario farlo se la richiesta iniziale viene rifiutata o il servizio viene disattivato.

1. Nel portale di Azure passare alla risorsa bot che contiene il provider di ricerca che si vuole modificare.
2. Passare al riquadro Canali (anteprima).
3. Selezionare il canale di ricerca e selezionare Modifica.
   1. Azure visualizza il riquadro Canale di ricerca. In questo riquadro è possibile modificare le impostazioni.
   2. Per modificare le frasi di attivazione, scaricare il file, modificarlo in locale e caricare il file.
   3. Dopo aver completato le modifiche, selezionare di nuovo Aggiungi per inviare il provider di ricerca per la revisione da parte dell'amministratore IT.

Eliminare un provider di ricerca

Il provider di ricerca verrà eliminato se si rimuove il canale di ricerca dalla risorsa bot.

Per rimuovere il canale di ricerca dal bot:

1. Nella portale di Azure passare alla risorsa bot.
2. Passare al riquadro Canali (anteprima).
3. Selezionare il canale di ricerca.
4. Nella parte superiore del riquadro Canale di ricerca selezionare Elimina canale.
5. Selezionare Sì per confermare l'operazione.

Per eliminare la risorsa bot:

1. Nella portale di Azure passare alla risorsa bot.
2. Se non è già stato fatto, rimuovere il canale di ricerca dal bot.
3. Nella parte superiore del riquadro Panoramica selezionare Elimina.
4. Seleziona OK per confermare l'operazione.

Informazioni aggiuntive

Il canale di ricerca usa la ricerca federata e lo schema delle schede adattive:

Per altre informazioni sullo schema della scheda adattiva, vedere Schede adattive per sviluppatori di bot.

Informazioni sulle frasi trigger

Una frase trigger è una frase usata dalla piattaforma di ricerca per instradare una query al provider di ricerca personalizzato basato sul bot. La ricerca federata inoltra l'espressione di un utente al provider di ricerca quando l'espressione è una corrispondenza vicina a una delle frasi trigger.

Suggerimento

Se sono disponibili più provider di ricerca, la ricerca federata sceglie solo una, in base alle frasi trigger fornite e alla query dell'utente.

Si pensi ad esempio a un bot che gestisce le pianificazioni e lo stato dei voli.

1. Si pensi ad alcuni modi comuni in cui un utente fa riferimento o usa il bot. Assicurarsi di distinguere il bot da altri utenti.

   Invece di un termine generico, ad esempio "orario" che può essere applicato alle scuole e ai programmi televisivi, usare frasi più specifiche, ad esempio "tabella oraria volo" e "programma di volo".

2. Includere frasi diverse che coprono l'ambito delle funzionalità del bot, ad esempio l'ora di partenza e lo stato corrente.

   Ad esempio, includere query su: orari di arrivo o di partenza e aeroporti.

Le frasi trigger per un bot di pianificazione e stato di questo tipo possono includere:

• Orario di volo
• Stato del volo
• Ora di partenza del volo 675
• Quando partirà il mio volo
• Ora di arrivo del volo 468
• Stato del volo di Seattle Tacoma
• Stato del volo Heathrow

Come un altro esempio, le frasi trigger per un bot per le previsioni meteo possono includere:

• Previsioni meteo locali
• Informazioni meteo
• Il tempo di domani
• Previsioni meteo di 10 giorni
• Oggi è alto
• La possibilità di pioggia di oggi
• Domani neverà
• Velocità del vento domani
• È ventoso fuori
• Meteo di Londra

Elementi della scheda adattiva supportati

Nella ricerca federata è supportato un subset dello schema della scheda adattiva. Per informazioni sulla formattazione dei risultati della ricerca, vedere Personalizzare la pagina dei risultati della ricerca.

Il supporto include gli elementi della scheda adattiva seguenti: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet e FactSet. Per altre informazioni, vedere Gestire i layout dei risultati della ricerca di Microsoft Search e Esplora schemi schede adattive.

È possibile creare ogni scheda direttamente come JSON oppure usare il pacchetto NuGet AdaptiveCards .

La ricerca federata non supporta HTML

Importante

La ricerca federata non eseguirà il rendering del testo della scheda adattiva contenente HTML.

La piattaforma di ricerca non include un parser HTML. Tuttavia, è possibile eliminare alcuni tag e usare il pacchetto NuGet Html2Markdown per convertire HTML in Markdown:

1. Rimuovere <span> gli elementi e <u> .
2. Sostituire <div> gli elementi e <br> con elementi paragrafo (<p>).
3. Convertire il codice HTML rimanente in Markdown.

Passaggi successivi

• Per informazioni sul supporto dei canali nel servizio Bot Connessione or, vedere Connessione un bot ai canali.
• Per informazioni sulla creazione di bot, vedere Come funzionano i bot e Creare un bot con l'avvio rapido di Bot Framework SDK .
• Per informazioni sulla distribuzione di bot, vedere Distribuire il bot e Configurare la distribuzione continua.