Definir comandos de pesquisa de extensão de mensagem

O comando de pesquisa é invocado de qualquer um ou ambos os seguintes locais:

• Área redigir mensagem: os botões na parte inferior da área de mensagem de redação.
• Caixa de comando: usando /na caixa de comando. Por exemplo, /your-app-name. Se você estiver usando o teams clássico, o comando de pesquisa será invocado na @mentioning caixa de comando. Por exemplo, @your-app-name.

Quando um comando de pesquisa é invocado da área de mensagem de composição, o usuário envia os resultados para a conversa. Quando um comando de pesquisa invocado da caixa de comando, o usuário interage com o cartão resultante ou copia-o para uso em outro lugar.

A imagem a seguir exibe os locais de invocação do comando de pesquisa:

Adicionar o comando de pesquisa ao manifesto do aplicativo

Para adicionar o comando de pesquisa ao manifesto do aplicativo (anteriormente chamado de manifesto do aplicativo teams), você deve adicionar um novo composeExtensions objeto ao nível superior do JSON do manifesto do aplicativo. Você pode adicionar o comando de pesquisa com a ajuda do Portal do Desenvolvedor ou manualmente.

Criar extensão de mensagem de pesquisa usando o Bot Framework

Você pode criar uma extensão de mensagem de pesquisa usando o Teams Toolkit e o Portal do Desenvolvedor para o Teams.

Pré-requisitos

Antes de começar, verifique se você atende aos seguintes requisitos:

• Node.js. As versões com suporte são 16, 18.
• Conta do Microsoft 365 para desenvolvimento
• Configure seu ambiente de desenvolvimento para estender aplicativos do Teams no Microsoft 365. Depois de registrar o locatário do desenvolvedor no Office 365 Versão Direcionada, pode levar alguns dias para que o registro entre em vigor.
• Teams Toolkit Visual Studio Code Extension versão 5.2.0 e superior ou CLI do Teams Toolkit.

Kit de ferramentas do Teams

Para criar uma extensão de mensagem baseada em pesquisa usando o Teams Toolkit, siga estas etapas:

1. Abra o Visual Studio Code.

2. No painel esquerdo, selecione Kit de Ferramentas do Teams.

3. Selecione Criar um Novo Aplicativo.

4. Selecione Extensão de Mensagem.

5. Selecione Resultados da Pesquisa Personalizada.

6. Selecione uma linguagem de programação.

7. Selecione Pasta Padrão.

8. Insira o nome do aplicativo e selecione Inserir.

   O Teams Toolkit faz scaffolds seu projeto e cria uma extensão de mensagem de pesquisa.

Para executar a extensão de mensagem no Teams, siga estas etapas:

1. No painel esquerdo, selecione Kit de Ferramentas do Teams.

2. Em CONTAS, entre com sua conta do Microsoft 365 e a conta do Azure se você ainda não tiver feito isso.

   

3. No painel esquerdo, selecione Executar e Depurar (Ctrl+Shift+D).

4. Na lista suspensa de configuração de inicialização, selecione Preview in Teams (Edge) ou Preview in Teams (Chrome). O Teams Toolkit inicia o cliente Web do Teams em uma janela do navegador.

5. Vá para uma mensagem de chat e selecione o ícone Ações e aplicativos . No menu de sobrevoo, pesquise seu aplicativo.

6. Selecione sua extensão de mensagem na lista e insira um comando de pesquisa na caixa de pesquisa.

7. Selecione um item na lista. O item é desenrolado em um Cartão Adaptável na área de composição de mensagem.

8. Selecione Enviar. O Teams envia o resultado da pesquisa como um Cartão Adaptável na mensagem de chat.

Portal do Desenvolvedor do Teams

1. Acesse Portal do Desenvolvedor para Teams.

2. Acesse Aplicativos.

3. Selecione Criar um novo aplicativo.

4. Em Configurar, selecioneRecursos de aplicativo.

5. Selecione Extensão de mensagens.

   

6. Em Tipo de extensão mensagem, selecione Bot.

   1. Se você receber uma isenção de responsabilidade, que lê a extensão de mensagem de API já está em uso pelos usuários. Deseja alterar o tipo de extensão de mensagem para bot?. Selecione Sim, altere.

   

