Criar seu primeiro aplicativo usando o Node.js
Inicie o desenvolvimento de aplicativos do Microsoft Teams criando seu primeiro aplicativo com uma guia, um bot e uma funcionalidade de extensão de mensagem.
Este aplicativo terá todos os recursos e cada um tem sua própria interface do usuário e UX:
Neste tutorial, você aprenderá:
- Como configurar um novo projeto usando ferramentas de linha de comando.
- Como criar três aplicativos com uma funcionalidade diferente cada uma: guia, bot e extensão de mensagem.
- Como implantar seu aplicativo no Portal do Desenvolvedor.
Pré-requisitos
Aqui está uma lista de ferramentas que você precisará instalar para criar e implantar um aplicativo do Teams.
Instalar | Para usar... | |
---|---|---|
Required | ||
Node.js e NPM | 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. | |
ngrok | Os recursos do aplicativo Teams (bots de conversa, extensões de mensagem e webhooks de entrada) exigem conexões de entrada. Um túnel conecta seu sistema de desenvolvimento ao Teams. Não é necessário para aplicativos que incluem apenas guias. Esse pacote é instalado no diretório do projeto (usando npm devDependencies ). |
|
Microsoft Edge (recomendado) ou Google Chrome | Um navegador com ferramentas de desenvolvedor. | |
Visual Studio Code | Ambientes de compilação JavaScript, TypeScript ou Estrutura do SharePoint (SPFx). Use a versão 1.55 ou posterior. | |
Git | Git para usar o repositório De exemplo Node.js aplicativo do GitHub. | |
Gole | Kit de ferramentas JavaScript de código aberto. Instale a versão 4.0.0 ou posterior. | |
Microsoft Teams | Microsoft Teams para colaborar com todos com quem você trabalha por meio de aplicativos para chat, reuniões e chamar tudo em um só lugar. | |
Opcional | ||
Ferramentas do Azure para Visual Studio Code e CLI do Microsoft 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 | Ferramentas de navegador para desenvolvimento de guias com JavaScript. | |
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 Microsoft Teams Store. | |
extensões de Visual Studio Code | ||
Ferramentas do Azure Functions Core versão 3. | Componentes de back-end localmente durante uma execução de depuração local, incluindo os auxiliares de autenticação necessários ao executar seus serviços no Azure. Ele está instalado no diretório do projeto (usando o npm devDependencies ). |
|
SDK DO .NET | Associações personalizadas para implantações de aplicativo de depuração local e Azure Functions. Se você ainda não instalou o SDK do .NET 3.1 (ou posterior) globalmente, a versão portátil poderá ser instalada. |
Verificar números de versão para ferramentas instaladas
Use os comandos a seguir para verificar se as versões instaladas para as ferramentas são necessárias.
Observação
Use a janela do terminal com a qual você está mais confortável em sua plataforma. Esses exemplos usam o Git Bash (que está incluído na instalação do Git), mas esses scripts serão executados na maioria das plataformas.
Para verificar os números de versão das ferramentas instaladas:
Abra uma janela de terminal.
Execute o seguinte comando para verificar a
git
versão instalada em seu computador:$ git --version
Exemplo de saída:
git version 2.19.0.windows.1
Execute o seguinte comando para verificar a
node.js
versão:$ node -v
Exemplo de saída:
v8.9.3
Verifique o número da versão de
npm
:$ npm -v
Exemplo de saída:
5.5.1
Verifique o número da versão de
gulp
:$ gulp -v
Exemplo de saída:
CLI version 2.3.0
Local version 4.0.2
Execute o seguinte comando para verificar o número de versão do Visual Studio Code:
code --version
Exemplo de saída:
1.28.2
929bacba01ef658b873545e26034d1a8067445e9
Você pode usar uma versão diferente desses aplicativos sem nenhum problema.
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 você carrega e testa seu aplicativo personalizado.
Vamos verificar se você está pronto para desenvolver com o locatário.
Habilitar a opção de carregamento de aplicativo personalizado
Depois de criar o aplicativo, você deve carregar seu aplicativo no Teams sem distribuí-lo. Esse processo é conhecido como upload de aplicativo personalizado. Entre em sua conta do Microsoft 365 para exibir essa opção.
Observação
O upload personalizado do aplicativo é 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 um aplicativo personalizado no Teams:
No cliente do Teams, selecione Ícone de Armazenamento .
Selecione Gerenciar seus aplicativos.
Procure a opção para Carregar um aplicativo personalizado. Se você vir a opção, o upload de aplicativo personalizado estará habilitado.
Observação
Se o Teams não mostrar a opção de carregar um aplicativo personalizado, converse com o administrador do Teams.
Create um locatário gratuito do desenvolvedor do Teams
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. Create uma conta gratuita antes de começar.
Agora você tem todas as ferramentas e configurou suas contas. Em seguida, vamos configurar seu ambiente de desenvolvimento e começar a criar!
Você pode continuar a usar essa janela do terminal para executar os comandos que seguem neste tutorial.
Baixar o exemplo
Para este tutorial, use o exemplo Hello, Mundo! para começar. Você pode baixá-lo e cloná-lo do GitHub.
Para usar o Git Bash para clonar o repositório de exemplo:
Abra uma janela de terminal.
Execute o seguinte comando para clonar o repositório de exemplo no computador:
git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git
Dica
Você pode bifurcar esse repositório se quiser modificar e marcar em suas alterações no repositório do GitHub para referência futura.
Criar seu primeiro aplicativo Node.js
Depois de clonar o repositório para Node.js aplicativo de exemplo, você pode compilar e testar o aplicativo em seu ambiente local.
Nesta página, você aprenderá a:
Criar e executar o exemplo
Depois que o repositório for clonado, você poderá criar o aplicativo de exemplo.
Abra uma janela de terminal.
Execute o comando do diretório de alterações no terminal para alterar para o diretório de aplicativo de exemplo:
cd Microsoft-Teams-Samples/samples/app-hello-world/nodejs/
Instale todas as dependências usando o seguinte comando:
npm install
Você deve ver um monte de dependências sendo instaladas.
Execute o aplicativo usando o seguinte comando após a conclusão da instalação:
npm start
Quando o aplicativo Olá, Mundo é iniciado, ele é exibido
App started listening on port 3333
na janela do terminal.Observação
Se você vir um número de porta diferente exibido na mensagem acima, é porque você tem um conjunto de variáveis de ambiente PORT. Você pode continuar a usar essa porta ou alterar sua variável de ambiente para 3333.
Abra uma janela do navegador e use as seguintes URLs para verificar se todas as URLs do aplicativo Olá, Mundo estão sendo carregadas:
http://localhost:3333
http://localhost:3333/hello
http://localhost:3333/first
http://localhost:3333/second
Testar seu aplicativo de exemplo no ambiente local
Lembre-se de que os aplicativos no Microsoft Teams são aplicativos Web expondo um ou mais recursos. Disponibilize seu aplicativo na Internet para que a plataforma do Teams possa carregá-lo. Para tornar seu aplicativo acessível pela Internet, você precisa hospedar seu aplicativo.
Para testes locais, você pode executar o aplicativo em seu computador local e criar um túnel para ele com um ponto de extremidade da Web. O ngrok é uma ferramenta gratuita que permite que você faça exatamente isso. Com o ngrok, você pode obter um endereço Web como https://d0ac14a5.ngrok.io
(essa URL é apenas um exemplo). Você pode baixar e instalaro ngrok para seu ambiente. Certifique-se de adicioná-lo a um local no PATH
.
túnel ngrok Create
Depois de instalar o ngrok, você pode criar um túnel para implantar seu aplicativo localmente.
Abra uma nova janela do terminal.
Execute o comando a seguir para criar um túnel. O aplicativo de exemplo usa a porta 3333:
ngrok http 3333 --host-header=localhost:3333
Um túnel ngrok é criado. Aqui está um exemplo de túnel ngrok.
O Ngrok escuta as solicitações da Internet e as encaminhará para seu aplicativo em execução na porta 3333.
Para verificar a implantação local do aplicativo:
Abra o navegador.
Carregue seu aplicativo usando a seguinte URL:
https://<forwarding address in ngrok console session>/
Aqui está um exemplo da URL:
Você pode tentar adicionar
hello
,first
ousecond
à url do túnel ngrok para exibir páginas de guias diferentes do aplicativo.O Ngrok escuta as solicitações da Internet e as encaminha para seu aplicativo em execução na porta 3333.
Anote o endereço de encaminhamento no console do ngrok. Você precisa dessa URL para implantar seu aplicativo no Teams.
Observação
Se você usou uma porta diferente durante a compilação e a execução, use o mesmo número de porta para configurar o túnel ngrok .
Dica
É uma boa ideia executar o ngrok em uma janela de terminal diferente para mantê-lo em execução sem interferir com o aplicativo de nó, que você pode ter que parar, reconstruir e executar novamente. A sessão ngrok retornará informações úteis de depuração nesta janela. A versão paga do ngrok permite nomes persistentes.
Importante
Se você usar a versão gratuita do ngrok, seu aplicativo estará disponível somente durante a sessão atual em seu computador de desenvolvimento. Ele não estará disponível se o computador estiver desligado ou for dormir. Quando você reinicia o serviço, ele retorna um novo endereço. Em seguida, você deve atualizar todos os locais que usam o endereço desatualizado. Lembre-se dessa etapa ao compartilhar o aplicativo para teste.
Criar Node.js pacote de aplicativos
Você pode usar gulp CLI
para criar o pacote de aplicativos para Node.js.
Abra uma janela de terminal.
Verifique se você está no diretório em que o
node.js
é clonado. Esta é a pasta em quegulpfile.js
é colocada.Execute o comando a seguir para criar o pacote de aplicativos Node.js.
$ gulp
Aqui está um exemplo da saída de comando:
[13:39:27] Using gulpfile ~\documents\github\msteams-samples-hello-world-nodejs\gulpfile.js
[13:39:27] Starting 'clean'...
[13:39:27] Starting generate-manifest'...
[13:39:27] Finished 'generate-manifest' after 11 ms
[13:39:27] Finished 'clean after 21 ms
[13:39:27] Starting 'default'... Build completed. Output in manifest folder
[13:39:27] Finished 'default' after 62 μs
O pacote de aplicativos helloworldapp.zip é criado. Você pode encontrar o arquivo de pacote no caminho a seguir.
<path to the cloned repo>/Microsoft-Teams-Samples/samples/app-hello-world/nodejs/manifest
Observação
Pesquisa para o arquivo de pacote de aplicativo, helloworldapp.zip, se o local não estiver claro na ferramenta que você está usando.
Configurar seu primeiro aplicativo Node.js usando o Portal do Desenvolvedor
Você pode usar o Portal do Desenvolvedor para carregar o pacote de aplicativos no Teams e configurar os recursos do aplicativo. O Portal do Desenvolvedor é um aplicativo do Teams que simplifica a criação e o registro de um aplicativo. Instale na Loja do Teams!
Depois de compilar e testar seu aplicativo teams, você pode configurá-lo e visualiza-lo usando o Portal do Desenvolvedor.
A atualização do pacote de aplicativos inclui:
- Importando o pacote de aplicativos para o Portal do Desenvolvedor
- Configurando recursos de aplicativo
Importar o pacote de aplicativos para o Portal do Desenvolvedor
Para importar o pacote de aplicativos:
Abra o Microsoft Teams.
Selecione o ícone Armazenar na barra à esquerda.
Pesquisa para o Portal do Desenvolvedor na barra de pesquisa e selecione Portal do Desenvolvedor*.
Selecione Abrir.
O Portal do Desenvolvedor é aberto.
Selecione a guia Aplicativos .
Selecione Importar aplicativo.
Abra o pacote
helloworldapp.zip
de aplicativos do seguinte caminho em sua estrutura de diretório de repositório de exemplo C#:<path to cloned node.js sample repo>\Source\Repos\Microsoft-Teams-Samples\samples\app-hello-world\nodejs\manifest
O aplicativo Olá, Mundo é importado no Portal do Desenvolvedor.
Depois de importar seu aplicativo para o Portal do Desenvolvedor, você poderá exibir seus detalhes no Portal do Desenvolvedor.
Faça um tour pelo seu aplicativo no Portal do Desenvolvedor
Depois de importar seu aplicativo para o Portal do Desenvolvedor, você poderá exibir seus detalhes, incluindo o arquivo de manifesto.
Exibir informações do aplicativo
Selecione Informações Básicas no painel esquerdo do Portal do Desenvolvedor.
Observe as seguintes informações das informações básicas:
- ID do aplicativo
- Informações do desenvolvedor
- URLs de aplicativo
Selecione Branding no painel esquerdo para exibir as informações de identidade visual.
Esses detalhes são importantes se você estiver escrevendo um novo aplicativo para distribuição.
Exibir recursos do aplicativo
Selecione Recursos de aplicativo no painel esquerdo do Portal do Desenvolvedor.
Os recursos do aplicativo aparecem no painel direito. Você pode exibir cartões para aplicativo pessoal, Bot e Extensão de Mensagem.
Exibir o manifesto do aplicativo
Você usa o arquivo de manifesto para configurar recursos, recursos necessários e outros atributos importantes para seu aplicativo.
Selecione Publicar no painel esquerdo para abrir a lista suspensa e selecione Pacote de aplicativos.
O manifesto do aplicativo é exibido no painel direito.
O arquivo de manifesto é exibido no painel direito.
Configurar os recursos do seu aplicativo
Depois de importar seu aplicativo para o Portal do Desenvolvedor, a próxima etapa é configurar os recursos do aplicativo. O Portal do Desenvolvedor contém todas as informações do aplicativo em seções diferentes. Isso facilita a configuração dos recursos do aplicativo.
Usando o Portal do Desenvolvedor, você pode:
Configurar aplicativo de guia pessoal
Para configurar o aplicativo de guia pessoal:
Selecione o ícone no aplicativo pessoal cartão no painel Recursos de aplicativo e selecione Editar.
Os detalhes da guia Hello são exibidos.
Selecione o ícone para Hello guia e selecione Editar para abrir os detalhes do aplicativo para atualização.
Insira os detalhes do aplicativo para a guia Hello em Adicionar uma guia ao seu aplicativo pessoal.
Insira os seguintes detalhes:
- Nome: guia Hello.
- URL de conteúdo e URL do Site: o endereço de encaminhamento na sessão do console do ngrok.
- Contexto: selecione Guia Pessoal.
Selecione Atualizar.
Os detalhes da guia Hello aparecem no painel Aplicativo Pessoal.
Selecione Salvar.
O painel Aplicativo Pessoal agora mostra a nova guia e uma guia Sobre criada automaticamente.
Configurar bot
É fácil adicionar a funcionalidade de bots ao seu aplicativo. O aplicativo de exemplo Olá, Mundo já tem um bot como parte do exemplo, mas você deve registrá-lo no Teams.
O bot importado do exemplo não tem uma ID de aplicativo associada. Você precisará excluí-lo e criar um novo bot. O Portal do Desenvolvedor cria uma nova ID do aplicativo e registra-a no Teams.
Adicionar e configurar um bot envolve:
Para adicionar um novo bot
Selecione o ícone no bot cartão no painel Recursos do aplicativo e selecione Excluir.
Selecione Ferramentas para adicionar funcionalidade.
Selecione Gerenciamento de bots no painel Ferramentas .
Selecione + Novo Bot no painel de gerenciamento de bots .
Insira um nome adequado para o bot e selecione Adicionar.
O painel Configurar aparece mostrando detalhes do novo bot no painel esquerdo.
Insira a URL de encaminhamento no
ngrok
console e selecione Salvar.Selecione Segredos do cliente e selecione Adicionar um segredo do cliente ao bot para gerar uma senha para o bot.
O Portal do Desenvolvedor gera uma senha para o bot.
Você pode usar o ícone para copiar a senha. Para este tutorial, você não precisa copiá-lo.
Clique em OK.
Selecione < Bots para retornar ao painel de gerenciamento de bots .
O painel de gerenciamento de bots mostra o novo Bot adicionado com uma ID do aplicativo.
Certifique-se de salvar a ID do Bot junto com a senha da seção Segredo do cliente .
Para adicionar bot ao aplicativo
Abra o painel Recursos do aplicativo e selecione o bot cartão.
O painel Bot é exibido.
Selecione seu aplicativo bot em Selecionar um bot existente e selecione Salvar.
O novo bot é adicionado ao seu aplicativo com sua própria ID do aplicativo.
Para configurar o escopo do bot
Selecione o ícone no novo bot cartão e selecione Editar.
Selecione todos os três escopos para o comando na página Bot .
Mova-se pelo painel Bot para exibir a seção Comandos e selecione + Adicionar um Comando.
Insira um nome e uma descrição adequados, selecione todos os três escopos para o Comando e selecione Adicionar.
- Pessoal
- Equipe
- Chat em Grupo
O novo comando é adicionado à seção Comandos do painel Bot .
Selecione Salvar.
Os detalhes do comando são salvos.
Abra o painel Recursos do aplicativo e selecione Cartão de aplicativo pessoal para exibir os detalhes da guia do aplicativo.
Você verá que uma guia para seu novo bot de chat é adicionada ao seu aplicativo.
Configurar a extensão de mensagem
As extensões de mensagem permitem que os usuários peçam informações do serviço e postem essas informações. As informações são postadas na forma de cartões na conversa do canal. As extensões de mensagem aparecem na parte inferior da caixa de composição.
Para adicionar uma nova extensão de mensagem:
Selecione o ícone no cartão de Extensão de Mensagem no painel Recursos do aplicativo e selecione Excluir.
Selecione Extensão de Mensagem no painel Recursos do aplicativo.
Selecione o nome do aplicativo bot na lista suspensa Selecionar um bot existente no painel extensão Mensagem .
Selecione Salvar.
A extensão da mensagem é salva e a seção Comandos é exibida no painel extensão Mensagem .
Selecione + Adicionar um comando para definir o escopo do que seu aplicativo de extensão de mensagem pode fazer.
A caixa de diálogo Adicionar um comando .
Verifique se Pesquisa está selecionado como o tipo de comando que você deseja adicionar na caixa de diálogo Adicionar um comando.
Insira informações adequadas para os seguintes detalhes:
- ID do comando
- Título de comando
- Descrição do comando
Mova a caixa de diálogo para exibir os detalhes restantes.
Verifique se o padrão de make está selecionado.
Selecione os seguintes contextos para o comando de extensão de mensagem:
- Caixa de comando
- Caixa de composição
- Mensagem
Insira informações adequadas para os seguintes detalhes:
- Nome do parâmetro
- Título de parâmetro
- Descrição do parâmetro
Selecione Texto como o tipo de entrada.
Selecione Salvar.
O comando de extensão de mensagem é salvo e aparece na lista de comandos no painel extensão Mensagem .
Selecione Salvar.
Abra o painel Recursos do aplicativo.
Você verá todos os três recursos – aplicativo de guia pessoal, bot e extensão de mensagem – configurados para o aplicativo Olá, Mundo.
Visualizar e testar seu aplicativo Node.js
Depois de importar seu aplicativo e configurar os recursos no Portal do Desenvolvedor, você poderá visualizar e testar o aplicativo de exemplo.
Observação
Atualmente, os desenvolvedores externos não podem usar a opção Visualização no Teams no aplicativo Portal do Desenvolvedor no Teams. Ele não está disponível como um aplicativo no Teams, devido a uma limitação de API. Se você quiser visualizar seu aplicativo no Teams, use o site do Portal do Desenvolvedor .
Depois de configurar os recursos do seu aplicativo, você pode visualizar e testar seu aplicativo no Teams no ambiente local.
Para visualizar seu aplicativo:
Selecione Visualização no Teams na barra de ferramentas do Portal do Desenvolvedor
O Portal do Desenvolvedor informa que seu aplicativo personalizado é carregado com êxito.
Selecione Gerenciar seus aplicativos. Seu aplicativo está listado nos aplicativos carregados.
Localize seu aplicativo usando a caixa de pesquisa, selecione os três pontos em sua linha.
Selecione a opção Exibir . A página Adicionar é exibida para seu aplicativo.
Selecione Adicionar para carregar o aplicativo no Teams.
Seu aplicativo já está disponível no Teams. Você pode exibir todas as guias e testar os recursos:
guia Hello:
Bot de chat:
Você pode enviar uma mensagem usando o chat.
Extensão de mensagem:
Você pode tentar uma pesquisa usando a extensão de mensagem.
Guia Sobre:
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de