Criar seu primeiro aplicativo usando o Node.js

Artigo
Developer (Iniciante)
5 minutos para concluir

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:

Captura de tela do diagrama mostrando que este aplicativo tem três recursos.

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

4 minutos restantes

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!

Acesse o Programa para desenvolvedores 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

3 minutos restantes

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:

Compilar e executar seu primeiro aplicativo
Testar seu aplicativo de exemplo

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, firstou second à 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 que gulpfile.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

2 minutos restantes

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 o aplicativo de guia pessoal.
Configurar bot.
Configurar a extensão de mensagem.

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.

Captura de tela da imagem mostrando o aplicativo bot importado sem ID do aplicativo.

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:

Adicionando um novo bot.
Adicionando bot ao aplicativo.
Configurando o escopo do bot.

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.