Conectar um bot à Pesquisa (visualização)

Este artigo descreve como criar um provedor de pesquisa federado personalizado (alimentado pelo bot) e conectá-lo ao canal de pesquisa. Depois que o administrador do locatário habilita seu provedor em seu locatário, as pesquisas de usuários corporativos, de Office.com, SharePoint.com e Bing.com, podem incluir resultados de seu provedor de pesquisa personalizado.

A Microsoft Federated Search Platform permite que você crie provedores de pesquisa federados personalizados para permitir que suas informações participem das experiências Answers & Vertical do Microsoft Search sem a necessidade de mesclar essas informações com seu índice do Microsoft 365. Para obter mais informações, consulte Anunciando a visualização do desenvolvedor da Plataforma de Pesquisa Federada da Microsoft e a pesquisa de federação do Dynamics 365 (visualização).

Nota

O canal de pesquisa está em pré-visualização privada. Para solicitar acesso, use o formulário Microsoft Search Developer Private Preview. Na pergunta 7, selecione Pesquisa Federada.

As etapas a seguir são necessárias para conectar seu bot ao canal de pesquisa. Essas etapas são descritas com mais detalhes mais adiante neste artigo.

1. Implemente seu bot para funcionar como um provedor de pesquisa.
2. Se o bot exigir que os usuários estejam conectados:
   1. No portal do Azure, exponha a API do bot à plataforma de pesquisa.
   2. No código do bot, use o URI de escopo gerado para gerar um token de usuário.
3. Implante seu bot no Azure.
4. Adicione o canal de pesquisa ao seu bot.
5. Peça ao administrador de TI para revisar o registro do bot e publicar o bot no locatário.

Gorjeta

Recomendamos que você habilite o provedor de pesquisa em um locatário de teste antes de habilitá-lo na produção.

Pré-requisitos

• Conhecimento das noções básicas do Bot Framework Service e como criar um bot com o Bot Framework SDK.
• O bot para se conectar ao canal.
• Se não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

Você pode implementar seu bot em qualquer um dos idiomas suportados pelo Bot Framework SDK. Este artigo usa o bot de pesquisa federada C# como exemplo.

Expor a API do bot à Pesquisa

Gorjeta

Esta etapa só é necessária se o bot exigir acesso a recursos de usuário protegidos.

Em alguns fluxos de trabalho de negócios, um bot pode exigir credenciais de usuário para executar uma ação em nome do usuário. Para criar uma experiência de logon único (SSO) para seu bot no canal de pesquisa, você deve permitir que a plataforma de pesquisa proteja um token de acesso do ID do Microsoft Entra em nome do usuário.

Para gerar um URI de escopo e ID de aplicativo para seu bot:

1. Aceda ao portal do Azure.
2. Se você ainda não tiver um recurso de bot, crie um recurso de Bot do Azure.
3. Vá para o serviço Microsoft Entra ID .
4. Aceda ao painel Registos de aplicações.
5. Selecione o aplicativo associado ao seu bot.
6. Vá para o painel Expor uma API .
7. Selecione Adicionar âmbito.
   1. No painel Adicionar um escopo, recomendamos que você mantenha o URI de ID do Aplicativo gerado automaticamente. Selecione Guardar e continuar.
   2. Insira um nome de escopo.
   3. Para Quem pode consentir?, Administradores e usuários é preferível, mas ambas as opções funcionarão.
   4. Insira um nome de exibição de consentimento de administrador e uma descrição de consentimento de administrador.
   5. Opcionalmente, insira um nome de exibição de consentimento de usuário e uma descrição de consentimento de usuário.
   6. Verifique se Estado está definido como Habilitado.
   7. Selecione Adicionar escopo.
8. Selecione Adicionar um aplicativo cliente.
   1. No painel Adicionar um aplicativo cliente, defina ID do Cliente como 81473081-50b9-469a-b9d8-303109583ecb, ID do cliente da plataforma de Pesquisa.
   2. Em Escopos autorizados, selecione o URI de escopo criado na etapa anterior.
   3. Selecione Adicionar aplicativo.
9. Vá para o painel Visão geral . Copie o URI da ID do aplicativo. Você precisará disso quando registrar seu bot no canal de pesquisa.

Implemente seu bot

O canal de pesquisa envia cada consulta de usuário para seu bot como uma atividade de invocação com um nome de "aplicativo/pesquisa". Seu bot retorna os resultados da consulta na resposta de invocação. Use o formato Adaptive Card para os resultados da consulta enviados de volta para o canal de pesquisa.

