Tutorial: Liga uma aplicação web Node.js com o Azure DocumentDB

Neste tutorial, constróis uma aplicação web Node.js que se liga ao Azure DocumentDB. A pilha MongoDB, Express, React.js, Node.js (MERN) é um conjunto popular de tecnologias utilizadas para construir muitas aplicações web modernas. Com o Azure DocumentDB, pode criar uma nova aplicação web ou migrar uma aplicação existente usando drivers do MongoDB com os quais já está familiarizado. Neste tutorial, você:

• Configurar o ambiente
• Teste a aplicação MERN com um contentor MongoDB local
• Teste a aplicação MERN com um cluster
• Implemente a aplicação MERN no Azure App Service

Pré-requisitos

Para concluir este tutorial, você precisa dos seguintes recursos:

• Uma assinatura do Azure

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita

• Um cluster do Azure DocumentDB existente

  • Se não tiver um cluster, crie um novo cluster

• Uma conta GitHub com direito a GitHub Codespaces

Configurar o ambiente de desenvolvimento

Está disponível um ambiente de contentor de desenvolvimento com todas as dependências necessárias para completar todos os exercícios deste projeto. Podes executar o contentor de desenvolvimento no GitHub Codespaces ou localmente usando o Visual Studio Code.

Espaços de código do GitHub

O GitHub Codespaces executa um contentor de desenvolvimento gerido pelo GitHub com Visual Studio Code for the Web como interface de utilizador. Para o ambiente de desenvolvimento mais direto, use o GitHub Codespaces para ter as ferramentas e dependências de desenvolvimento corretas pré-instaladas para completar este módulo de formação.

Importante

Todas as contas do GitHub podem usar Codespaces por até 60 horas gratuitas por mês com duas instâncias principais.

1. Inicie o processo para criar um novo Codespace do GitHub na ramificação main do repositório GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

2. Na página Criar espaço de código, revise as definições de configuração do espaço de código e selecione Criar novo espaço de código

   Captura de ecrã do ecrã de confirmação antes de criar um novo espaço de código.

3. Aguarde até que o codespace inicie. Este processo de arranque pode demorar alguns minutos.

4. Abra um novo terminal no espaço de códigos.

   Sugestão

   Podes usar o menu principal para navegar até à opção do menu Terminal e depois selecionar a opção Novo Terminal .

   

5. Consulta as versões das ferramentas que usas neste tutorial.

   docker --version
   
   node --version
   
   npm --version
   
   az --version
   

   Observação

   Este tutorial requer as seguintes versões de cada ferramenta, que estão pré-instaladas no seu ambiente:

   Tool	Versão
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI (Interface de Linha de Comando da Azure)	≥ 2.46.0

6. Fecha o terminal.

7. Os passos restantes deste tutorial decorrem no contexto deste contentor de desenvolvimento.

Código do Visual Studio

A extensão Dev Containers para Visual Studio Code requer que o Docker esteja instalado na sua máquina local. A extensão aloja o contentor de desenvolvimento localmente usando o host Docker com as ferramentas e dependências de desenvolvimento corretas pré-instaladas para completar este módulo de treino.

1. Abra o Visual Studio Code no contexto de um diretório vazio.

2. Verifique se você tem a extensão Dev Containers instalada no Visual Studio Code.

3. Abra um novo terminal no editor.

   Sugestão

   Podes usar o menu principal para navegar até à opção do menu Terminal e depois selecionar a opção Novo Terminal .

   Captura de ecrã da opção de menu para abrir um novo terminal.

4. Clone o azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app repositório do GitHub para o diretório atual.

   git clone https://github.com/azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.git .
   

5. Abra a Paleta de comandos, procure os comandos Dev Containers e selecione Dev Containers: Reopen in Container.

   

   Sugestão

   O Visual Studio Code pode solicitar automaticamente que você reabra a pasta existente dentro de um contêiner de desenvolvimento. Este passo é funcionalmente equivalente a usar a paleta de comandos para reabrir o espaço de trabalho atual num contentor.

   

