Definir comandos de pesquisa da extensão de mensagens

O comando de pesquisa é invocado a partir de qualquer uma ou ambas as seguintes localizações:

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

Quando um comando de pesquisa é invocado a partir da área de composição de mensagens, o utilizador envia os resultados para a conversação. Quando um comando de pesquisa invocado a partir da caixa de comando, o utilizador interage com o card resultante ou copia-o para utilização noutro local.

A imagem seguinte apresenta as localizações de invocação do comando de pesquisa:

Adicionar o comando de pesquisa ao manifesto da aplicação

Para adicionar o comando de pesquisa ao manifesto da sua aplicação (anteriormente denominado manifesto de aplicação do Teams), tem de adicionar um novo composeExtensions objeto ao nível superior do manifesto de aplicação JSON. Pode adicionar o comando de pesquisa com a ajuda do Portal do Programador ou manualmente.

Criar uma extensão de mensagem de pesquisa com o Bot Framework

Pode criar uma extensão de mensagem de pesquisa com o Teams Toolkit e o Portal do Programador para Teams.

Pré-requisitos

Antes de começar, certifique-se de que cumpre os seguintes requisitos:

• Node.js. As versões suportadas são 16, 18.
• Conta do Microsoft 365 para desenvolvimento
• Configure o seu ambiente de desenvolvimento para expandir as aplicações do Teams no Microsoft 365. Depois de inscrever o inquilino do programador no Office 365 Lançamento Direcionado, a inscrição poderá demorar alguns dias a entrar em vigor.
• O Teams Toolkit Visual Studio Code a versão 5.2.0 e superior ou a CLI do Teams Toolkit.

Kit de ferramentas do Teams

Para criar uma extensão de mensagem baseada em pesquisa com o Teams Toolkit, siga estes passos:

1. Abra o Visual Studio Code.

2. No painel esquerdo, selecione Teams Toolkit.

3. Selecione Criar uma Nova Aplicação.

4. Selecione Extensão da Mensagem.

5. Selecione Resultados de Pesquisa Personalizados.

6. Selecione uma linguagem de programação.

7. Selecione Pasta predefinida.

8. Introduza o nome da sua aplicação e selecione Enter.

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

Para executar a extensão de mensagem no Teams, siga estes passos:

1. No painel esquerdo, selecione Teams Toolkit.

2. Em CONTAS, inicie sessão com a sua conta do Microsoft 365 e a conta do Azure, caso ainda não o tenha feito.

   

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

4. Na lista pendente de configuração de início, selecione Preview in Teams (Edge) ou Preview in Teams (Chrome). O Teams Toolkit inicia o cliente Web do Teams numa janela do browser.

5. Aceda a uma mensagem de chat e selecione o ícone Ações e aplicações . No menu de opções, procure a sua aplicação.

6. Selecione a extensão da mensagem na lista e introduza um comando de pesquisa na caixa de pesquisa.

7. Selecione um item na lista. O item desenrola-se num Cartão Ajustável na área de composição de mensagens.

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

Portal do Desenvolvedor do Teams

1. Aceda ao Portal do Programador do Teams.

2. Aceda a Aplicações.

3. Selecione Criar uma nova aplicação.

4. Em Configurar, selecioneFuncionalidades da aplicação.

5. Selecione Extensão de mensagens.

   

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

   1. Se receber uma exclusão de responsabilidade, que diz API Message extension já está a ser utilizada pelos utilizadores. Pretende alterar o tipo de extensão da mensagem para bot? Selecione Sim, alterar.

   

7. Se tiver um bot existente, selecione Bot existente ou, se tiver um ID de bot, selecione Introduzir ID do Bot.

   1. Se não tiver um ID de bot existente, selecione Criar um bot para criar um novo bot e introduza o ID do bot novo que criou.

8. Selecione Salvar.

9. Selecione os âmbitos necessários.

10. Em Comando, selecione + Adicionar um comando.

    É apresentada uma página de detalhes do comando.

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

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

12. Selecione Salvar. Uma extensão de mensagem de pesquisa com a arquitetura de bot criada.

13. No canto superior direito, selecione Pré-visualizar no Teams. A aplicação é aberta no ambiente de trabalho ou no cliente Web do Teams.

Expandir a extensão de mensagens baseadas em bots como agente

Importante

Os agentes para Microsoft 365 Copilot estão em pré-visualização e só funcionam no Microsoft 365 Copilot no Teams.

Os agentes do Microsoft 365 fornecem integração com vários produtos do Microsoft 365, como o Teams e o Outlook. A integração ajuda os utilizadores a procurar ou criar conteúdos em sistemas externos. Os agentes de extensão de mensagens permitem Microsoft 365 Copilot interagir com APIs de outro software e serviços através de um bot. Recomendamos que crie ou atualize as extensões de mensagens existentes para maximizar a sua utilidade e capacidade de utilização no Microsoft 365 Copilot. Para obter mais informações, veja Extend bot-based message extension as agent for Microsoft 365 Copilot (expandir a extensão de mensagens baseadas em bots como agente para Microsoft 365 Copilot).

Trechos de código

O código seguinte fornece um exemplo de extensões de mensagens 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. Procura em pacotes NuGet e apresenta 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 na pesquisa.

Próxima etapa

Responder a comandos de pesquisa.

Confira também

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