Conectar um bot à pesquisa (preview)

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 de locatários habilitar seu provedor em seu locatário, as pesquisas de usuários corporativos, de Office.com, SharePoint.com e Bing.com, poderão incluir resultados do seu provedor de pesquisa personalizado.

A Plataforma de Pesquisa Federada da Microsoft permite que você crie provedores de pesquisa federados personalizados para permitir que suas informações participem das experiências Respostas e Verticais do Microsoft Search sem a necessidade de mesclar essas informações com o índice do Microsoft 365. Para obter mais informações, confira Como anunciar a preview do desenvolvedor da Plataforma de Pesquisa Federada da Microsoft e a pesquisa federada do Dynamics 365 (preview).

Observação

O canal de pesquisa está em versão prévia privada. Para solicitar acesso, use o formulário de versão prévia privada de desenvolvedores da Pesquisa da Microsoft. 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 em mais detalhes posteriormente 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 a URI de escopo gerada para gerar um token de usuário.
3. Implante um 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 seu bot no locatário.

Dica

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

Pré-requisitos

• Conhecimento de 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 você ainda não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

Você pode implementar seu bot em qualquer uma das linguagens com suporte do SDK do Bot Framework. Este artigo usa o bot de pesquisa federada C# como exemplo.

Expor a API do bot à Pesquisa

Dica

Esta etapa só será 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 do 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 Microsoft Entra ID em nome do usuário.

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

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

Implementar 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". O bot retorna os resultados da consulta na resposta de invocação. Use o formato Cartão Adaptável para os resultados da consulta enviados de volta ao canal de Pesquisa.

1. Atualize todos os pacotes do Bot Framework e dos Cartões Adaptáveis em seu projeto para a última versão.
2. Opcionalmente, selecione adicionar 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 Cartão Adaptável para exibir os resultados.

Obter a ID de rastreamento da plataforma de Pesquisa

A plataforma de pesquisa atribui uma ID de rastreamento exclusiva a cada consulta enviada ao bot. A plataforma a adiciona aos dados de canal da atividade de invocação. Você pode decidir registrar a ID de rastreamento da solicitação. Use a propriedade de dados do canal para obter a ID de rastreamento traceId.

No exemplo de pesquisa federada, o método SearchHelper.GetSearchTraceId 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 authorizations dos 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 da propriedade	Type	Descrição
authType	Número inteiro	O tipo de token de autenticação: 0 para desconhecido ou padrão, ou 2 para token em nome de.
token	string	O próprio token de autenticação.

No exemplo de pesquisa federada:

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

Depois de obter o token, você pode usá-lo quando solicitar qualquer recurso protegido do usuário. Para obter mais informações sobre como usar tokens em nome de, confira plataforma de identidade da Microsoft e fluxo On-Behalf-Of de OAuth 2.0.

armazenamento de dados de Consultas

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

Nome da propriedade	Type	Descrição
queryText	string	O texto da consulta.
kind	string	O tipo de consulta: "pesquisar" 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	Número inteiro	O índice do primeiro resultado a ser enviado.
queryOptions.top	Número inteiro	O número máximo de resultados a serem retornados.

Você retorna os resultados da busca na resposta de invocação:

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

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

  Nome da propriedade	Type	Descrição
  statusCode	Número inteiro	Um código de status HTTP usado para indicar se o bot conseguiu 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 os resultados da busca ou "application/vnd.microsoft.error" para uma mensagem de erro.
  value	objeto	Um valor que corresponde ao valor de type.

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

  Nome da propriedade	Type	Descrição
  code	string	Um código de erro definido pelo bot ou null, se não for especificado.
  message	string	Uma mensagem de erro ou null se não for especificado.

  Para resultados da busca, o objeto value contém:

  Nome da propriedade	Type	Descrição
  results	matriz de objetos de resultado de busca	Os resultados, ou null se não houver nenhum.
  displayLayouts	matriz de objetos de layout de exibição	Os layouts de exibição ou null, se não houver nenhum.
  totalResultCount	Número inteiro	Os resultados totais disponíveis, se houver suporte à paginação; caso contrário, null.
  moreResultsAvailable	Booliano	Indica se existem mais resultados disponíveis.

  Os objetos de resultado de busca contêm:

  Nome da propriedade	Type	Descrição
  value	string	Um identificador exclusivo ou valor para este resultado de busca.
  layoutId	string	A ID do layout de exibição a ser usado para esse resultado.
  data.searchResultText	string	O texto desse resultado.

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

  Nome da propriedade	Type	Descrição
  layoutId	string	A ID do layout.
  layoutBody	string	O corpo do layout como um objeto JSON de Cartões Adaptáveis.

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

