Responder aos comandos de pesquisa
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 composeExtension/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 e 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 consultacount : 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 pesquisaauth : solicita que o usuário se autentiqueconfig : solicita que o usuário configure a extensão da mensagemmessage : 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 textogrid : 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 . |
Resposta de configuração
A resposta de configuração são os dados retornados pelo servidor ou aplicativo para configurar e habilitar a extensão de mensagem dentro da plataforma de mensagens. O código a seguir é um exemplo para a configuração de extensão de mensagem:
{
"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's date is 8-3-2024, Friday"
},
"context": {
"theme": "default"
}
},
"locale": "en-GB",
"localTimezone": "Asia/Calcutta"
}
A resposta a seguir é a resposta de configuração que aparece quando o usuário 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"
}
]
}
}
}
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 doattachment
objeto. Opreview
anexo só pode ser um Hero ou uma miniatura cartão. - Extração das propriedades básicas
title
,text
eimage
doattachment
objeto. As propriedades básicas serão usadas somente se apreview
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 }
}
});
}
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 prepovoados. 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 | View |
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 | View |
Próxima etapa
Confira também
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de