Criar seu primeiro aplicativo de extensão de mensagem usando JavaScript
Inicie o desenvolvimento de aplicativos do Microsoft Teams com seu primeiro aplicativo teams usando JavaScript.
Neste tutorial, você aprenderá:
- Como configurar um novo projeto com o Teams Toolkit.
- Como criar um aplicativo de extensão de mensagem.
- Como implantar seu aplicativo.
Este guia passo a passo ajuda você a criar um aplicativo de extensão de mensagens do Teams com o Teams Toolkit no Visual Studio Code. Você verá a seguinte saída depois de concluir este guia:
Pré-requisitos
Verifique se você instala as seguintes ferramentas para criar e implantar seus aplicativos.
| Instalar | Para usar... | |
|---|---|---|
| Required | ||
| Visual Studio Code | Ambientes de build JavaScript ou TypeScript. Use a versão mais recente. | |
| Kit de ferramentas do Teams | A Microsoft Visual Studio Code extensão que cria um scaffolding de projeto para seu aplicativo. Use a versão mais recente. | |
| Node.js | Ambiente de runtime javaScript de back-end. Para obter mais informações, consulte Node.js tabela de compatibilidade de versão. | |
| Microsoft Teams | Colabore com pessoas com quem você trabalha por meio de aplicativos para chats, reuniões e chamadas em um só lugar. | |
| Microsoft Edge (recomendado) ou Google Chrome | Um navegador com ferramentas de desenvolvedor essenciais para depuração e teste. | |
| Conta de desenvolvedor do Microsoft 365 | Acesso à conta do Teams com permissões apropriadas para instalar um aplicativo personalizado. | |
| Opcional | ||
| Ferramentas do Azure para Visual Studio Code e CLI do Azure | Ferramentas do Azure para acessar dados armazenados ou implantar um back-end baseado em nuvem para seu aplicativo teams no Azure. | |
| React Ferramentas de Desenvolvedor para Chrome ou React Ferramentas de Desenvolvedor para Microsoft Edge | Uma extensão DevTools do navegador para a biblioteca JavaScript React de código aberto. |
Preparar o ambiente de desenvolvimento
Depois de instalar as ferramentas necessárias, configure o ambiente de desenvolvimento.
Instalar o Kit de Ferramentas do Teams
O Microsoft Teams Toolkit ajuda a simplificar o processo de desenvolvimento com ferramentas para provisionar e implantar recursos de nuvem para seu aplicativo e publicar na Teams Store.
Você pode usar o Teams Toolkit com Visual Studio Code ou uma interface de linha de comando chamada CLI do TeamsFx.
Abra Visual Studio Code e selecione Extensões (Ctrl+Shift+X ou Exibir>Extensões).
Na caixa de pesquisa, insira o Kit de Ferramentas do Teams.
Selecione Instalar.
O ícone Kit de
Ferramentas do Teams é exibido na Barra de Atividades do Visual Studio Code.
Você também pode instalar o Teams Toolkit no Visual Studio Code Marketplace.
Configurar seu locatário de desenvolvimento do Teams
Um locatário é um espaço ou um contêiner para sua organização no Teams, onde você conversa, compartilha arquivos e executa reuniões. Esse espaço também é onde você carrega e testa seu aplicativo. Vamos verificar se você está pronto para desenvolver com o locatário.
Verifique se há a opção carregar um aplicativo
Depois de criar seu aplicativo personalizado, você deve carregar seu aplicativo no Teams com a opção Carregar um aplicativo personalizado . Entre em sua conta do Microsoft 365 para marcar se essa opção estiver habilitada.
As etapas a seguir ajudam você a verificar se você pode carregar aplicativos no Teams:
No cliente do Teams, selecione o ícone Aplicativos .
Selecione Gerenciar seus aplicativos.
Selecione Carregar um aplicativo.
Procure a opção para Carregar um aplicativo personalizado. Se a opção estiver visível, você poderá carregar aplicativos personalizados.
Observação
Se você não encontrar a opção de carregar um aplicativo personalizado, entre em contato com o administrador do Teams.
Criar um locatário de desenvolvedor gratuito do Teams (opcional)
Se você não tiver uma conta de desenvolvedor do Teams, ingresse no programa de desenvolvedor do Microsoft 365.
Selecione Ingressar Agora e siga as instruções na tela.
Na tela de boas-vindas, selecione Configurar assinatura do E5.
Configurar a conta de administrador. Depois de concluir, a seguinte tela será exibida:
Entre no Teams usando a conta de administrador que você acabou de configurar. Verifique se você tem a opção Carregar um aplicativo personalizado no Teams.
Obter uma conta gratuita do Azure
Se você quiser hospedar seu aplicativo ou acessar recursos no Azure, deverá ter uma assinatura do Azure. Crie uma conta gratuita antes de começar.
Criar workspace de projeto para seu aplicativo de extensão de mensagens
Agora, vamos criar seu primeiro aplicativo de extensão de mensagem.
O recurso de extensão de mensagem permite que você interaja com um serviço Web por meio de botões e formulários. Use a área de composição de mensagem, a caixa de comando ou uma mensagem diretamente no cliente do Teams para pesquisar e iniciar ações em um sistema externo. As extensões de mensagem dependem de bots para fornecer uma caixa de diálogo entre o usuário e seu código.
Há dois tipos de extensões de mensagem do Teams:
- Comandos de pesquisa: você pode pesquisar sistemas externos e inserir os resultados em uma mensagem na forma de um cartão.
- Comandos de ação: você pode apresentar aos usuários um pop-up modal para coletar ou exibir informações. Em seguida, você pode processar a interação deles e enviar as informações de volta ao Teams.
Vamos criar um aplicativo de extensão de mensagem com um comando de pesquisa. Primeiro, configure um novo projeto do Teams para criar o aplicativo de extensão de mensagem.
Neste tutorial, você aprenderá:
- Como configurar um novo projeto de extensão de mensagem com o Teams Toolkit.
- Sobre a estrutura de diretório do seu projeto de aplicativo.
Criar seu workspace de projeto de extensão de mensagem
Se os pré-requisitos estiverem em vigor, vamos começar!
Observação
A interface do usuário Visual Studio Code mostrada pode ser diferente para você, dependendo do sistema operacional, da versão do Kit de Ferramentas, do tema e do ambiente.
Abra o Visual Studio Code.
Selecione o ícone kit de
ferramentas do Teams na barra de atividades Visual Studio Code.Selecione Criar um Novo Aplicativo.
Selecione Extensão de Mensagem.
Selecione Resultados da Pesquisa Personalizada.
Selecione Iniciar com um Bot.
Selecione JavaScript.
Selecione Pasta padrão para armazenar sua pasta raiz do projeto no local padrão.
Você também pode alterar o local padrão pelas seguintes etapas:
Selecione Procurar.
Selecione o local para o workspace do projeto.
Selecione Selecionar Pasta.
Insira um nome adequado para seu aplicativo. Selecione Enter.
O Teams Toolkit cria o aplicativo em alguns segundos.
Depois que seu aplicativo é criado, o Teams Toolkit exibe a seguinte mensagem:
Faça um tour pelo código-fonte do aplicativo de extensão de mensagem
Uma extensão de mensagem usa o Bot Framework para interagir com seu serviço por meio de uma conversa. Após o scaffolding, exiba os diretórios e arquivos do projeto em EXPLORER.
| Pasta/Arquivo | Conteúdos |
|---|---|
teamsapp.yml |
O arquivo principal do projeto descreve a configuração do aplicativo e define o conjunto de ações a serem executadas em cada estágio do ciclo de vida. |
teamsapp.local.yml |
Substitui com teamsapp.yml ações que habilitam a execução local e a depuração. |
.vscode/ |
Visual Studio Code arquivos para depuração local. |
appPackage/ |
Modelos para o manifesto do aplicativo teams. |
infra/ |
Modelos para provisionar recursos do Azure. |
index.js |
Ponto de entrada do aplicativo e restify manipulador. |
Dica
Familiarize-se com bots e extensão de mensagem fora do Teams antes de integrar seu aplicativo ao Teams.
Criar e executar seu primeiro aplicativo de extensão de mensagem
Depois de configurar o workspace do projeto com o Teams Toolkit, é hora de criar seu projeto. Você precisa entrar na sua conta do Microsoft 365.
Entre em sua conta do Microsoft 365
Entre com a conta de administrador que você criou ao ingressar no programa de desenvolvedores do Microsoft 365.
Abra o Visual Studio Code.
Selecione o ícone Kit de
Ferramentas do Teams na barra de atividades.Selecione Entrar no Microsoft 365 usando suas credenciais. Seu navegador da Web padrão é aberto para permitir que você entre.
Feche o navegador depois de entrar usando suas credenciais.
Retorne ao Teams Toolkit no Visual Studio Code.
A seção ACCOUNTS da barra lateral mostra o nome da conta do Microsoft 365. Se o upload de aplicativo personalizado estiver habilitado para sua conta do Microsoft 365, o Teams Toolkit exibirá Sideloading habilitado.
Agora você está pronto para criar o aplicativo e executá-lo localmente!
Compilar e executar seu aplicativo no ambiente local
Agora você pode criar e depurar seu primeiro aplicativo de extensão de mensagens do Teams localmente.
Compilar e executar seu aplicativo localmente
Selecione a chave F5 no Visual Studio Code para executar seu aplicativo no modo de depuração.
Observação
Se o Teams Toolkit não conseguir verificar um pré-requisito específico, ele solicitará que você marcar.
Saiba o que acontece quando você executa seu aplicativo localmente no depurador.
Quando você seleciona F5, o Kit de Ferramentas do Teams executa as seguintes funções:
Verifica os seguintes pré-requisitos:
- Você está conectado com uma conta do Microsoft 365.
- O upload de aplicativo personalizado está habilitado para sua conta do Microsoft 365.
- A versão de Node.js com suporte está instalada.
- A porta necessária pelo aplicativo bot está disponível.
Instala pacotes npm
Inicia o Túnel de Desenvolvimento para criar um túnel HTTP.
Registra o aplicativo em Microsoft Entra ID e configura o aplicativo.
Registra o aplicativo bot no Bot Framework e configura o aplicativo.
Registra o aplicativo no Portal do Desenvolvedor do Teams e configura o aplicativo.
Inicia o aplicativo de extensão de mensagem hospedado localmente.
Inicia o Teams em um navegador da Web e carrega o aplicativo Teams.
Quando você depura o aplicativo pela primeira vez, o Teams baixa as dependências e cria o aplicativo. Esse processo pode levar de 3 a 5 minutos para ser concluído.
O Teams é aberto em uma janela do navegador quando o build é concluído. Entre com sua conta do Microsoft 365, se solicitado.
Uma caixa de diálogo é aberta para permitir que você adicione o aplicativo de extensão de mensagens ao Teams. Selecione Adicionar.
O Teams carrega o aplicativo de extensão de mensagem.
Como os aplicativos de extensão de mensagem dependem de bots para habilitar a comunicação entre o usuário e o serviço Web, seu aplicativo carrega em um recurso de chat de um bot.
- Se você criou um aplicativo bot antes de criar o aplicativo de extensão de mensagem, o Teams carregará a extensão de mensagem no aplicativo bot criado. As mensagens de chat anteriores do aplicativo bot estão visíveis.
- Se você criou uma extensão de mensagem primeiro, o Teams carregará seu aplicativo no chat mais recente que está aberto no Teams.
Testar seu aplicativo
Na primeira vez que seu aplicativo é carregado, o aplicativo de extensão de mensagem está aberto para você testar. Este aplicativo de exemplo permite pesquisar pacotes npm de código aberto no registro de software.
Como executar uma consulta de pesquisa
Insira o nome de um pacote npm de código aberto na caixa de pesquisa da extensão da mensagem, como a cli. A extensão de mensagem exibe uma lista dos itens correspondentes.
Selecione um dos itens da lista. O aplicativo cria um Cartão Adaptável com o item na área de composição de mensagem para que você possa enviá-lo em um chat ou canal.
Selecione Enter. O aplicativo de extensão de mensagem envia o Cartão Adaptável com o item no chat ou canal.
Como abrir seu aplicativo de extensão de mensagem
Você testou o recurso de pesquisa do aplicativo de extensão de mensagem na etapa anterior. Agora, aprenda as diferentes maneiras de abrir o aplicativo de extensão de mensagem.
Abra seu aplicativo na caixa de comandos
Insira / seguido pelo nome do aplicativo de extensão de mensagem na caixa de comando.
O aplicativo é aberto na caixa de comando e você pode usá-lo para executar uma consulta.
Observação
- Usar / para abrir o aplicativo de extensão de mensagem da caixa de comando só funciona no novo cliente do Teams.
- Use @ para abrir seu aplicativo de extensão de mensagem da caixa de comando no cliente clássico do Teams.
Abra seu aplicativo na área de composição de mensagens
Selecione os três pontos na parte inferior da área de composição da mensagem.
Selecione seu aplicativo de extensão de mensagem.
O aplicativo de extensão de mensagem é carregado com as opções para executar uma pesquisa.
Abra seu aplicativo de aplicativos personalizados carregados
Selecione Aplicativos>Gerenciar seus aplicativos.
Selecione a lista suspensa para seu aplicativo na lista de aplicativos e selecione Aplicativo pessoal.
Uma caixa de diálogo aparece sugerindo que você experimente seu aplicativo. Se você selecionar Got it, a caixa de diálogo desaparecerá. Selecione Experimentar.
Uma lista de aplicativos de extensão de mensagem aparece no chat mais recente do Teams. Selecione seu aplicativo de extensão de mensagem na lista.
Saiba como solucionar problemas se seu aplicativo não for executado localmente
Para executar seu aplicativo no Teams, você deve ter uma conta de desenvolvimento do Microsoft 365 que permite o upload de aplicativo personalizado. Você pode saber mais sobre o upload de aplicativo personalizado na seção Pré-requisitos.
Implantar seu primeiro aplicativo do Teams
Vamos implantar seu primeiro aplicativo de extensão de mensagens no Azure usando o Teams Toolkit.
Entre em sua conta do Azure
Entre em sua conta do Azure para acessar o Microsoft portal do Azure e provisionar novos recursos de nuvem para dar suporte ao seu aplicativo.
Abra o Visual Studio Code.
Abra a pasta de projeto na qual você criou o aplicativo de extensão de mensagem.
Selecione o ícone Kit de
Ferramentas do Teams na barra de atividades.Selecione Entrar no Azure usando suas credenciais. Seu navegador da Web padrão é aberto para permitir que você entre.
Dica
Se você tiver a extensão da CONTA do AZURE instalada e estiver usando a mesma conta, poderá ignorar esta etapa.
Feche o navegador quando solicitado e retorne ao Visual Studio Code.
A seção ACCOUNTS da barra lateral lista o número de assinaturas utilizáveis do Azure disponíveis para você. Verifique se você tem pelo menos uma assinatura utilizável do Azure disponível. Caso contrário, saia e use uma conta diferente.
Implantar seu aplicativo no Azure.
A implantação consiste em duas etapas. Primeiro, os recursos de nuvem necessários são criados (também conhecidos como provisionamento). Em seguida, o código do aplicativo é copiado para os recursos de nuvem criados. Você implanta o aplicativo de extensão de mensagem neste tutorial.
Qual é a diferença entre Provisionar e Implantar?
A etapa Provisionar cria recursos no Azure e no Microsoft 365 para seu aplicativo, mas nenhum código (como HTML, CSS ou JavaScript) é copiado para os recursos. A etapa Implantar copia o código do aplicativo para os recursos criados durante a etapa de provisionamento. É comum implantar várias vezes sem provisionar novos recursos. Como a etapa de provisionamento leva algum tempo para ser concluída, ela é separada da etapa de implantação.
Selecione o ícone kit de ferramentas do Teams na barra de atividades Visual Studio Code.
Selecione Provisionar.
Selecione uma assinatura.
Selecione um grupo de recursos.
Se você não tiver um grupo de recursos para selecionar, poderá criar um novo grupo de recursos com as seguintes etapas:
Selecione + Novo grupo de recursos.
Selecione o nome padrão ou insira um nome adequado para o grupo de recursos.
Selecione o local do grupo de recursos.
Uma caixa de diálogo avisa que os custos podem ser incorridos ao executar recursos no Azure. Selecione Provisionar.
O processo de provisionamento cria recursos na nuvem do Azure. Pode levar algum tempo. Após alguns minutos, você verá a seguinte mensagem:
Se desejar, você pode exibir os recursos provisionados. Para este tutorial, você não precisa exibir recursos.
O recurso provisionado aparece em ENVIRONMENT.
Em CICLO DE VIDA, selecione Implantar.
Uma caixa de diálogo é exibida que pergunta se você deseja implantar recursos no ambiente de desenvolvimento. Selecione Implantar.
Assim como acontece com o provisionamento, a implantação leva algum tempo. Depois de alguns minutos, você verá uma mensagem de conclusão.
Executar o aplicativo implantado
Depois que as etapas de provisionamento e implantação forem concluídas, acesse Executar e Depurar (Ctrl+Shift+D ou Exibir > Execução) no Teams Toolkit.
Selecione o menu suspenso EXECUTAR E DEPURAR .
Selecione Iniciar Remoto no Teams (Edge).
Selecione o botão ▷ .
Uma caixa de diálogo é aberta para instalar seu aplicativo implantado no Teams. Selecione Adicionar.
O Teams abre o aplicativo de extensão de mensagens no chat mais recente.
Saiba o que acontece quando você implanta o seu aplicativo no Azure
Antes da implantação, o aplicativo é executado localmente.
- O back-end é executado usando o Azure Functions Core Tools.
- O ponto de extremidade HTTP do aplicativo, onde o Microsoft Teams carrega o aplicativo, é executado localmente.
A implantação é um processo de duas etapas. Você provisiona os recursos em uma assinatura ativa do Azure e, em seguida, implanta ou carrega o código de back-end e front-end do aplicativo no Azure.
- O back-end, se configurado, usa vários serviços do Azure, incluindo Serviço de Aplicativo do Azure e Armazenamento do Azure.
- O aplicativo front-end é implantado em uma conta de Armazenamento do Azure configurada para hospedagem da Web estática.
Parabéns!
Você concluiu o tutorial para criar um aplicativo de extensão de mensagens com JavaScript!
Você veio com algo assim?
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.