Tutorial: Conectar um aplicativo Web Node.js com o Azure Cosmos DB para MongoDB (vCore)

APLICA-SE A: MongoDB vCore

Neste tutorial, você cria um aplicativo Web Node.js que se conecta ao Azure Cosmos DB para MongoDB na arquitetura vCore. A pilha MongoDB, Express, React.js, Node.js (MERN) é uma coleção popular de tecnologias usadas para construir muitas aplicações web modernas. Com o Azure Cosmos DB para MongoDB (vCore), você pode criar um novo aplicativo Web ou migrar um aplicativo existente usando drivers MongoDB com os quais já está familiarizado. Neste tutorial:

• Configurar o ambiente
• Teste o aplicativo MERN com um contêiner MongoDB local
• Testar o aplicativo MERN com um cluster vCore
• Implantar o aplicativo MERN no Serviço de Aplicativo do Azure

Pré-requisitos

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

• Um cluster vCore existente.
• Uma conta GitHub.
  • O GitHub vem com horários gratuitos do Codespaces para todos os usuários.

Configurar o ambiente de desenvolvimento

Um ambiente de contêiner de desenvolvimento está disponível com todas as dependências necessárias para concluir cada exercício neste projeto. Você pode executar o contêiner de desenvolvimento no GitHub Codespaces ou localmente usando o Visual Studio Code.

Espaços de código do GitHub

O GitHub Codespaces executa um contêiner de desenvolvimento gerenciado pelo GitHub com o Visual Studio Code for the Web como interface do usuário. Para o ambiente de desenvolvimento mais simples, use o GitHub Codespaces para que você tenha as ferramentas e dependências de desenvolvedor corretas pré-instaladas para concluir este módulo de treinamento.

Importante

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

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

   

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

   

3. Aguarde até que o espaço de código inicie. Este processo de arranque pode demorar alguns minutos.

4. Abra um novo terminal no codespace.

   Gorjeta

   Você pode usar o menu principal para navegar até a opção de menu Terminal e, em seguida, selecionar a opção Novo Terminal .

   

5. Verifique as versões das ferramentas que você usa neste tutorial.

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

   Nota

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

   Ferramenta	Versão
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   NPM	≥ 9.5.0
   CLI do Azure	≥ 2.46.0

6. Feche o terminal.

7. As etapas restantes neste tutorial ocorrem no contexto desse contêiner de desenvolvimento.

Visual Studio Code

A extensão Dev Containers para Visual Studio Code requer que o Docker seja instalado em sua máquina local. A extensão hospeda o contêiner de desenvolvimento localmente usando o host Docker com as ferramentas de desenvolvedor corretas e dependências pré-instaladas para concluir este módulo de treinamento.

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.

   Gorjeta

   Você pode usar o menu principal para navegar até a opção de menu Terminal e, em seguida, selecionar a opção Novo Terminal .

   

4. Clone o azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app repositório GitHub no 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.

   

   Gorjeta

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

   

6. Verifique as versões das ferramentas que você usa neste tutorial.

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

   Nota

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

   Ferramenta	Versão
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   NPM	≥ 9.5.0
   CLI do Azure	≥ 2.46.0

7. Feche o terminal.

8. As etapas restantes neste tutorial ocorrem no contexto desse contêiner de desenvolvimento.

Teste a API do aplicativo MERN com o contêiner MongoDB

Comece executando a API do aplicativo de exemplo com o contêiner MongoDB local para validar se o aplicativo funciona.

1. Execute um contêiner do MongoDB usando o Docker e publique 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 conexão à extensão MongoDB usando a cadeia de conexão mongodb://localhost.

   

4. Quando a conexão for bem-sucedida, abra o arquivo data/products.mongodb playground.

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

   

6. A corrida do playground deve resultar em uma 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
     },
     ...
   ]
   

   Nota

   As ids de objeto (_id) são geradas aleatoriamente e serão diferentes dessa saída de exemplo truncada.

7. No diretório server/, crie um novo arquivo .env.

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

   Variável de Ambiente	Value
   CONNECTION_STRING	A cadeia de conexão com o cluster do Azure Cosmos DB para MongoDB (vCore). Por enquanto, utilize mongodb://localhost:27017?directConnection=true.

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

9. Altere o contexto do terminal para a pasta server/ .

   cd server
   

10. Instale as dependências do Gerenciador de Pacotes de Nó (npm).

    npm install
    

11. Inicie o aplicativo Node.js & Express.

    npm start
    

12. A API abre automaticamente uma janela do navegador para verificar se ela retorna uma matriz de documentos do produto.

13. Feche o separador/janela extra do navegador.

14. Feche o terminal.

Testar o aplicativo MERN com o cluster do Azure Cosmos DB para MongoDB (vCore)

Agora, vamos validar se o aplicativo funciona perfeitamente com o Azure Cosmos DB para MongoDB (vCore). Para essa tarefa, preencha o cluster pré-existente com dados de propagação usando o shell do MongoDB e atualize a cadeia de conexão da API.

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

2. Navegue até a página de cluster existente do Azure Cosmos DB para MongoDB (vCore).

3. Na página de cluster do Azure Cosmos DB para MongoDB (vCore), selecione a opção do menu de navegação Cadeias de conexão.

   

4. Registre o valor do campo Cadeia de conexão .

   

   Importante

   A cadeia de conexão no portal não inclui os valores de nome de usuário e senha. Você deve substituir os <user> espaços reservados e <password> pelas credenciais usadas quando criou originalmente o cluster.

5. De volta ao seu ambiente de desenvolvimento integrado (IDE), abra um novo terminal.