1. Atualize qualquer Bot Framework e pacotes Adaptive Cards em seu projeto para a versão mais recente.
2. Opcionalmente, adicione código de autenticação para gerar um token de usuário.
3. Implemente um método de pesquisa de dados para cada fonte de dados a ser incluída.
4. Gere o Adaptive Card para exibir os resultados.

Obter o ID de rastreamento da plataforma de pesquisa

A plataforma de pesquisa atribui um ID de rastreamento exclusivo a cada consulta que envia ao seu bot. A plataforma adiciona isso aos dados do canal da atividade de invocação. Você pode decidir registrar a ID de rastreamento da solicitação. Use a propriedade de dados do traceId canal para obter a ID de rastreamento.

No exemplo de pesquisa federada, o SearchHelper.GetSearchTraceId método demonstra como obter a ID de rastreamento da atividade de invocação.

Adicionar autenticação

Se você expôs sua API de bot à Pesquisa e solicitou autenticação quando conectou seu bot à Pesquisa, poderá obter o token de autenticação do usuário dos dados do canal da atividade.

A propriedade dos authorizations dados do canal pode conter uma lista de tokens de autenticação. Se você expor sua API de bot à Pesquisa, a lista conterá o token em nome de. O token na lista terá a seguinte estrutura:

Nome de Propriedade	Tipo	Description
authType	integer	O tipo de token de autenticação: 0 para desconhecido ou padrão, ou 2 para token em nome de.
token	string	O token de autenticação em si.

No exemplo de pesquisa federada:

• A SearchBotAuthenticationToken classe e a AuthenticationTypes enumeração representam essas informações.
• O SearchHelper.GetSearchOboToken método demonstra como obter o token da atividade invoke.

Depois de ter o token, você pode usá-lo quando solicitar quaisquer recursos protegidos para o usuário. Para obter informações sobre como usar tokens em nome de, consulte Microsoft identity platform e OAuth 2.0 On-Behalf-Of flow.

Consultar cada armazenamento de dados

O canal de pesquisa envia uma consulta ao bot como uma invoke atividade, com os detalhes da consulta na propriedade da value atividade, que representa um objeto JSON com a seguinte estrutura:

Nome de Propriedade	Tipo	Description
queryText	string	O texto da consulta.
variante	string	O tipo de consulta: "pesquisa" quando os resultados serão exibidos em uma guia vertical personalizada, ou "searchAnswer" quando um resultado será exibido como uma resposta na guia Todos .
queryOptions	objeto	Opções de consulta adicionais usadas para paginação.
queryOptions.skip	integer	O índice do primeiro resultado a enviar.
queryOptions.top	integer	O número máximo de resultados a enviar.

Você retorna os resultados da pesquisa na resposta invoke:

• Sempre defina a propriedade do Status objeto de resposta invoke como , o 200que indica que a conexão de rede está correta. A propriedade do objeto tem um código de Body status separado.

• A Body propriedade representa um objeto JSON com a seguinte estrutura:

  Nome de Propriedade	Tipo	Description
  statusCode	integer	Um código de status HTTP usado para indicar se o bot foi capaz de executar a consulta com êxito.
  tipo	string	O tipo da resposta de invocação, definindo o formato do campo de valor. Use "application/vnd.microsoft.search.searchResponse" para resultados de pesquisa ou "application/vnd.microsoft.error" para uma mensagem de erro.
  valor	objeto	Um valor que corresponde ao valor type.

  Para mensagens de erro, o value objeto contém:

  Nome de Propriedade	Tipo	Description
  code	string	Um código de erro definido pelo bot ou null , se não especificado.
  mensagem	string	Uma mensagem de erro ou null se não for especificado.

  Para os resultados da pesquisa, o value objeto contém:

  Nome de Propriedade	Tipo	Description
  Resultados	Matriz de objetos de resultado de pesquisa	Os resultados, ou null se nenhum.
  displayLayouts	Matriz de objetos de layout de exibição	Os layouts de exibição ou null , se nenhum.
  totalResultCount	integer	O total de resultados disponíveis, se a paginação for suportada; caso contrário, null.
  maisResultadosDisponível	Boolean	Indica se mais resultados estão disponíveis.

  Os objetos de resultado da pesquisa contêm:

  Nome de Propriedade	Tipo	Description
  valor	string	Um identificador ou valor exclusivo para este resultado de pesquisa.
  layoutId	string	A ID do layout de exibição a ser usado para esse resultado.
  data.searchResultText	string	O texto para este resultado.

  Os objetos de layout de exibição contêm:

  Nome de Propriedade	Tipo	Description
  layoutId	string	O ID do layout.
  layoutCorpo	string	O corpo do layout como um objeto JSON Adaptive Cards.