6. Consulta as versões das ferramentas que usas neste tutorial.

   docker --version
   
   node --version
   
   npm --version
   
   az --version
   

   Observação

   Este tutorial requer as seguintes versões de cada ferramenta, que estão pré-instaladas no seu ambiente:

   Tool	Versão
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI (Interface de Linha de Comando da Azure)	≥ 2.46.0

7. Fecha o terminal.

8. Os passos restantes deste tutorial decorrem no contexto deste contentor de desenvolvimento.

Teste a API da aplicação MERN com o contentor MongoDB

Comece por correr a API da aplicação de exemplo com o contentor local do MongoDB para validar que a aplicação funciona.

1. Executa um contentor MongoDB usando Docker e publica a porta típica do MongoDB (27017).

   docker pull mongo:6.0
   
   docker run --detach --publish 27017:27017 mongo:6.0
   

2. Na barra lateral, selecione a extensão MongoDB.

   

3. Adicione uma nova ligação à extensão do MongoDB usando a cadeia mongodb://localhostde ligação .

   

4. Quando a ligação for bem-sucedida, abra o ficheiro de playground data/products.mongodb.

5. Selecione o ícone Executar tudo para executar o script.

   

6. A execução no ambiente de testes deve resultar em uma lista de documentos na coleção local do MongoDB. Aqui está um exemplo truncado do resultado.

   [
     {
       "_id": { "$oid": "640a146e89286b79b6628eef" },
       "name": "Confira Watch",
       "category": "watches",
       "price": 105
     },
     {
       "_id": { "$oid": "640a146e89286b79b6628ef0" },
       "name": "Diannis Watch",
       "category": "watches",
       "price": 98,
       "sale": true
     },
     ...
   ]
   

   Observação

   Os identificadores de objeto (_id) são gerados aleatoriamente e diferem deste exemplo truncado.

7. No servidor/ diretório, cria um novo ficheiro .env .

8. No ficheiro server/.env , adicione uma variável de ambiente para este valor:

   Variável de Ambiente	Valor
   CONNECTION_STRING	A cadeia de ligação ao cluster Azure DocumentDB. Por agora, use mongodb://localhost:27017?directConnection=true.

   CONNECTION_STRING=mongodb://localhost:27017?directConnection=true
   

9. Muda o contexto do terminal para o servidor/ pasta.

   cd server
   

10. Instale as dependências usando o npm.

    npm install
    

11. Iniciar a aplicação Node.js e Express.

    npm start
    

12. A API abre automaticamente uma janela do navegador para verificar se devolve um conjunto de documentos de produto.

13. Fecha o separador/janela extra do navegador.

14. Fecha o terminal.

Teste a aplicação MERN com o cluster Azure DocumentDB

Agora, vamos validar que a aplicação funciona perfeitamente com o Azure DocumentDB. Para esta tarefa, preenche o cluster pré-existente com dados seed usando o shell MongoDB e depois atualiza a cadeia de ligação da API.

