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

  • Artigo

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.

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.

    Abrir no GitHub Codespaces

  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 tela da tela de confirmação antes de criar um 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 .

    Captura de tela da opção de menu codespaces para abrir um 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.

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.

    Captura de tela da extensão MongoDB na barra lateral.

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

    Captura de tela do botão adicionar conexão na extensão MongoDB.

  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.

    Captura de tela do botão executar tudo em um playground para a extensão MongoDB.

  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.

    Captura de tela da opção cadeias de conexão na página de um cluster.

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

    Captura de ecrã da credencial da cadeia de ligação para um cluster.

    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.

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.

    Captura de tela de todos os espaços de código em execução, incluindo seu status e modelos.

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

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

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