Criar seu primeiro aplicativo de extensão de mensagem usando JavaScript
Inicie o desenvolvimento de aplicativos do Microsoft Teams com seu primeiro aplicativo do Teams. Você pode criar uma extensão de mensagem aplicativo teams.
Seu aplicativo terá uma funcionalidade, que vem com sua própria interface do usuário e UX:
Neste tutorial, você pode aprender:
- Como configurar um novo projeto com o Teams Toolkit.
- Como criar um aplicativo de extensão de mensagem.
- Como implantar seu aplicativo.
Pré-requisitos
Aqui está uma lista de ferramentas necessárias para criar e implantar seus aplicativos.
| Instalar | Para usar... | |
|---|---|---|
| Required | ||
| Visual Studio Code | JavaScript ou TypeScript, ambientes de build. Use a versão mais recente. | |
| Kit de ferramentas do Teams | Uma extensão do Microsoft Visual Studio Code que cria um scaffolding de projeto para seu aplicativo. Use a versão 4.0.0. | |
| Node.js | Ambiente de runtime do JavaScript de back-end. Para obter mais informações, consulte Node.js tabela de compatibilidade de versão para o tipo de projeto. | |
| Microsoft Teams | Microsoft Teams para colaborar com todos com quem você trabalha por meio de aplicativos para chat, reuniões, chamadas e tudo em um só lugar. | |
| Microsoft Edge (recomendado) ou Google Chrome | Um navegador com ferramentas de desenvolvedor. | |
| Conta de desenvolvedor do Microsoft 365 | Acesso à conta do Teams com as permissões apropriadas para instalar um aplicativo. | |
| 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 Ferramentas de Desenvolvedor do Chrome OR React para Microsoft Edge | Uma extensão DevTools do navegador para a biblioteca JavaScript React de código aberto. | |
| Microsoft Graph Explorer | O Microsoft Graph Explorer, uma ferramenta baseada em navegador que permite executar uma consulta de dados do Microsoft Graph. | |
| Portal do Desenvolvedor do Teams | Portal baseado na Web para configurar, gerenciar e distribuir seu aplicativo do Teams, inclusive para sua organização ou para a loja do Teams. |
Dica
Se você trabalhar com dados do Microsoft Graph, saiba mais sobre e marque a Explorer do Microsoft Graph. Essa ferramenta baseada no navegador permite consultar o Microsoft Graph fora de um aplicativo.
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 Kit de Ferramentas do Teams ajuda a simplificar o processo de desenvolvimento com ferramentas para provisionar e implantar recursos de nuvem para seu aplicativo, publicar na loja do Teams e muito mais.
Você pode usar o kit de ferramentas com Visual Studio Code ou CLI (interface de linha de comando), chamada TeamsFx.
- Abra Visual Studio Code e selecione a exibição Extensões (Ctrl+Shift+X / ⌘⇧-X ou Exibir > Extensões).
- Na caixa de pesquisa, insira kit de ferramentas do Teams.
- Selecione Instalar ao lado do Kit de Ferramentas do Teams.
O ícone Kit de Ferramentas do Teams é exibido na Barra de Atividades Visual Studio Code depois de instalado.
Você também pode encontrar o Kit de Ferramentas do Teams no Visual Studio Code Marketplace.
Observação
A versão mais recente do Teams Toolkit é 4.2.0.
Configurar seu locatário de desenvolvimento do Teams
Um locatário é como 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 seu sideload e testa seu aplicativo. Vamos verificar se você está pronto para desenvolver com o locatário.
Verificar a opção sideload
Depois de criar o aplicativo, você deve carregar seu aplicativo no Teams sem distribuí-lo. Esse processo é conhecido como sideload. Entre em sua conta do Microsoft 365 para exibir essa opção.
Observação
O sideload é necessário para visualizar e testar aplicativos no ambiente local do Teams. Se ele não estiver habilitado, você não poderá visualizar e testar seu aplicativo no Teams localmente.
Você já tem um locatário e tem acesso ao administrador? Vamos marcar se você realmente fizer isso!
Verifique se você pode carregar aplicativos de sideload no Teams:
No cliente do Teams, selecione o ícone Store .
Selecione Gerenciar seus aplicativos.
Selecione Publicar um aplicativo.
Procure a opção para Carregar um aplicativo personalizado. Se você vir a opção, os aplicativos de sideload estarão habilitados.
Observação
Se você não tiver a opção de carregar um aplicativo personalizado, converse 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, poderá obtê-la gratuitamente. 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 tela a seguir 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ê deseja hospedar seu aplicativo ou acessar recursos no Azure, deverá ter uma assinatura do Azure. Crie uma conta gratuita antes de começar.
Agora você tem todas as ferramentas e configurou sua conta. Em seguida, vamos configurar seu ambiente de desenvolvimento e começar a criar! Selecione o aplicativo que você deseja fazer primeiro.
Criar workspace de projeto para seu aplicativo de extensão de mensagens
Você criou seu aplicativo bot. Agora, vamos criar seu primeiro aplicativo de extensão de mensagem.
O recurso Extensão de Mensagem permite que você interaja com um serviço Web. Use a área de composição, a caixa de comando ou uma mensagem no cliente do Teams para pesquisar e iniciar ações em um sistema externo.
Há dois tipos de extensões de mensagem do Teams:
- Comandos de pesquisa: você pode pesquisar sistemas externos. Em seguida, você pode inserir seus 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 informações de volta ao Teams.
Vamos criar um aplicativo de extensão de mensagem com um comando de pesquisa. Use-os para pesquisar dados externos e inserir os resultados em uma mensagem no cliente do Teams.
Como você já se preparou para criar esses aplicativos, você pode configurar um novo projeto do Teams para criar o aplicativo de extensão de mensagem.
Observação
As extensões de mensagem dependem de bots para fornecer uma caixa de diálogo entre o usuário e seu código.
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 é do Mac. Pode ser diferente dependendo do sistema operacional, da versão do Kit de Ferramentas 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 Criar um novo aplicativo do Teams para criar um aplicativo usando o Kit de Ferramentas do Teams.
Verifique se a extensão mensagem está selecionada como a funcionalidade que você deseja criar em seu aplicativo..
Selecione JavaScript como linguagem de programação.
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 a Pasta Selecionar.
Insira um nome adequado para seu aplicativo. Selecione Enter.
O Teams Toolkit cria o aplicativo em alguns segundos.
Depois que seu aplicativo é criado, o Kit de Ferramentas do Teams exibe a seguinte mensagem:
Você pode selecionar Depuração local para visualizar seu projeto.
Uma recapitulação rápida da criação de um aplicativo do Teams.
Assista a esta breve recapitulação para criar um aplicativo do Teams.
Faça um tour pelo código-fonte do aplicativo de extensão de mensagem
Uma extensão de mensagem usa o Bot Framework. Você o usa para interagir com seu serviço por meio de uma conversa. Depois que o scaffolding for concluído, exiba os diretórios e arquivos do projeto na área Explorer de Visual Studio Code.
| Nome da pasta | Conteúdos |
|---|---|
.fx/configs |
Arquivos de configuração que o usuário pode personalizar para o aplicativo teams. |
.fx/configs/config.<envName>.json |
Arquivo de configuração para cada ambiente. |
.fx/configs/azure.parameters.<envName>.json |
Arquivo de parâmetros para provisionamento do Azure BICEP para cada ambiente. |
.fx/configs/projectSettings.json |
Configurações de projeto globais que se aplicam a todos os ambientes. |
.fx/configs/ngrok.yml |
Configurações do Ngrok |
.fx/states |
Saída de provisionamento gerada pelo Kit de Ferramentas. O kit de ferramentas cria essa pasta depois que você provisiona recursos para seu aplicativo. |
.fx/states/state.<envName>.json |
Provisionar arquivo de saída para cada ambiente. |
.fx/states/<env>.userdata |
Dados confidenciais do usuário para a saída de provisionamento para cada ambiente. |
bot |
Código para o Bot necessário no runtime. |
bot/messageExtensionBot.js |
Ponto de entrada principal para o aplicativo de extensão de mensagem. |
templates/appPackage |
Arquivos de modelo de manifesto de aplicativo e os ícones do aplicativo, color.png e outline.png. |
templates/appPackage/manifest.template.json |
Manifesto do aplicativo para executar o aplicativo em ambiente local e remoto. |
templates/azure |
Arquivos de modelo BICEP |
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, crie seu projeto. Você precisa entrar na sua conta do Microsoft 365.
Entre em sua conta do Microsoft 365
Use essa conta para entrar no Teams. Se você estiver usando um locatário do programa de desenvolvedor do Microsoft 365, a conta de administrador que você configurou durante o registro é sua conta do Microsoft 365.
Abra o Visual Studio Code.
Selecione o ícone kit de
ferramentas do Teams na barra lateral.Selecione Entrar no M365.
Seu navegador da Web padrão é aberto para permitir que você entre na conta.
Entre em sua conta do Microsoft 365.
Feche o navegador quando solicitado e retorne ao Visual Studio Code.
Retorne ao Teams Toolkit no Visual Studio Code.
A seção ACCOUNTS da barra lateral mostra o nome da conta do Microsoft 365. O Kit de Ferramentas do Teams exibe Sideloading habilitado se o sideload estiver habilitado para sua conta do Microsoft 365.
Agora você está pronto para criar o aplicativo e executá-lo localmente!
Compilar e executar seu aplicativo no ambiente local
Uma extensão de mensagem permite que você interaja com um serviço Web. Ele aproveita o recurso de mensagens e a comunicação segura de um bot. O aplicativo de extensão de mensagem é adicionado a um serviço Web registrado como um bot.
Compilar e executar seu aplicativo localmente
Selecione F5 no Visual Studio Code para executar seu aplicativo no modo de depuração.
Observação
Se o Teams Toolkit não conseguir marcar um pré-requisito específico, ele solicitará que você marcar-lo.
Saiba o que acontece quando você executa seu aplicativo localmente no depurador.
Ao selecionar F5, o Kit de Ferramentas do Teams:
- Verifica todos os seguintes pré-requisitos:
- Você está conectado com uma conta do Microsoft 365.
- O sideload está habilitado para sua conta do Microsoft 365.
- A versão de Node.js com suporte está instalada.
- O Ngrok está instalado.
- A porta necessária pelo aplicativo bot está disponível.
- Instalar pacotes npm
- Inicia o Ngrok para criar um túnel HTTP.
- Registra o aplicativo no Azure AD 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.
Observação
Quando você executa o aplicativo pela primeira vez, todas as dependências são baixadas e o aplicativo é criado. Uma janela do navegador é aberta quando o build é concluído. Esse processo pode levar de três a cinco minutos para ser concluído.
O Teams executa seu aplicativo em um navegador da Web.
Entre com sua conta do Microsoft 365, se solicitado.
Selecione Adicionar para adicionar o aplicativo à sua conta.
O kit de ferramentas exibe uma mensagem para indicar que o aplicativo foi adicionado ao Teams.
- Se você selecionar Obtê-lo, você pode experimentar o aplicativo mais tarde na lista de aplicativos sideload.
- Se você selecionar Experimentar, o Teams carregará seu aplicativo.
Selecione Experimentar.
O aplicativo Extensão de Mensagem é carregado em um aplicativo de bot de chat.
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, poderá ver que ele é carregado no mesmo aplicativo bot que você criou. As mensagens de chat anteriores estão visíveis.
- Se você criou uma extensão de mensagem primeiro, seu aplicativo será carregado em qualquer chat 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.
Para executar uma consulta de pesquisa
Vamos inserir uma cadeia de caracteres de pesquisa na caixa de pesquisa, como "cli". Você receberá uma lista dos itens correspondentes:
Selecione um nos resultados da pesquisa. Ele será exibido na área de composição para que você possa enviar o resultado para o canal.
Selecione as instruções Enviar .
Agora, você aprendeu a criar e executar um aplicativo de extensão de mensagem básico!
Cenários opcionais
Você testou o recurso de pesquisa de um aplicativo de extensão de mensagem básico. Agora, você pode experimentar algumas outras funcionalidades deste aplicativo. Estes são cenários opcionais neste aplicativo.
Para criar um cartão
Selecione Criar Cartão.
Insira os detalhes cartão conforme mostrado e selecione Enviar.
Seus detalhes cartão aparecem na área de composição.
Selecione o ícone Enviar na área de composição.
O aplicativo envia o cartão no chat do bot.
Para abrir seu aplicativo na área de composição
Escolha uma das seguintes maneiras de abrir seu aplicativo.
- Usando
@mention:
Insira
@your-app-namena área de comando do seu aplicativo.O aplicativo abre a caixa de pesquisa e você pode usá-la para executar uma consulta.
Insira uma cadeia de caracteres de pesquisa e selecione uma no resultado da pesquisa.
Ele é exibido na área de comando como um cartão.
Copie o cartão para colá-lo na área de composição.
Envie o cartão usando a área de composição.
- Usando o ícone de três pontos:
Inicie a extensão de mensagem de três pontos na parte inferior da área de composição.
Selecione seu aplicativo de extensão de mensagem.
O aplicativo de extensão de mensagem carrega as opções para executar uma pesquisa e criar cartões adaptáveis.
Executar o aplicativo de aplicativos sideload
Você pode abrir um aplicativo sideload do Teams na lista de aplicativos sideload.
Selecione o ícone Store na barra lateral do Teams.
Selecione a Gerenciar aplicativos.
Selecione o ícone de três pontos para seu aplicativo e selecione Exibir detalhes. Você também pode copiar o link para o aplicativo e usá-lo para abrir o aplicativo.
Selecione Abrir para carregar o aplicativo e selecione Experimentar.
O aplicativo é carregado no Teams.
Saiba como solucionar problemas se o 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 sideload do aplicativo. Você pode saber mais sobre sideload na seção Pré-requisitos.
Implantar seu primeiro aplicativo do Teams
Você aprendeu a criar, compilar e executar o aplicativo teams com recursos de Extensão de Mensagem. A etapa final é implantar seu aplicativo no Azure.
Vamos implantar o primeiro aplicativo com o recurso Tab no Azure usando o Teams Toolkit.
Entre em sua conta do Azure
Use essa conta 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 guias.
Selecione o ícone kit de
ferramentas do Teams na barra lateral.Selecione Entrar no Azure.
Dica
Se você tiver a extensão da Conta do Azure instalada e estiver usando a mesma conta, poderá ignorar esta etapa. Use a mesma conta que você está usando em outras extensões.
Seu navegador da Web padrão é aberto para permitir que você entre na conta.
Entre em sua conta do Azure usando suas credenciais.
Feche o navegador quando solicitado e retorne ao Visual Studio Code.
A seção ACCOUNTS da barra lateral mostra as duas contas separadamente. Ele também 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.
Agora você está pronto para implantar seu aplicativo no Azure!
Parabéns, você criou um aplicativo do Teams! Agora vamos continuar e aprender a implantar um dos aplicativos no Azure usando o Kit de Ferramentas do Teams.
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. Para este tutorial, você implantará o aplicativo de extensão de mensagem.
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 (HTML, CSS, JavaScript etc.) é 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 pode levar algum tempo para ser concluída, ela é separada da etapa de implantação.
Selecione o ícone do Kit de Ferramentas do Teams
na barra Visual Studio Code lateral.
Selecione Provisionar.
Selecione uma assinatura a ser usada para os recursos do Azure.
Seu aplicativo está hospedado usando recursos do Azure.
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. Você pode monitorar o progresso observando as caixas de diálogo no canto inferior direito. Após alguns minutos, você verá o seguinte aviso:
Se desejar, você pode exibir os recursos provisionados. Para este tutorial, você não precisa exibir recursos.
O recurso provisionado é exibido na seção ENVIRONMENT .
Selecione Implantar no painel LIFECYCLE após a conclusão do provisionamento.
Assim como acontece com o provisionamento, a implantação leva algum tempo. Você pode monitorar o processo observando as caixas de diálogo no canto inferior direito. Após alguns minutos, você verá um aviso de conclusão.
Agora, você pode usar o mesmo processo para implantar seus aplicativos Bot e Extensão de Mensagem no Azure.
Executar o aplicativo implantado
Depois que as etapas de provisionamento e implantação forem concluídas:
Abra o painel de depuração (Ctrl+Shift+D / ⌘⇧-D ou Exibir > Execução) de Visual Studio Code.
Selecione Iniciar Remoto (Edge) na lista suspensa de configuração de inicialização.
Selecione o F5 (Iniciar depuração) para iniciar seu aplicativo no Azure.
Selecione Adicionar.
O kit de ferramentas exibe uma mensagem para indicar que o aplicativo foi adicionado ao Teams.
- Se você selecionar Obtê-lo, você pode experimentar o aplicativo mais tarde na lista de aplicativos sideload.
- Se você selecionar Experimentar, o Teams carregará seu aplicativo.
Seu aplicativo é carregado no site do Azure.
Selecione Experimentar.
O aplicativo Extensão de Mensagem é carregado em um aplicativo de bot de chat.
Saiba o que acontece quando você implantou seu aplicativo no Azure
Antes da implantação, o aplicativo era 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 back-end e o código de 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 front-end do aplicativo será implantado em uma conta de Armazenamento do Microsoft Azure configurada para hospedagem Web estática.
Parabéns!
Você fez isso!
Você criou um aplicativo de extensão de mensagens.
Agora que você aprendeu a criar um aplicativo básico, você pode passar a criar aplicativos mais complexos. Para começar, tente adicionar recursos aos seus aplicativos existentes.
Para adicionar recursos ao aplicativo existente:
Selecione Adicionar recurso na seção Desenvolvimento da barra lateral do Teams Toolkit.
Selecione o recurso que você deseja adicionar ao seu aplicativo.
Isso é tudo. O Teams Toolkit adiciona o scaffolding para o novo recurso à estrutura de diretório do seu aplicativo. Siga os procedimentos para criar e implantar o aplicativo, e seu aplicativo terá vários recursos.
Você concluiu o tutorial para criar um aplicativo de extensão de mensagens com JavaScript.
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.
Comentários
Enviar e exibir comentários de