No exemplo de pesquisa federada, o SearchHelper.RunFederatedSearch método demonstra como obter as informações de consulta da atividade de chamada e como formatar a resposta de invocação.

Apresentar os resultados da pesquisa

Você pode criar verticais de pesquisa e tipos de resultados para personalizar os resultados da pesquisa que os usuários veem quando pesquisam no SharePoint, Office e Bing. As verticais tornam mais fácil para os usuários encontrar as informações que eles têm permissão para ver. Para obter mais informações, consulte a seção Elementos do cartão adaptável suportados.

Se o bot receber uma consulta para a qual não tem resposta, sua resposta deverá conter uma resposta vazia.

Registrar seu bot no Azure

Para conectar seu bot ao canal de Pesquisa, você deve ter um recurso de bot provisionado no Azure. Para obter mais informações, consulte como registrar um bot no Azure ou como implantar seu bot no Azure.

Conecte seu bot à Pesquisa

As instruções a seguir mostram como conectar um bot à Pesquisa.

Gorjeta

Recomendamos que você habilite o provedor de pesquisa em um locatário de teste antes de habilitá-lo na produção.

1. Aceda ao portal do Azure.

2. Abra seu recurso de bot.

3. Abra o painel Canais (Pré-visualização ).

4. Selecionar Pesquisa.

5. Na guia Configurações de pesquisa, insira informações para seu bot.

   

   1. Em Metadados do Provedor de Pesquisa, digite o nome a ser exibido na interface do usuário de pesquisa.

   2. Em Frases de gatilho, defina as frases que representam as consultas que seu bot pode responder.

      Nota

      Para versões iniciais, apenas o inglês (en-US) está disponível.

      • Carregue um .csv ficheiro que contenha as frases. O arquivo deve conter uma coluna de dados, sem cabeçalhos.
      • Na lista Preferência de idioma, selecione o idioma no qual as frases de gatilho são escritas.

   3. Em Autenticação, indique se o seu fornecedor de pesquisa requer autenticação de utilizador.

      • Se a autenticação for necessária, insira o URL de autenticação. Use o URI de ID do aplicativo copiado quando expôs a API do bot.

   4. Selecione Seguinte.

6. Na guia Verticais, se você quiser que os resultados do seu provedor de pesquisa apareçam em sua própria vertical personalizada na página de resultados da pesquisa, insira o nome vertical no campo, caso contrário, deixe esse campo vazio. Em seguida, selecione Seguinte.
   A página de resultados da pesquisa destina-se a Office.com, SharePoint.com e Bing.com.

7. No separador Publicação de Inquilino, reveja as suas definições e adicione informações de publicação.

   1. Analise o nome do provedor de pesquisa e as consultas de exemplo. Volte às guias anteriores para alterar essas informações, se necessário.
   2. Introduza uma descrição do seu fornecedor de pesquisa.
   3. Insira um e-mail de contato de suporte. Use o e-mail de um desenvolvedor ou grupo de desenvolvedores que tenha acesso ao provedor de pesquisa.

8. Selecione Adicionar para solicitar a aprovação do administrador de TI.

Aprovar um provedor de pesquisa em um locatário

A aprovação do provedor de pesquisa no locatário é feita por um administrador de TI na página Pesquisa & Inteligência no centro de administração do Microsoft 365.

Testar a ligação

Recomendamos que você habilite o provedor de pesquisa em um locatário de teste antes de habilitá-lo na produção.

Modificar um provedor de pesquisa

Você pode editar o provedor de pesquisa antes de enviá-lo para revisão pelo administrador de TI. Poderá ter de o fazer se o seu pedido inicial for rejeitado ou se o seu serviço for desativado.

1. No portal do Azure, vá para o recurso de bot que contém o provedor de pesquisa que você deseja editar.
2. Vá para o painel Canais (Pré-visualização ).
3. Selecione o canal de pesquisa e selecione Editar.
   1. O Azure exibe o painel Canal de Pesquisa. Neste painel, você pode editar suas configurações.
   2. Para modificar as frases de acionamento, baixe o arquivo, edite-o localmente e carregue o arquivo.
   3. Depois de concluir as edições, selecione Adicionar novamente para enviar o provedor de pesquisa para revisão pelo administrador de TI.

