Responder aos comandos de pesquisa

  • Artigo

Importante

Os exemplos de código nesta seção são baseados em versões v4.6 e posteriores do SDK do Bot Framework. Se você estiver procurando documentação para versões anteriores, consulte a seção Extensões de Mensagem – v3 SDK na pasta Recursos da documentação.

Depois que o usuário envia o comando de pesquisa, seu serviço Web recebe uma composeExtensions/query mensagem de invocação que contém um value objeto com os parâmetros de pesquisa. A invocação é disparada com as seguintes condições:

  • À medida que os caracteres são inseridos na caixa de pesquisa.
  • initialRun é definido como true no manifesto do aplicativo, você recebe a mensagem de invocação assim que o comando de pesquisa é invocado. Para obter mais informações, consulte consulta padrão.

Este documento orienta como responder às solicitações de usuário na forma de cartões e visualizações e as condições em que o Microsoft Teams emite uma consulta padrão.

Os parâmetros de solicitação são encontrados no value objeto na solicitação, que inclui as seguintes propriedades:

Nome da propriedade Objetivo
commandId O nome do comando invocado pelo usuário, correspondendo a um dos comandos declarados no manifesto do aplicativo.
parameters Matriz de parâmetros. Cada objeto de parâmetro contém o nome do parâmetro, juntamente com o valor do parâmetro fornecido pelo usuário.
queryOptions Parâmetros de paginação:
skip: ignorar contagem para esta consulta
count: número de elementos a serem retornados.		 
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  // Code to handle the query.
}

Responder a solicitações de usuário

Quando o usuário executa uma consulta, o Microsoft Teams emite uma solicitação HTTP síncrona ao seu serviço. Nesse ponto, seu código tem 5 segundos para fornecer uma resposta HTTP à solicitação. Durante esse tempo, seu serviço pode executar uma pesquisa adicional ou qualquer outra lógica de negócios necessária para atender à solicitação.

Seu serviço deve responder com os resultados correspondentes à consulta de usuário. A resposta deve indicar um código HTTP status de 200 OK e um aplicativo válido ou objeto JSON com as seguintes propriedades:

Nome da propriedade Objetivo
composeExtension Envelope de resposta de nível superior.
composeExtension.type Tipo de resposta. Há suporte para os seguintes tipos:
result: exibe uma lista de resultados da pesquisa
auth: solicita que o usuário se autentique
config: solicita que o usuário configure a extensão da mensagem
message: exibe uma mensagem de texto simples
composeExtension.attachmentLayout Especifica o layout dos anexos. Usado para respostas do tipo result.
Atualmente, há suporte para os seguintes tipos:
list: uma lista de objetos cartão que contêm campos de miniatura, título e texto
grid: uma grade de imagens de miniatura
composeExtension.attachments Matriz de objetos de anexo válidos. Usado para respostas do tipo result.
Atualmente, há suporte para os seguintes tipos:
application/vnd.microsoft.card.thumbnail
application/vnd.microsoft.card.hero
application/vnd.microsoft.teams.card.o365connector
application/vnd.microsoft.card.adaptive
composeExtension.suggestedActions Ações sugeridas. Usado para respostas do tipo auth ou config.
composeExtension.text Mensagem a ser exibida. Usado para respostas do tipo message.

Tipos e visualizações de cartão de resposta

O Teams dá suporte aos seguintes tipos de cartão:

Para ter uma melhor compreensão e visão geral dos cartões, confira o que são cartões.

Para saber como usar os tipos de miniatura e cartão de herói, consulte adicionar cartões e cartão ações.

Para obter mais informações sobre o conector cartão para Grupos do Microsoft 365, consulte Usando cartões de conector para Grupos do Microsoft 365.

A lista de resultados é exibida na interface do usuário do Microsoft Teams com uma visualização de cada item. A visualização é gerada de uma das duas maneiras:

  • Usando a preview propriedade dentro do attachment objeto. O preview anexo só pode ser um Hero ou uma miniatura cartão.
  • Extração das propriedades básicas title, texte image do attachment objeto. As propriedades básicas serão usadas somente se a preview propriedade não for especificada.

