Connettere un bot alla 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).

Annotazioni

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. Nel 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

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

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 alla scheda Esporre un'API.
  7. Seleziona Aggiungi un ambito.
    1. Nel riquadro Aggiungi un ambito consigliamo di mantenere l'URI ID dell'applicazione generato automaticamente. Selezionare Salva e continua.
    2. Immettere il nome dell'ambito.
    3. Per Chi può fornire il consenso?, gli amministratori e gli utenti sono preferiti, ma entrambe le opzioni funzioneranno.
    4. Immettere un nome del consenso amministratore da visualizzare e una descrizione del consenso amministratore.
    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. Selezionare Aggiungere un'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.

Implementa il tuo bot

Il canale Search invia ogni query utente al tuo bot come un'attività di tipo "invoke" con il nome "application/search". Il bot restituisce i risultati della query nella risposta invoke. Utilizzare il formato Adaptive Card per i risultati della query inviati al canale di ricerca.

  1. Aggiorna qualsiasi pacchetto "Bot Framework" e "Adaptive Cards" nel tuo progetto all'ultima versione.
  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à di invocazione. È possibile decidere di registrare l'ID di traccia della richiesta. Usare la proprietà del dato di canale traceId per ottenere l'ID di tracciamento.

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 della proprietà TIPO Description
authType numero intero Tipo di token di autenticazione: 0 per token sconosciuto o predefinito o 2 per il token on-behalf-of.
token corda 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 dei token On-Behalf-Of, consultare la piattaforma di identità Microsoft e il flusso On-Behalf-Of di 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 della proprietà TIPO Description
queryText corda Testo della query.
tipo/gentile corda 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 numero intero Indice del primo risultato da inviare.
queryOptions.top numero intero 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 della proprietà TIPO Description
    Codice di stato numero intero Codice di stato HTTP usato per indicare se il bot è riuscito a eseguire correttamente la query.
    type corda 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 della proprietà TIPO Description
    codice corda Codice di errore definito dal bot o null se non specificato.
    message corda Messaggio di errore o null se non specificato.

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

    Nome della proprietà TIPO Description
    results matrice di oggetti risultato di ricerca I risultati, o null se nessuno.
    displayLayouts matrice di oggetti layout di visualizzazione Layout di visualizzazione o null se nessuno.
    totalResultCount numero intero I risultati totali disponibili, se l'impaginazione è supportata; in caso contrario, null.
    più risultati disponibili Boolean Indica se sono disponibili più risultati.

    Gli oggetti risultato della ricerca contengono:

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

    Gli oggetti layout di visualizzazione contengono:

    Nome della proprietà TIPO Description
    layoutId corda L'ID del layout.
    corpo del layout corda Il corpo del layout come oggetto JSON di Adaptive Cards.

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.

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. Apri la risorsa bot.

  3. Aprire il riquadro Canali (anteprima).

  4. Seleziona Cerca.

  5. Nella scheda Impostazioni di ricerca immettere le informazioni per il bot.

    Esempio della scheda Impostazioni di ricerca

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

    2. Definire le frasi che rappresentano delle query a cui il bot può rispondere, sotto Frasi trigger.

      Annotazioni

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

      • Caricare il .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. Usa l'URI ID dell'applicazione che hai copiato quando hai esposto l'API per il tuo bot.

    4. Seleziona Avanti.

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

  7. Nella scheda Tenant Publishing, esaminare le impostazioni e aggiungere le informazioni di pubblicazione.

    1. Rivedere il nome del fornitore 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 fornitore di servizi di ricerca in un tenant specifico

L'approvazione del provider di ricerca nel tenant viene effettuata da un amministratore IT nella pagina Ricerca e intelligencenell'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. Nel portale di Azure, vai 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. Nel portale di Azure, vai 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 di attivazione

Una frase di attivazione è una frase che la piattaforma di ricerca utilizza per instradare una query al provider di ricerca personalizzato alimentato dal tuo 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 domande sugli orari di arrivo o di partenza e sugli aeroporti.

Le frasi trigger per un bot per la pianificazione dei voli del programma di volo e dello 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
  • Il massimo di oggi
  • La possibilità di pioggia di oggi
  • Nevicherà domani?
  • 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 Gestisci i layout dei risultati di ricerca di Microsoft Search e lo Schema Explorer delle 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 renderizzerà il 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 gli elementi <span> e <u>.
  2. Sostituire gli elementi <div> e <br> con elementi di paragrafo <p>.
  3. Convertire il codice HTML rimanente in Markdown.

Passaggi successivi

  • Last updated on