Tutorial: Conectar um aplicativo Web Node.js com o Azure DocumentDB

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

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

Pré-requisitos

Para concluir este tutorial, você precisará dos seguintes recursos:

• Uma assinatura do Azure

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

• Um cluster existente do Azure DocumentDB

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

• Uma conta do GitHub com acesso ao Codespaces do GitHub

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 nos Codespaces do GitHub 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 a Web como a interface do usuário. Para o ambiente de desenvolvimento mais simples, use os Codespaces do GitHub 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 Codespaces por até 60 horas gratuitas por mês com duas instâncias principais.

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

   

2. Na página Criar codespace , examine as configurações do codespace e selecione Criar novo codespace

   

3. Aguarde até que o codespace inicie. 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:

   Tool	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.

Código do Visual Studio

A extensão Dev Containers para Visual Studio Code requer que o Docker seja instalado no computador local. A extensão hospeda o contêiner de desenvolvimento localmente usando o host do Docker com as ferramentas e dependências de desenvolvedor corretas 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 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 .

   Captura de tela da opção de menu codespaces para abrir um 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 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 etapa é funcionalmente equivalente ao uso da paleta de comandos para reabrir o workspace 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:

   Tool	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.

Testar a API do aplicativo MERN com o contêiner do 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 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 do 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

   Os identificadores de objeto (_id) são gerados aleatoriamente e diferem dessa saída de exemplo truncada.

7. No servidor/ diretório, 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 DocumentDB. Por enquanto, use mongodb://localhost:27017?directConnection=true.

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

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

   cd server
   

10. Instale as dependências do Gerenciador de Pacotes do Node (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 a aba extra do navegador.

14. Feche o terminal.

Testar o aplicativo MERN com o cluster do Azure DocumentDB

Agora, vamos validar que o aplicativo funciona perfeitamente com o Azure DocumentDB. 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 de cluster existente do Azure DocumentDB.

3. Na página do cluster do Azure DocumentDB, selecione a opção no menu 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 espaços reservados <user> e <password> pelas credenciais que você usou quando criou o cluster originalmente.

5. Abra um novo terminal no IDE (ambiente de desenvolvimento integrado).

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

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

   Observação

   Você pode precisar codificar valores específicos para a cadeia de conexão. Neste exemplo, o nome do cluster é msdocs-azure-documentdb-tutorial, o nome de usuário é clusteradmin, e a senha é P@ssw.rd. Na senha, o @ caractere precisa ser codificado usando %40. Uma cadeia de conexão de exemplo é fornecida aqui com a codificação correta da senha.

   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. No shell, execute os comandos a seguir para criar seu banco de dados, criar sua coleção e inicializar 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
     },
     ...
   ]
   

   Observação

   Os identificadores de objeto (_id) são gerados aleatoriamente e diferem dessa saída de exemplo truncada.

9. Saia do shell do MongoDB.

   exit
   

10. No diretório/cliente , 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 DocumentDB. Use a mesma cadeia de conexão usada 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 o servidor/ pasta, instalando dependências do Gerenciador de Pacotes do 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 aba/janela extra do navegador. Em seguida, feche o terminal.

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

Prove que o aplicativo funciona de ponta a ponta implantando o serviço e o cliente no Serviço de Aplicativo do Azure. Use segredos nos aplicativos da web para armazenar variáveis de ambiente com credenciais e endpoints de API.

1. Em seu IDE (ambiente de desenvolvimento integrado), 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 o aplicativo Web chamado 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 az login --use-device-code comando.

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

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

   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 cliente/ caminho.

    cd ../client
    

11. Crie um novo aplicativo Web para o componente cliente 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 nomeado REACT_APP_API_ENDPOINT com az webapp config appsettings set. Utilize o ponto de extremidade da API do servidor armazenado na variável 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 do cliente com az webapp show e armazene-o em uma variável de shell 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 todo o grupo de recursos, use az group delete.

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

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

   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.

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 o contêiner de desenvolvimento atualmente em execução proveniente do azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app repositório GitHub.

   

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

   

Código do Visual Studio

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 interrompe o contêiner de desenvolvimento em execução, mas o contêiner ainda existe no Docker em um estado parado. Você sempre pode 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

Migrar seus dados