Exibir os resultados da busca

Você pode criar verticais de pesquisa e tipos de resultados para personalizar os resultados da busca 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, confira a seção Elementos de Cartões Adaptáveis compatíveis.

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

Registre 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, confira 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.

Dica

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

1. Vá para o Portal do Azure.

2. Kudu o recurso do bot.

3. Kudu o painel de Canais (Preview).

4. Selecione Pesquisar.

5. Na guia Configurações de Pesquisa, insira as informações do bot.

   

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

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

      Observação

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

      • Faça upload de um arquivo .csv que contenha as frases. O arquivo deve conter uma coluna de dados, sem cabeçalhos.
      • Na lista de preferências de Idioma, selecione o idioma no qual as frases de gatilho são escritas.

   3. Em Autenticação, indique se o provedor de pesquisa requer autenticação do usuário.

      • Se a autenticação for necessária, insira a URL de autenticação. Use a URI da ID do Aplicativo que você copiou quando expôs a API ao seu bot.

   4. Selecione Avançar.

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

7. Na guia Publicação de Locatários, revise suas configurações e adicione informações de publicação.

   1. Revise o nome do provedor de pesquisa e os exemplos de consulta. Volte para às guias anteriores para alterar essas informações, se necessário.
   2. Insira uma descrição do seu provedor de pesquisa.
   3. Insira um email de contato de suporte. Use o email 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 Search & Intelligence no Centro de administração do Microsoft 365.

Testar a conexão

Recomendamos que você habilite o provedor de pesquisa em um locatário de teste antes de habilitá-lo em 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. Talvez seja necessário fazer isso se sua solicitação inicial for rejeitada ou seu serviço for desativado.

1. No portal do Azure, acesse o recurso de bot que contém o provedor de pesquisa que deseja editar.
2. Acesse o painel Canais (Preview).
3. Selecione 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 gatilho, faça download do arquivo, edite-o localmente e faça upload do 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, acesse o recurso do seu bot.
2. Acesse o painel Canais (Preview).
3. Selecione o canal de pesquisa.
4. Na parte superior do painel Canal de Pesquisa, selecione Excluir canal.
5. Para confirmar a operação, selecione Sim.

Para excluir recurso do seu bot:

1. No portal do Azure, acesse o recurso do seu bot.
2. Se você ainda não tiver feito isso, remova o canal de pesquisa do seu 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 de Cartões Adaptáveis:

Para obter mais informações sobre o esquema de Cartões Adaptáveis, confira Cartões adaptáveis para desenvolvedores de bots.

Sobre frases de gatilho

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

Dica

Se mais de um provedor de pesquisa estiver disponível, a pesquisa federada escolherá 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 faria uso do 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 abranjam o escopo dos recursos do 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 horário de voo e bot de status podem incluir:

• Horários dos voos
• Status do voo
• Hora de partida do voo 675
• Quando partirá o meu voo
• Hora de chegada do voo 468
• Status do voo para Seattle - Tacoma
• Status do voo para Heathrow

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

• Previsão do clima local
• Informações meteorológicas
• O clima amanhã
• Previsão do clima para 10 dias
• Alta de hoje
• Chance de chuva hoje
• Vai nevar amanhã?
• Velocidade do vento amanhã
• Está ventando lá fora?
• Clima em Londres

Elementos de Cartões Adaptáveis com suporte

Há suporte para um subconjunto do esquema de Cartões Adaptáveis na pesquisa federada. Para obter informações sobre como formatar os resultados da busca, confira Personalizar a página de resultados da busca.

O suporte inclui os seguintes elementos dos Cartões Adaptáveis: TextBlock, RichTextBlock,Imagem,ColumnSet, ImageSet e FactSet. Para obter mais informações, confira Gerenciar layouts de resultados da busca da Pesquisa da Microsoft e o Explorer de esquemas de cartões adaptáveis.

Você pode criar cada cartão diretamente como JSON ou 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 contiver 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. Remova os elementos <span> e <u>.
2. Substitua os elementos <div> e <br> por elementos de parágrafo (<p>).
3. Converta o HTML restante em Markdown.

Próximas etapas

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