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

APLICA-SE AO: MongoDB vCore

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

• Configurar seu ambiente
• Testar o aplicativo MERN com um contêiner local do MongoDB
• 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ê precisará dos seguintes recursos:

• Um cluster vCore existente.
• Uma conta do GitHub.
  • O GitHub vem com horas gratuitas de 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 todos os exercícios deste projeto. Você pode executar o contêiner de desenvolvimento no GitHub Codespaces ou localmente usando o Visual Studio Code.

Codespaces do GitHub

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

Importante

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

1. Inicie o processo para criar um GitHub Codespace no branch main do repositório GitHub azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.

   

2. Na página Criar codespace, analise as definições de configuração do codespace e selecione Criar codespace

   

3. Aguarde até que o codespace seja iniciado. Esse processo de inicialização pode levar alguns minutos.

4. Abra um novo terminal no codespace.

   Dica

   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
   

   Observação

   Este tutorial requer as seguintes versões de cada ferramenta que são pré-instaladas em 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 deste tutorial ocorrem no contexto desse contêiner de desenvolvimento.

Visual Studio Code

A extensão Contêiner de Desenvolvimento para o Visual Studio Code exige que o Docker esteja instalado no seu computador local. A extensão hospeda o contêiner de desenvolvimento localmente usando o host do Docker com as ferramentas do desenvolvedor e as dependências corretas pré-instaladas para concluir esse módulo de treinamento.

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

2. Verifique se a extensão Dev Containers está instalada no Visual Studio Code.

3. Abrir um novo terminal no editor.

   Dica

   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. Clonar o repositório azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app do 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 Contêineres de Desenvolvimento e selecione Contêineres de Desenvolvimento: Reabrir no Contêiner.

   

   Dica

   O Visual Studio Code pode solicitar automaticamente que você reabra a pasta existente em um contêiner de desenvolvimento. Essa funcionalidade equivale 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
   

   Observação

   Este tutorial requer as seguintes versões de cada ferramenta que são pré-instaladas em 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 deste 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 do 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 do MongoDB.

   

3. Adicione uma nova conexão à extensão do MongoDB usando a cadeia de conexão mongodb://localhost.

   

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

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

   

6. A execução 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
     },
     ...
   ]
   

   Observação

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

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

8. No arquivo client/.env, adicione uma variável de ambiente para o seguinte valor:

   Variável de ambiente	Valor
   CONNECTION_STRING	A cadeia de conexão para o cluster vCore do Azure Cosmos DB for MongoDB. Por enquanto, use 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 do Nó (npm).

    npm install
    

11. Iniciar o aplicativo Node.js e 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 a guia/janela extra do navegador.

14. Feche o terminal.

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

Agora, vamos validar se o aplicativo funciona perfeitamente com o Azure Cosmos DB for MongoDB (vCore). Para essa tarefa, preencha o cluster pré-existente com dados de semente 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 da conta do Azure Cosmos DB for MongoDB (vCore) existente.

3. Na página de cluster do Azure Cosmos DB for MongoDB (vCore), selecione a opção do menu de navegação Cadeia 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 espaços reservados <user> 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 Shell do MongoDB usando o comando mongosh e a cadeia de conexão que você registrou anteriormente. Você deve substituir os espaços reservados <user> e <password> pelas credenciais usadas quando criou originalmente o cluster.

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

   Observação

   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 é clusteradmine 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. No shell, execute os comandos a seguir para criar seu banco de dados, criar sua coleção e propagar 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 do mongoDB local. 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

   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	Valor
    CONNECTION_STRING	A cadeia de conexão para o cluster vCore do Azure Cosmos DB for MongoDB. Use a mesma cadeia de conexão que você usou com o shell do 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 a pasta server/, 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 a guia/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. No 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. Caso ainda não tenha feito isso, entre na CLI do Azure usando o comando az login --use-device-code.

5. Altere o diretório de trabalho atual para a pasta server/.

   cd server
   

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

   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 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 do aplicativo Web do servidor com az webapp show e armazene-o em uma variável de shell chamada serverUri.

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

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

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

   Dica

   Às vezes, as implantações podem ser concluídas de forma assíncrona. Se você não estiver vendo 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 de servidor do aplicativo 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 aplicativo para o aplicativo Web cliente chamado 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 do aplicativo Web do servidor com az webapp show e armazene-o em uma variável de shell chamada clientUri.

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

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

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

    Dica

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

15. Feche o terminal.

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, no final de um projeto, é uma boa ideia remover os recursos que já não são necessários. Recursos deixados em execução podem custar dinheiro. Você pode excluir os recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

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

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

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

   az group list
   

Limpar o ambiente de desenvolvimento

Talvez você também queira limpar seu ambiente de desenvolvimento ou retorná-lo ao seu estado normal.

Codespaces do GitHub

A exclusão do ambiente GitHub Codespaces garante que você possa maximizar a quantidade de horas gratuitas por núcleo que você tem direito na sua conta.

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

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

   

3. Abra o menu de contexto do codespace e selecione Excluir.

   

Visual Studio Code

Você não precisa necessariamente limpar seu ambiente local, mas pode interromper 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 Contêineres de Desenvolvimento e selecione Contêineres de Desenvolvimento: Reabrir Pasta Localmente.

   

Dica

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

Próxima etapa

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

Migrar seus dados