Partilhar via

Responder aos comandos de pesquisa

  • Artigo

Importante

Os exemplos de código nesta secção baseiam-se na v4.6 e versões posteriores do SDK do Bot Framework. Se estiver à procura de documentação para versões anteriores, veja a secção Extensões de Mensagens – SDK v3 na pasta Recursos da documentação.

Depois de o utilizador submeter o comando de pesquisa, o serviço Web recebe uma composeExtension/query mensagem de invocação que contém um value objeto com os parâmetros de pesquisa. A invocação é acionada com as seguintes condições:

  • À medida que os carateres são introduzidos na caixa de pesquisa.
  • initialRun está definido como verdadeiro no manifesto da aplicação e recebe a mensagem de invocação assim que o comando de pesquisa for invocado. Para obter mais informações, veja a consulta predefinida.

Este documento orienta-o sobre como responder a pedidos de utilizador sob a forma de cartões e pré-visualizações e as condições em que o Microsoft Teams emite uma consulta predefinida.

Os parâmetros do pedido encontram-se no value objeto no pedido, que inclui as seguintes propriedades:

Nome da propriedade Objetivo
commandId O nome do comando invocado pelo utilizador, que corresponde a um dos comandos declarados no manifesto da aplicação.
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 utilizador.
queryOptions Parâmetros de paginação:
skip: ignorar a contagem para esta consulta
count: número de elementos a devolver.		 
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  // Code to handle the query.
}

Responder a pedidos de utilizador

Quando o utilizador efetua uma consulta, o Microsoft Teams emite um pedido HTTP síncrono ao seu serviço. Nessa altura, o código tem 5 segundos para fornecer uma resposta HTTP ao pedido. Durante este período, o serviço pode efetuar mais pesquisas ou qualquer outra lógica de negócio necessária para servir o pedido.

O seu serviço tem de responder com os resultados correspondentes à consulta do utilizador. A resposta tem de indicar um código de estado HTTP de 200 OK e um objeto JSON ou aplicação válido com as seguintes propriedades:

Nome da propriedade Objetivo
composeExtension Envelope de resposta de nível superior.
composeExtension.type Tipo de resposta. São suportados os seguintes tipos:
result: apresenta uma lista de resultados da pesquisa
auth: pede ao utilizador para se autenticar
config: pede ao utilizador para configurar a extensão da mensagem
message: apresenta uma mensagem de texto simples
composeExtension.attachmentLayout Especifica o esquema dos anexos. Utilizado para respostas do tipo result.
São suportados os seguintes tipos:
list: uma lista de objetos de cartão que contêm campos de miniatura, título e texto
grid: uma grelha de imagens em miniatura
composeExtension.attachments Matriz de objetos de anexo válidos. Utilizado para respostas do tipo result.
São suportados 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. Utilizado para respostas do tipo auth ou config.
composeExtension.text Mensagem a apresentar. Utilizado para respostas do tipo message.

Resposta de configuração

A resposta de configuração são os dados devolvidos pelo servidor ou aplicação para configurar e ativar a extensão de mensagem na plataforma de mensagens. O código seguinte é um exemplo para a configuração da extensão de mensagens:

{
    "name": "composeExtension/submitAction",
    "type": "invoke",
    "timestamp": "2024-03-08T14:10:47.575Z",
    "localTimestamp": "2024-03-08T19:40:47.575+05:30",
    "id": "f:7dfe18de-94e3-9f38-5d44-adeb31cd8243",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1PBlnIsEROUYzpFjULDVodMHrnpujmfhBdQAf0pcO1EkaDkhI0_Pj_ql-jZUYOGdSc3_KcqaIIjzbleraVJ2Z3g",
        "name": "MOD Administrator",
        "aadObjectId": "ce9def33-d7fc-444c-8728-be1f95e6b6f2"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "groupChat",
        "tenantId": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b",
        "id": "19:1dd50ba7-e5bd-46ea-b34e-80a415148de7_ce9def33-d7fc-444c-8728-be1f95e6b6f2@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:9a2b01fc-88c1-40e1-bf87-5079c8e35626",
        "name": "PSDAzureBot"
    },
    "entities": [
        {
            "locale": "en-GB",
            "country": "GB",
            "platform": "Web",
            "timezone": "Asia/Calcutta",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "tenant": {
            "id": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b"
        },
        "source": {
            "name": "compose"
        }
    },
    "value": {
        "commandId": "razorView",
        "commandContext": "compose",
        "data": {
            "Title": "Welcome to RazorView!",
            "DisplayData": " Today&#x27;s date is 8-3-2024, Friday"
        },
        "context": {
            "theme": "default"
        }
    },
    "locale": "en-GB",
    "localTimezone": "Asia/Calcutta"
}

A seguinte resposta é a resposta de configuração que aparece quando o utilizador interage com a extensão de composição:

{
    "composeExtension": {
        "type": "config",
        "suggestedActions": {
            "actions": [
                {
                    "type": "openUrl",
                    "value": "https://7a03-2405-201-a00c-7191-b472-ff64-112d-f806.ngrok-free.app"
                }
            ]
        }
    }
}

A captura de ecrã mostra a resposta de configuração para a extensão da mensagem.

Tipos e pré-visualizações de cartões de resposta

Observação

Os resultados da pesquisa da extensão de mensagem não suportam o preenchimento.

O Teams suporta os seguintes tipos de cartão:

Para ter uma melhor compreensão e descrição geral sobre cartões, veja o que são cartões.

Para saber como utilizar os tipos de cartões de miniatura e de destaque, consulte Adicionar cartões e ações de cartões.

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

A lista de resultados é apresentada na IU do Microsoft Teams com uma pré-visualização de cada item. A pré-visualização é gerada de uma das duas formas:

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

Para o cartão Destaque ou Miniatura, exceto a ação de invocação, outras ações, como o botão e o toque, não são suportadas no cartão de pré-visualização.

Para enviar um Cartão Ajustável ou um cartão de conector para grupos do Microsoft 365, tem de incluir uma pré-visualização. A preview propriedade tem de ser um cartão Hero ou Thumbnail. Se não especificar a propriedade de pré-visualização no attachment objeto, não será gerada uma pré-visualização.

Para cartões De Destaque e Miniatura, não precisa de especificar uma propriedade de pré-visualização, uma pré-visualização é gerada por predefiniçã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
      }
  };
}

Ativar e processar 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 }
        }
    });
}

Consulta predefinida

Se definir initialRun como true no manifesto, o Microsoft Teams emite uma consulta predefinida quando o utilizador abre a extensão da mensagem pela primeira vez. O seu serviço pode responder a esta consulta com um conjunto de resultados pré-preenchidos. Isto é útil quando o comando de pesquisa requer autenticação ou configuração, apresentando itens visualizados recentemente, favoritos ou qualquer outra informação que não dependa da entrada do utilizador.

A consulta predefinida tem a mesma estrutura que qualquer consulta de utilizador normal, com o name campo definido initialRun como 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. Procura pacotes de deslocamento e apresenta os resultados na extensão de mensagens baseada em pesquisa. View View View
Autenticação e configuração da extensão de mensagens do Teams Este exemplo mostra uma extensão de mensagem que tem uma página de configuração, aceita pedidos de pesquisa e devolve resultados após o utilizador iniciar sessão. Também mostra a ligação de instalação zero da aplicação a desenrolar-se juntamente com a desfraldamento normal da ligação View View View

Próxima etapa

Adicionar autenticação de terceiros à extensão de mensagens

Confira também