6. Inicie o MongoDB Shell usando o mongosh comando e a cadeia de conexão que você gravou anteriormente. Certifique-se de substituir os <user> espaços reservados e <password> pelas credenciais usadas quando criou originalmente o cluster.

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

   Nota

   Talvez seja necessário codificar valores específicos para a cadeia de conexão. Neste exemplo, o nome do cluster é msdocs-cosmos-tutorial, o nome de usuário é clusteradmin, e a senha é P@ssw.rd. Na senha, o @ caractere precisará ser codificado usando %40. Um exemplo de cadeia de conexão é fornecido aqui com a codificação correta da senha.

   CONNECTION_STRING=mongodb+srv://clusteradmin:P%40ssw.rd@msdocs-cosmos-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 seu banco de dados, criar sua coleção e semear com 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 em uma 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
     },
     ...
   ]
   

   Nota

   As ids de objeto (_id) são geradas aleatoriamente e serão diferentes dessa saída de exemplo truncada.

9. Saia do shell do MongoDB.

   exit
   

10. No diretório client/, crie um novo arquivo .env.

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

    Variável de Ambiente	Value
    CONNECTION_STRING	A cadeia de conexão com o cluster do Azure Cosmos DB para MongoDB (vCore). Use a mesma cadeia de conexão que você usou com o shell mongo.

    CONNECTION_STRING=<your-connection-string>
    

12. Valide se o aplicativo está usando o serviço de banco de dados alterando o contexto do terminal para o servidor/ pasta, instalando dependências do Gerenciador de Pacotes de Nó (npm) e iniciando o aplicativo.

    cd server
    
    npm install
    
    npm start
    

13. A API abre automaticamente uma janela do navegador para verificar se ela retorna uma matriz de documentos do produto.

14. Feche o separador/janela extra do navegador. Em seguida, feche o terminal.

Implantar o aplicativo MERN no Serviço de Aplicativo do Azure

Implante o serviço e o cliente no Serviço de Aplicativo do Azure para provar que o aplicativo funciona de ponta a ponta. Use segredos nos aplicativos Web para armazenar variáveis de ambiente com credenciais e pontos de extremidade de API.

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

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

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

3. Crie variáveis de shell para os dois aplicativos Web chamados 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 fez, entre na CLI do Azure usando o az login --use-device-code comando.

5. Altere o diretório de trabalho atual para o caminho do servidor/ .

   cd server
   

6. Crie um novo aplicativo Web para o componente de servidor do aplicativo MERN com az webapp upo .

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

7. Crie uma nova configuração de cadeia de conexão para o aplicativo Web do servidor chamado CONNECTION_STRING com az webapp config connection-string set. Use o mesmo valor para a cadeia de conexão usada com o shell do MongoDB e o arquivo .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 para o aplicativo Web do servidor e az webapp show armazene-o em uma variável de shell chamada d serverUri.

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

9. Use o pacote e o open-cli comando do NuGet com npx para abrir uma janela do navegador usando o URI do aplicativo Web do servidor. Valide se o aplicativo servidor está retornando seus dados de matriz JSON do cluster MongoDB (vCore).

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

   Gorjeta

   Às vezes, as implantações podem ser concluídas de forma assíncrona. Se não estiver a ver o que espera, aguarde mais um minuto e atualize a janela do navegador.

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

    cd ../client
    

11. Crie um novo aplicativo Web para o componente cliente do aplicativo MERN com az webapp upo .

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

12. Crie uma nova configuração de aplicativo para o aplicativo Web cliente nomeado REACT_APP_API_ENDPOINT com az webapp config appsettings set. Use o ponto de extremidade da API do servidor armazenado na variável de shell serverUri .

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

13. Obtenha o URI para o aplicativo Web cliente e az webapp show armazene-o em uma variável de shell com o nome d clientUri.

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

14. Use o pacote e o open-cli comando do NuGet com npx para abrir uma janela do navegador usando o URI do aplicativo Web cliente. Valide se o aplicativo cliente está renderizando dados da API do aplicativo servidor.

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

    Gorjeta

    Às vezes, as implantações podem ser concluídas de forma assíncrona. Se não estiver a ver o que espera, aguarde mais um minuto e atualize a janela do navegador.

15. Feche o terminal.

Clean up resources (Limpar recursos)

Quando estiver a trabalhar na sua própria subscrição, no final de um projeto, é uma boa ideia remover os recursos de que já não necessita. Os recursos que deixar em execução podem custar dinheiro. Pode eliminar recursos individualmente ou eliminar o grupo de recursos para eliminar todo o conjunto de recursos.

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

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

2. Valide se o grupo de recursos foi excluído usando az group listo .

   az group list
   

Limpar o ambiente de desenvolvimento

Você também pode querer limpar seu ambiente de desenvolvimento ou devolvê-lo ao seu estado típico.

Espaços de código do GitHub

Excluir o ambiente do GitHub Codespaces garante que você possa maximizar a quantidade de direitos de horas gratuitas por núcleo que você obtém para sua conta.

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

2. Localize seus espaços de código atualmente em execução provenientes do azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app repositório GitHub.

   

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

   

Visual Studio Code

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: Reopen Folder Locally.

   

Gorjeta

O Visual Studio Code interromperá o contêiner de desenvolvimento em execução, mas o contêiner ainda existe no Docker em um estado interrompido. Você sempre tem a opção de excluir a instância do contêiner, a imagem do contêiner e os volumes do Docker para liberar mais espaço na máquina local.

Próximo passo

Agora que você criou seu primeiro aplicativo para o cluster MongoDB (vCore), saiba como migrar seus dados para o Azure Cosmos DB.

Migrar os dados