7. Se você tiver um bot existente, selecione Bot existente ou, se tiver uma ID do bot, selecione Inserir ID do Bot.

   1. Se você não tiver uma ID de bot existente, selecione Criar um bot para criar um bot e insira a ID do bot do novo bot criado.

8. Selecione Salvar.

9. Selecione os escopos necessários.

10. Em Comando, selecione + Adicionar um comando.

    Uma página de detalhes de comando é exibida.

11. Na página Detalhes do Comando, selecione Pesquisar como o tipo de comando e atualize os seguintes campos:

    • ID do comando
    • Título de comando
    • Descrição do comando
    • Contexto em que o comando funciona
    • Nome do parâmetro
    • Título de parâmetro
    • Descrição do parâmetro
    • Selecione o tipo de entrada

12. Selecione Salvar. Uma extensão de mensagem de pesquisa usando a estrutura de bot criada.

13. No canto superior direito, selecione Visualizar no Teams. O aplicativo é aberto na área de trabalho do Teams ou no cliente Web.

Estender a extensão de mensagem baseada em bot como plug-in

Importante

Os plug-ins para Microsoft Copilot para Microsoft 365 estão em versão prévia e funcionam apenas em Microsoft 365 Chat no Teams.

Os plug-ins do Microsoft 365 fornecem integração com vários produtos do Microsoft 365, como Teams e Outlook. A integração ajuda os usuários a pesquisar ou criar conteúdo em sistemas externos. Os plug-ins de extensão de mensagem permitem que Microsoft Copilot para Microsoft 365 interajam com APIs de outros softwares e serviços por meio de um bot. Recomendamos que você crie ou atualize suas extensões de mensagem existentes para maximizar sua utilidade e usabilidade em Copilot para Microsoft 365. Para obter mais informações, consulte estender a extensão de mensagem baseada em bot como plug-in para Copilot para Microsoft 365.

Trechos de código

O código a seguir fornece um exemplo de extensões de mensagem baseadas em pesquisa:

C#

• Referência do SDK
• Referência de código de exemplo

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

            var packages = new[] {
            new { title = "A very extensive set of extension methods", value = "FluentAssertions" },
            new { title = "Fluent UI Library", value = "FluentUI" }};

            // We take every row of the results and wrap them in cards wrapped 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 =>
            {
                var previewCard = new ThumbnailCard { Title = package.title, Tap = new CardAction { Type = "invoke", Value = package } };
                if (!string.IsNullOrEmpty(package.title))
                {
                    previewCard.Images = new List<CardImage>() { new CardImage(package.title, "Icon") };
                }

                var attachment = new MessagingExtensionAttachment
                {
                    ContentType = HeroCard.ContentType,
                    Content = new HeroCard { Title = package.title },
                    Preview = previewCard.ToAttachment()
                };

                return attachment;
            }).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
                }
            };
        }

Node.js

Referência de código de exemplo

async handleTeamsMessagingExtensionQuery(context, query) {
        const searchQuery = query.parameters[0].value;     
        const attachments = [];
                const response = await axios.get(`http://registry.npmjs.com/-/v1/search?${ querystring.stringify({ text: searchQuery, size: 8 }) }`);
                
                response.data.objects.forEach(obj => {
                        const heroCard = CardFactory.heroCard(obj.package.name);
                        const preview = CardFactory.heroCard(obj.package.name);
                        preview.content.tap = { type: 'invoke', value: { description: obj.package.description } };
                        const attachment = { ...heroCard, preview };
                        attachments.push(attachment);
                });
    
                return {
                    composeExtension:  {
                           type: 'result',
                           attachmentLayout: 'list',
                           attachments: attachments
                    }
                };
            }       
        }

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 NuGet e exibe os resultados na extensão de mensagens baseada em pesquisa.	View	View	View

Guias passo a passo

Siga o guia passo a passo para criar uma extensão de mensagem baseada em pesquisa.

Próxima etapa

Responda aos comandos de pesquisa.

Confira também

• Portal do Desenvolvedor do Teams
• Extensões de mensagens