Excluir um provedor de pesquisa

Seu provedor de pesquisa será excluído se você remover o canal de pesquisa do recurso de bot.

Para remover o canal de pesquisa do bot:

1. No portal do Azure, vá para seu recurso de bot.
2. Vá para o painel Canais (Pré-visualização ).
3. Selecione o canal de pesquisa.
4. Na parte superior do painel Canal de Pesquisa, selecione Excluir canal.
5. Selecione Sim para confirmar a operação.

Para excluir seu recurso de bot:

1. No portal do Azure, vá para seu recurso de bot.
2. Se ainda não o fez, remova o canal de pesquisa do bot.
3. Na parte superior do painel Visão geral , selecione Excluir.
4. Selecione OK para confirmar a operação.

Informações adicionais

O canal de pesquisa usa a pesquisa federada e o esquema Adaptive Cards:

Para obter mais informações sobre o esquema do Adaptive Card, consulte Adaptive Cards para desenvolvedores de bots.

Sobre frases de gatilho

Uma frase de gatilho é uma frase que a plataforma de pesquisa usa para rotear uma consulta para seu provedor de pesquisa personalizado alimentado por seu bot. A pesquisa federada encaminha o enunciado de um usuário para seu provedor de pesquisa quando o enunciado é uma correspondência próxima a uma das frases de gatilho.

Gorjeta

Se mais de um provedor de pesquisa estiver disponível, a pesquisa federada escolhe apenas um, com base nas frases de gatilho fornecidas e na consulta do usuário.

Como exemplo, pense em um bot que gerencia horários e status de voos.

1. Pense em algumas maneiras comuns pelas quais um usuário se referiria ou usaria seu bot. Certifique-se de distinguir seu bot dos outros.

   Em vez de um termo genérico, como "horário", que pode se aplicar a escolas e programas de TV, use frases mais específicas, como "tabela de tempo de voo" e "horário de voo".

2. Inclua diversas frases que abrangem o escopo dos recursos do seu bot, como horário de partida e status atual.

   Por exemplo, inclua consultas sobre: horários de chegada ou partida e aeroportos.

As frases de gatilho para tal cronograma de voo e bot de status podem incluir:

• Horário de voo
• Estado do voo
• Hora de partida do voo 675
• Quando partirá o meu voo
• Hora de chegada do voo 468
• Estado do voo para Seattle Tacoma
• Estado do voo de Heathrow

Como outro exemplo, as frases de gatilho para um bot de previsão do tempo podem incluir:

• Previsão meteorológica local
• Informações meteorológicas
• O tempo de amanhã
• Previsão do tempo para 10 dias
• Alta de hoje
• Chance de chuva de hoje
• Será que vai nevar amanhã
• Velocidade do vento amanhã
• Está ventando lá fora
• Tempo em Londres

Elementos de cartão adaptável suportados

Um subconjunto do esquema Adaptive Card é suportado na pesquisa federada. Para obter informações sobre como formatar os resultados da pesquisa, consulte Personalizar a página de resultados da pesquisa.

O suporte inclui os seguintes elementos Adaptive Card: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet e FactSet. Para obter mais informações, consulte Gerenciar layouts de resultados de pesquisa da Pesquisa da Microsoft e Adaptive Cards Schema Explorer.

Você pode criar cada cartão diretamente como JSON ou pode usar o pacote NuGet AdaptiveCards .

A pesquisa federada não suporta HTML

Importante

A pesquisa federada não renderizará o texto do Cartão Adaptável que contenha HTML.

A plataforma de pesquisa não inclui um analisador HTML. No entanto, você pode eliminar algumas das tags e usar o pacote NuGet Html2Markdown para converter HTML em Markdown :

1. Remover <span> e <u> elementos.
2. Substitua <div> e <br> elementos por elementos de parágrafo (<p>).
3. Converta o HTML restante em Markdown.

Próximos passos

• Para obter informações sobre o suporte a canais no Bot Connector Service, consulte Conectar um bot a canais.
• Para obter informações sobre como criar bots, consulte Como os bots funcionam e o Guia de início rápido Criar um bot com o SDK do Bot Framework.
• Para obter informações sobre como implantar bots, consulte Implantar seu bot e Configurar a implantação contínua.