1. Entre no portal do Azure (https://portal.azure.com).

2. Navegue até à página existente do cluster Azure DocumentDB.

3. Na página do cluster Azure DocumentDB, selecione a opção de navegação cadeias de conexão.

   

4. Registe o valor do campo string de conexão.

   

   Importante

   A cadeia de ligação no portal não inclui os valores de nome de utilizador e palavra-passe. Deve substituir os marcadores de posição <user> e <password> pelas credenciais que utilizou quando originalmente criou o cluster.

5. Abra um novo terminal dentro do seu ambiente integrado de desenvolvimento (IDE).

6. Inicia o MongoDB Shell usando o mongosh comando e a string de ligação que gravaste anteriormente. Certifica-te de que substituis os <user> marcadores de lugar e <password> pelas credenciais que usaste quando criaste originalmente o cluster.

   mongosh "<mongodb-cluster-connection-string>"
   

   Observação

   Pode ser necessário codificar valores específicos para a cadeia de ligação. Neste exemplo, o nome do cluster é msdocs-azure-documentdb-tutorial, o nome de utilizador é clusteradmin, e a palavra-passe é P@ssw.rd. Na palavra-passe, o @ carácter tem de ser codificado usando %40. Aqui é fornecida uma cadeia de ligação de exemplo com a codificação correta da palavra-passe.

   CONNECTION_STRING=mongodb+srv://clusteradmin:P%40ssw.rd@msdocs-azure-documentdb-tutorial.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000
   

7. Dentro do shell, execute os seguintes comandos para criar a sua base de dados, criar a sua coleção e semear dados iniciais.

   use('cosmicworks');
   
   db.products.drop();
   
   db.products.insertMany([
     { name: "Confira Watch", category: "watches", price: 105.00 },
     { name: "Diannis Watch", category: "watches", price: 98.00, sale: true },
     { name: "Sterse Gloves", category: "gloves", price: 42.00 },
     { name: "Peache Sunglasses", category: "eyewear", price: 32.00, sale: false, sizes: [ "S", "M", "L" ] },
     { name: "Icento Pack", category: "bags", price: 58.00 },
     { name: "Iroowl Bracelet", category: "watches", price: 66.00 },
     { name: "Glaark Bag", category: "bags", price: 56.00, sale: true },
     { name: "Windry Mittens", category: "gloves", price: 35.00 },
     { name: "Tuvila Hat", category: "hats", price: 120.00 },
     { name: "Klinto Hat", category: "hats", subcategory: "hats-beanies", price: 65.00 }
   ]);
   
   db.products.find({});
   

8. Os comandos devem resultar numa lista de documentos na coleção local do MongoDB. Aqui está um exemplo truncado da saída.

   [
     {
       "_id": { "$oid": "640a146e89286b79b6628eef" },
       "name": "Confira Watch",
       "category": "watches",
       "price": 105
     },
     {
       "_id": { "$oid": "640a146e89286b79b6628ef0" },
       "name": "Diannis Watch",
       "category": "watches",
       "price": 98,
       "sale": true
     },
     ...
   ]
   

   Observação

   Os identificadores de objeto (_id) são gerados aleatoriamente e diferem deste exemplo truncado.

9. Saia do shell do MongoDB.

   exit
   

10. No diretório cliente/ , crie um novo ficheiro .env .

11. No ficheiro cliente/.env , adicione uma variável de ambiente para este valor:

    Variável de Ambiente	Valor
    CONNECTION_STRING	A cadeia de ligação ao cluster Azure DocumentDB. Usa a mesma corda de ligação que usaste com a concha do mongo.

    CONNECTION_STRING=<your-connection-string>
    

12. Valide que a aplicação está a usar o serviço de base de dados alterando o contexto do terminal para o servidor/ pasta, instalando dependências a partir do Node Package Manager (npm) e depois iniciando a aplicação.

    cd server
    
    npm install
    
    npm start
    

13. A API abre automaticamente uma janela do navegador para verificar se devolve um conjunto de documentos de produto.

14. Fecha o separador/janela extra do navegador. Depois, fecha o terminal.

Implemente a aplicação MERN no Azure App Service

Prove que a aplicação funciona de ponta a ponta implementando o serviço e o cliente no Azure App Service. Use segredos nas aplicações web para armazenar variáveis de ambiente com credenciais e endpoints da API.

1. No seu ambiente integrado de desenvolvimento (IDE), abra um novo terminal.

2. Crie uma variável shell para o nome do grupo de recursos pré-existente chamada resourceGroupName.

   # Variable for resource group name
   resourceGroupName="<existing-resource-group>"
   

3. Crie variáveis de shell para as duas aplicações web chamadas serverAppName e clientAppName.

   # Variable for randomnly generated suffix
   let suffix=$RANDOM*$RANDOM
   
   # Variable for web app names with a randomnly generated suffix
   serverAppName="server-app-$suffix"
   clientAppName="client-app-$suffix"
   

4. Se ainda não o fizeste, inicia sessão no Azure CLI usando o az login --use-device-code comando.

5. Altera o diretório de trabalho atual para o caminho server/.

   cd server
   

6. Crie uma nova aplicação web para o componente servidor da aplicação MERN com az webapp up.

   az webapp up \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --sku F1 \
       --runtime "NODE|18-lts"
   

7. Crie uma nova definição de cadeia de ligação para a aplicação web do servidor denominada CONNECTION_STRING com az webapp config connection-string set. Use o mesmo valor para a string de ligação que usou com o shell do MongoDB e o ficheiro .env anteriormente neste tutorial.

   az webapp config connection-string set \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --connection-string-type custom \
       --settings "CONNECTION_STRING=<mongodb-connection-string>"
   

8. Obtenha o URI da aplicação az webapp show web do servidor e guarde-o numa variável shell chamada d serverUri.

   serverUri=$(az webapp show \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --query hostNames[0] \
       --output tsv)
   

9. Use o open-cli pacote e o comando do NuGet com npx para abrir uma janela do navegador usando o URI da aplicação web do servidor. Valide que a aplicação do servidor está a devolver os dados do array JSON a partir do cluster.

   npx open-cli "https://$serverUri/products" --yes
   

   Sugestão

   Por vezes, as implementações podem terminar de forma assíncrona. Se não estiver a ver o que espera, espere mais um minuto e atualize a janela do navegador.

10. Altere o diretório de trabalho para o caminho cliente/.

    cd ../client
    

11. Crie uma nova aplicação web para o componente cliente da aplicação MERN com az webapp up.

    az webapp up \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --sku F1 \
        --runtime "NODE|18-lts"
    

12. Crie uma nova configuração de aplicação para a aplicação web cliente chamada REACT_APP_API_ENDPOINT com az webapp config appsettings set. Utilize o endpoint da API do servidor armazenado na variável do shell serverUri.

    az webapp config appsettings set \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --settings "REACT_APP_API_ENDPOINT=https://$serverUri"
    

13. Obtenha o URI da aplicação web de cliente com az webapp show e guarde-o numa variável shell chamada clientUri.

    clientUri=$(az webapp show \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --query hostNames[0] \
        --output tsv)
    

14. Use o open-cli pacote e o comando do NuGet com npx para abrir uma janela do navegador usando o URI da aplicação web do cliente. Valide que a aplicação cliente está a renderizar dados da API da aplicação servidora.

    npx open-cli "https://$clientUri" --yes
    

    Sugestão

    Por vezes, as implementações podem terminar de forma assíncrona. Se não estiver a ver o que espera, espere mais um minuto e atualize a janela do navegador.

15. Fecha o terminal.

Limpeza de recursos

Quando estiver a trabalhar na sua própria subscrição, ao terminar um projeto, é uma boa ideia remover os recursos de que já não necessita. Os recursos deixados em funcionamento podem custar-lhe dinheiro. Você pode excluir recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

1. Para eliminar todo o grupo de recursos, use az group delete.

   az group delete \
       --name $resourceGroupName \
       --yes
   

2. Valide que o grupo de recursos foi eliminado usando az group list.

   az group list
   

Limpar o ambiente de desenvolvimento

Também pode querer limpar o seu ambiente de desenvolvimento ou devolvê-lo ao seu estado habitual.

Espaços de código do GitHub

Excluir o ambiente do GitHub Codespaces garante que possas maximizar a quantidade de horas gratuitas por núcleo a que tens direito na tua conta.

1. Entre no painel do GitHub Codespaces (https://github.com/codespaces).

2. Localize o seu contentor de desenvolvimento atualmente em execução, proveniente do azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app repositório do GitHub.

   

3. Abra o menu de contexto do espaço de código e selecione Excluir.

   Captura de ecrã do menu de contexto para um único espaço de código com a opção de eliminação realçada.

Código do Visual Studio

Você não é necessariamente obrigado a limpar seu ambiente local, mas pode parar o contêiner de desenvolvimento em execução e retornar à execução do Visual Studio Code no contexto de um espaço de trabalho local.

1. Abra a Paleta de Comandos, procure os comandos Dev Containers e selecione Dev Containers: Reabrir Pasta Localmente.

   

Sugestão

O Visual Studio Code interrompe o contêiner de desenvolvimento em execução, mas o contêiner ainda existe no Docker em um estado interrompido. Podes sempre eliminar a instância do contentor, a imagem do contentor e os volumes do Docker para libertar mais espaço na tua máquina local.

Próximo passo

Migre os seus dados