Para hero ou miniatura cartão, exceto a ação de invocação outras ações, como botão e toque, não têm suporte no cartão de visualização.

Para enviar um cartão adaptável ou cartão de conector para Grupos do Microsoft 365, você deve incluir uma visualização. A preview propriedade deve ser uma cartão hero ou miniatura. Se você não especificar a propriedade de visualização no attachment objeto, uma visualização não será gerada.

Para cartões Hero e Miniatura, você não precisa especificar uma propriedade de visualização, uma visualização é gerada por padrão.

Exemplo de resposta

protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken) 
{
  var text = query?.Parameters?[0]?.Value as string ?? string.Empty;

  // Searches NuGet for a package.
  var obj = JObject.Parse(await (new HttpClient()).GetStringAsync($"https://azuresearch-usnc.nuget.org/query?q=id:{text}&prerelease=true"));
  var packages = obj["data"].Select(item => (item["id"].ToString(), item["version"].ToString(), item["description"].ToString()));

  // We take every row of the results and wrap them in cards wrapped in in MessagingExtensionAttachment objects.
  // The Preview is optional, if it includes a Tap, that will trigger the OnTeamsMessagingExtensionSelectItemAsync event back on this bot.
  var attachments = packages.Select(package => new MessagingExtensionAttachment
      {
          ContentType = HeroCard.ContentType,
          Content = new HeroCard { Title = package.Item1 },
          Preview = new HeroCard { Title = package.Item1, Tap = new CardAction { Type = "invoke", Value = package } }.ToAttachment()
      })
      .ToList();

  // The list of MessagingExtensionAttachments must we wrapped in a MessagingExtensionResult wrapped in a MessagingExtensionResponse.
  return new MessagingExtensionResponse
  {
      ComposeExtension = new MessagingExtensionResult
      {
          Type = "result",
          AttachmentLayout = "list",
          Attachments = attachments
      }
  };
}

Habilitar e manipular ações de toque

protected override Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(ITurnContext<IInvokeActivity> turnContext, JObject query, CancellationToken cancellationToken)
{
    // The Preview card's Tap should have a Value property assigned, this will be returned to the bot in this event.
    var (packageId, version, description, projectUrl, iconUrl) = query.ToObject<(string, string, string, string, string)>();

    var card = new ThumbnailCard
    {
        Title = "Card Select Item",
        Subtitle = description
    };

    var attachment = new MessagingExtensionAttachment
    {
        ContentType = ThumbnailCard.ContentType,
        Content = card,
    };

    return Task.FromResult(new MessagingExtensionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            Type = "result",
            AttachmentLayout = "list",
            Attachments = new List<MessagingExtensionAttachment> { attachment }
        }
    });
}

Observação

OnTeamsMessagingExtensionSelectItemAsync não é disparado no aplicativo do Teams móvel.

Consulta padrão

Se você definir initialRun como true no manifesto, o Microsoft Teams emitirá uma consulta padrão quando o usuário abrir a extensão da mensagem pela primeira vez. Seu serviço pode responder a essa consulta com um conjunto de resultados pré-preenchidos. Isso é útil quando o comando de pesquisa requer autenticação ou configuração, exibindo itens, favoritos ou qualquer outra informação que não dependa da entrada do usuário.

A consulta padrão tem a mesma estrutura que qualquer consulta de usuário regular, com o name campo definido como initialRun e value definido true como mostrado no seguinte objeto:

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "initialRun",
        "value": "true"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  ⋮
}

Exemplo de código

Nome do exemplo Descrição .NET Node.js Manifesto
Pesquisa de extensão de mensagem do Teams Este exemplo mostra como criar uma extensão de mensagem baseada em pesquisa. Ele pesquisa pacotes de cutucadas e exibe os resultados na extensão de mensagens baseada em pesquisa. View View Exibir
Auth e configuração da extensão de Mensagem do Teams Este exemplo mostra uma extensão de mensagem que tem uma página de configuração, aceita solicitações de pesquisa e retorna resultados após a entrada do usuário. Ele também mostra a desenrolação do link de instalação de aplicativo zero, juntamente com a desenrolação de link normal View View Exibir

Próxima etapa

Adicionar autenticação a uma extensão de mensagem

Confira também