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 Toolkit de Agentes do Microsoft 365 (anteriormente conhecido como Toolkit do Teams) 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.
• Agents Toolkit Visual Studio Code Extension versão 5.2.0 e superior ou Microsoft 365 Agents Toolkit CLI (anteriormente conhecido como CLI do Teams Toolkit).

Toolkit de Agentes

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

1. Abra o Visual Studio Code.

2. No painel esquerdo, selecione Microsoft 365 Agents Toolkit.

3. Selecione Criar um Novo Agente/Aplicação doTeams de Aplicações>.

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 Toolkit de Agentes 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 Microsoft 365 Agents 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 Toolkit de Agentes 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:

.NET

• 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
                    }
                };
            }       
        }

Python

async def on_teams_messaging_extension_query(self, context, query):
    """
    Handles Messaging Extension queries in Teams.
 
    This method generates a list of thumbnail cards containing random text and images when the "getRandomText" command is triggered. It creates preview cards with tap actions and returns them as a Messaging Extension response.
    """
    faker = Faker()
    title = query.command_id
    random_image_url = "https://loremflickr.com/200/200"

    if query.command_id == "getRandomText":
        attachments = []
        # Generate 5 results with fake text and fake images
        for i in range(5):
            text = faker.paragraph()
            images = [f"{random_image_url}?random={i}"]

            # Create a thumbnail card using ThumbnailCard
            thumbnail_card = self.create_thumbnail_card(title, text, images)

            # Create a preview card and add the tap action
            preview_card = self.create_thumbnail_card(title, text, images)
            tap_action = CardAction(
                type="invoke",
                value={"title": title, "text": text, "images": images},
            )
            preview_attachment = CardFactory.thumbnail_card(preview_card)
            preview_attachment.content.tap = tap_action

            # Combine the thumbnail card and the preview
            attachment = MessagingExtensionAttachment(
                content = thumbnail_card,
                content_type=CardFactory.content_types.thumbnail_card,
                preview=preview_attachment,
            )
            attachments.append(attachment)

        return MessagingExtensionResponse(
            compose_extension=MessagingExtensionResult(
                type="result",
                attachment_layout="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 demonstra como criar uma Extensão de Mensagens no Microsoft Teams que permite aos utilizadores realizar pesquisas e obter resultados.	View	View	View

Próxima etapa

Responder a comandos de pesquisa.

Confira também

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