Conectar um aplicativo Mongoose do Node.js ao Azure Cosmos DB

2024-08-15

APLICA-SE AO: MongoDB

Este tutorial demonstra como usar o Mongoose Framework ao armazenar o Azure Cosmos DB. Vamos usar a API do Azure Cosmos DB para o MongoDB para este passo a passo. Para aqueles não familiarizados, Mongoose é uma estrutura de modelagem de objeto para o MongoDB no Node.js e fornece uma solução simples, com base em esquema para modelar os dados do aplicativo.

O Azure Cosmos DB é o serviço de banco de dados multimodelo distribuído globalmente da Microsoft. É possível criar e consultar rapidamente documentos, chave/valor e bancos de dados do grafo. Todos se beneficiam de recursos de escala horizontal e distribuição global no núcleo do Azure Cosmos DB.

Pré-requisitos

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Você pode experimentar o Azure Cosmos DB gratuitamente, sem uma assinatura do Azure e sem compromisso. Como alternativa, você pode criar uma conta de camada gratuita do Azure Cosmos DB, com as primeiras 1.000 RU/s e 25 GB de armazenamento gratuitos. Você também pode usar o emulador do Azure Cosmos DB com o URI https://localhost:8081. Quanto à chave a ser usada com o emulador, confira Autenticação de solicitações.

Node.js versão v0.10.29 ou superior.

Criar uma conta do Azure Cosmos DB

Vamos criar uma conta do Azure Cosmos DB. Caso já tenha uma conta que queira usar, você poderá pular para Configurar seu aplicativo Node.js. Se estiver usando o Emulador do Azure Cosmos DB, siga as etapas em Emulador do Azure Cosmos DB para configurar o emulador e pule para Configurar seu aplicativo Node.js.

Em uma nova janela do navegador, entre no Portal do Azure.
No menu esquerdo, selecione Criar um recurso.
Na página Novo, selecione Bancos de dados>Azure Cosmos DB.
Na página Selecionar opção de API, escolha Azure Cosmos DB for MongoDB>Criar.

A API determina o tipo de conta a ser criada. Selecione Azure Cosmos DB for MongoDB porque você criará uma coleção que funcione com o MongoDB neste guia de início rápido. Para saber mais, confira Visão geral do Azure Cosmos DB for MongoDB.

Na página Criar Conta do Azure Cosmos DB, insira as configurações da nova conta do Azure Cosmos DB.

Configuração	Valor	Descrição
Subscription	Nome da assinatura	Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos DB.
Grupo de recursos	Nome do grupo de recursos	Selecione um grupo de recursos ou selecione Criar novo, então insira um nome exclusivo para o novo grupo de recursos.
Nome da Conta	Insira um nome exclusivo	Insira um nome exclusivo para identificar a conta do Azure Cosmos DB. O URI da sua conta será mongo.cosmos.azure.com acrescentado ao nome da conta exclusivo. O nome da conta só pode usar letras minúsculas, números e hifens (-) e precisa conter entre 3 e 44 caracteres.
Location	A região mais próxima dos usuários	Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.
Modo de capacidade	Taxa de transferência provisionada ou sem servidor	Selecione Taxa de transferência provisionada para criar uma conta no modo taxa de transferência provisionada. Selecione Sem servidor para criar uma conta no modo sem servidor. Observação: somente a API do MongoDB versões 4.2, 4.0 e 3.6 são compatíveis com contas sem servidor. Escolher 3.2 como a versão forçará a conta para o modo de taxa de transferência provisionada.
Aplicar o desconto por nível gratuito do Azure Cosmos DB	Aplicar ou Não aplicar	Com o nível gratuito do Azure Cosmos DB, você receberá os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente em uma conta. Saiba mais sobre o nível gratuito.
Versão	Escolha a versão de servidor necessária	O Azure Cosmos DB for MongoDB é compatível com as versões 4.2, 4.0, 3.6 e 3.2 do servidor. Você pode fazer upgrade ou downgrade de uma conta depois que ela é criada.

Observação

Você pode ter no máximo uma conta do nível gratuito do Azure Cosmos DB por assinatura do Azure e deve aceitar ao criar a conta. Se você não vir a opção de aplicar o desconto por nível gratuito, significa que outra conta da assinatura já foi habilitada com o nível gratuito.

Captura de tela da página da nova conta do Azure Cosmos DB.

Na guia Distribuição global, configure os detalhes a seguir. Você pode deixar os valores padrão para a finalidade deste guia de início rápido:

Configuração	Valor	Descrição
Redundância geográfica	Desabilitar	Habilite ou desabilite a distribuição global em sua conta emparelhando sua região com uma região de par. Você poderá adicionar mais regiões à sua conta posteriormente.
Gravações de várias regiões	Desabilitar	A capacidade de gravação de várias regiões permite que você aproveite a taxa de transferência provisionada para seus bancos de dados e contêineres em todo o mundo.

Observação

As seguintes opções não estarão disponíveis se você selecionar Sem servidor como Modo de capacidade:

Aplicar desconto por nível gratuito
Redundância geográfica
Gravações de várias regiões

Opcionalmente, você pode configurar detalhes adicionais nas seguintes guias:
- Rede – configurar o acesso de uma rede virtual.
- Política de Backup – configurar a política de backup periódica ou contínua.
- Criptografia – use a chave gerenciada por serviço ou uma chave gerenciada pelo cliente.
- Marcas – marcas são pares nome/valor que permitem categorizar recursos e exibir a cobrança consolidada por meio da aplicação da mesma marca a vários recursos e grupos de recursos.
Selecione Examinar + criar.
A criação da conta leva alguns minutos. Aguarde até que o portal exiba a página Parabéns! A conta do Azure Cosmos DB for MongoDB está pronta.

Criar um banco de dados

Neste aplicativo, abordaremos duas maneiras de criar coleções no Azure Cosmos DB:

Armazenando cada modelo de objeto em uma coleção separada: é recomendável criar um banco de dados com taxa de transferência dedicada. Usar esse modelo de capacidade proporcionará uma melhor eficiência aos custos.
Armazenar todos os modelos de objeto em uma única coleção do Azure Cosmos DB: se você preferir armazenar todos os modelos em uma única coleção, basta criar um banco de dados sem selecionar a opção Provisionar Taxa de Transferência. Usar esse modelo de capacidade criará cada coleção com sua própria capacidade de taxa de transferência para cada modelo de objeto.

Depois de criar o banco de dados, você usará o nome na variável de ambiente COSMOSDB_DBNAME abaixo.

Configurar seu aplicativo Node.js

Observação

Se você quiser apenas uma apresentação do código de exemplo em vez da instalação do aplicativo em si, clone o exemplo usado para este tutorial e crie seu aplicativo Node.js do Mongoose no Azure Cosmos DB.

Para criar um aplicativo Node.js na pasta de sua escolha, execute o seguinte comando em um prompt de comando do nó.

npm init

Responda às perguntas e seu projeto estará pronto para começar.
Adicione um novo arquivo à pasta e denomine index.js.
Instalar os pacotes necessários usando uma das opções npm install:
- Mongoose: npm install mongoose --save
Observação

Para obter mais informações sobre qual versão do mongoose é compatível com a versão do servidor API para MongoDB, consulte Compatibilidade do Mongoose.
- Dotenv (se você quiser carregar seus segredos de um arquivo .env): npm install dotenv --save
  
  Observação
  
  O sinalizador --save adiciona a dependência ao arquivo package.json.

Importe as dependências no arquivo index.js.

var mongoose = require('mongoose');
var env = require('dotenv').config();   //Use the .env file to load the variables

Adicione sua cadeia de conexão do Azure Cosmos DB e nome do Azure Cosmos DB ao arquivo .env. Substitua os espaços reservados {cosmos-account-name} e {dbname} por seu próprio nome de conta e nome de banco de dados do Azure Cosmos DB, sem os símbolos de chave.

// You can get the following connection details from the Azure portal. You can find the details on the Connection string pane of your Azure Cosmos DB account.

COSMOSDB_USER = "<Azure Cosmos DB account's user name, usually the database account name>"
COSMOSDB_PASSWORD = "<Azure Cosmos DB account password, this is one of the keys specified in your account>"
COSMOSDB_DBNAME = "<Azure Cosmos DB database name>"
COSMOSDB_HOST= "<Azure Cosmos DB Host name>"
COSMOSDB_PORT=10255

Conecte-se ao Azure Cosmos DB usando a estrutura de Mongoose adicionando o seguinte código ao final do index.js.

mongoose.connect("mongodb://"+process.env.COSMOSDB_HOST+":"+process.env.COSMOSDB_PORT+"/"+process.env.COSMOSDB_DBNAME+"?ssl=true& replicaSet=globaldb", {
   auth: {
     username: process.env.COSMOSDB_USER,
     password: process.env.COSMOSDB_PASSWORD
   },
   useNewUrlParser: true,
   useUnifiedTopology: true,
   retryWrites: false
})
.then(() => console.log('Connection to CosmosDB successful'))
.catch((err) => console.error(err));

Observação

Aqui, as variáveis de ambiente são carregadas usando process.env.{variableName} usando o pacote npm dotenv.

Quando você estiver conectado ao Azure Cosmos DB, agora você pode começar a configuração de modelos de objeto em Mongoose.

Melhores práticas para usar o Mangoose com o Azure Cosmos DB

Para cada modelo que você cria, o Mongoose cria uma nova coleção. Isso é feito idealmente usando a opção de taxa de transferência no nível do banco de dados, que foi abordada anteriormente. Para usar uma única coleção, você precisa usar discriminadores Mongoose. Discriminators são um mecanismo de herança do esquema. Elas permitem que você tenha vários modelos com esquemas sobrepostos sobre a mesma coleção subjacente do MongoDB.

Você pode armazenar vários modelos de dados na mesma coleção e, em seguida, usar uma cláusula de filtro no momento da consulta para baixar os dados necessários. Vamos examinar cada um dos modelos.

Uma coleção por modelo de objeto

Esta seção explora como conseguir isso com a API do Azure Cosmos DB para MongoDB. Esse método é nossa abordagem recomendada, pois permite que você controle o custo e a capacidade. Como resultado, a quantidade de unidades de solicitação no banco de dados não depende do número de modelos de objeto. Esse é o modelo operacional padrão para o Mongoose, portanto, familiarize-se com o processo.

Abra seu index.js novamente.

Crie a definição de esquema para 'Família'.

const Family = mongoose.model('Family', new mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
        gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}));

Crie um objeto para 'Família'.

const family = new Family({
    lastName: "Volum",
    parents: [
        { firstName: "Thomas" },
        { firstName: "Mary Kay" }
    ],
    children: [
        { firstName: "Ryan", gender: "male", grade: 8 },
        { firstName: "Patrick", gender: "male", grade: 7 }
    ],
    pets: [
        { givenName: "Buddy" }
    ],
    address: { country: "USA", state: "WA", city: "Seattle" }
});

Por fim, vamos salvar o objeto para o Azure Cosmos DB. Isso cria uma coleção nos bastidores.
```
family.save((err, saveFamily) => {
    console.log(JSON.stringify(saveFamily));
});
```

Agora, vamos criar outro esquema e objeto. Esta vez, vamos criar um para 'Destinos de Férias' que as famílias podem se interessar.

Assim como a última vez, vamos criar o esquema

const VacationDestinations = mongoose.model('VacationDestinations', new mongoose.Schema({
 name: String,
 country: String
}));

Crie um objeto de exemplo (você pode adicionar vários objetos a este esquema) e salvá-lo.

const vacaySpot = new VacationDestinations({
 name: "Honolulu",
 country: "USA"
});

vacaySpot.save((err, saveVacay) => {
 console.log(JSON.stringify(saveVacay));
});

Agora, ao ir ao portal do Azure, você observa duas coleções criadas no Azure Cosmos DB.
Por fim, vamos ler os dados do Azure Cosmos DB. Como estamos usando o modelo operacional de Mongoose padrão, as leituras são as mesmas que quaisquer outras leituras com o Mongoose.
```
Family.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family: " + JSON.stringify(fam)));
});
```

Usando o Mongoose Discriminators para armazenar dados em uma única coleção

Nesse método, usamos o Mongoose Discriminators para ajudar a otimizar os custos de cada coleção. O Discriminators permite que você defina uma 'chave' de diferenciação, que permite armazenar, diferenciar e filtrar em modelos de objeto diferente.

Aqui, criamos um modelo do objeto base, definimos uma chave de diferenciação e adicionar 'Família' e 'Destinos de Férias' como uma extensão para o modelo de base.

Vamos definir a configuração de base e definir a chave discriminadora.

const baseConfig = {
    discriminatorKey: "_type", //If you've got a lot of different data types, you could also consider setting up a secondary index here.
    collection: "alldata"   //Name of the Common Collection
};

Em seguida, vamos definir o modelo de objeto comum

const commonModel = mongoose.model('Common', new mongoose.Schema({}, baseConfig));

Agora, podemos definir o modelo 'Família'. Observe aqui que estamos usando commonModel.discriminator em vez de mongoose.model. Além disso, também estamos adicionando a configuração de base para o esquema de mongoose. Portanto, aqui, a chave discriminadora é FamilyType.

const Family_common = commonModel.discriminator('FamilyType', new     mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
       gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}, baseConfig));

Da mesma forma, vamos adicionar outro esquema, esta vez para 'Destinos de Férias'. Aqui, a chave discriminadora é VacationDestinationsType.

const Vacation_common = commonModel.discriminator('VacationDestinationsType', new mongoose.Schema({
    name: String,
    country: String
}, baseConfig));

Por fim, vamos criar objetos para o modelo e salvá-lo.

Vamos adicionar o(s) objeto(s) ao modelo 'Família'.

const family_common = new Family_common({
 lastName: "Volum",
 parents: [
     { firstName: "Thomas" },
     { firstName: "Mary Kay" }
 ],
 children: [
     { firstName: "Ryan", gender: "male", grade: 8 },
     { firstName: "Patrick", gender: "male", grade: 7 }
 ],
 pets: [
     { givenName: "Buddy" }
 ],
 address: { country: "USA", state: "WA", city: "Seattle" }
});

family_common.save((err, saveFamily) => {
 console.log("Saved: " + JSON.stringify(saveFamily));
});

Em seguida, vamos adicionar o(s) objeto(s) ao modelo 'Destino de Férias' e salvá-lo.

const vacay_common = new Vacation_common({
 name: "Honolulu",
 country: "USA"
});

vacay_common.save((err, saveVacay) => {
 console.log("Saved: " + JSON.stringify(saveVacay));
});

Agora, se você voltar ao portal do Azure, observe que você tem apenas uma coleção chamada alldata com dados de 'Família' e 'Destinos de Férias'.
Além disso, observe que cada objeto tem outro atributo chamado de __type, que ajuda você a diferenciar entre os dois modelos de objeto diferente.
Por fim, vamos ler os dados do Azure Cosmos DB. Mongoose se encarrega de filtrar os dados com base no modelo. Assim, você não precisa fazer nada diferente durante a leitura de dados. Apenas especifique seu modelo (neste caso, Family_common) e o Mongoose manipula a filtragem na ‘chave discriminadora’.
```
Family_common.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family (using discriminator): " + JSON.stringify(fam)));
});
```

Como você pode ver, é fácil trabalhar com Mongoose discriminators. Portanto, se você tiver um aplicativo que usa a estrutura de Mongoose, este tutorial é uma forma para você obter o seu aplicativo e executar a API do Azure Cosmos DB para MongoDB sem a necessidade de muitas alterações.

Limpar os recursos

Quando o aplicativo e a conta do Azure Cosmos DB estiverem prontos, você poderá excluir os recursos do Azure criados para não incorrer em mais cobranças. Para excluir os recursos:

Na barra de pesquisa do portal do Azure, procure e selecione Grupos de recursos.
Na lista, selecione o grupo de recursos criado neste início rápido.
Na página Visão geral do grupo de recursos, selecione Excluir grupo de recursos.
Na próxima janela, insira o nome do grupo de recursos a ser excluído e selecione Excluir.

Próximas etapas

Saiba como usar o Studio 3T com a API do Azure Cosmos DB para MongoDB.
Saiba como usar o Robo 3T com a API do Azure Cosmos DB para MongoDB.
Explore exemplos do MongoDB com a API do Azure Cosmos DB para MongoDB.
Tentando fazer um planejamento de capacidade para uma migração para o Microsoft Azure Cosmos DB? Você pode usar informações sobre o cluster de banco de dados existente para fazer isso.
- Se você sabe apenas o número de vCores e servidores no cluster de banco de dados existente, leia sobre como estimar unidades de solicitação com vCores ou vCPUs
- Se souber as taxas de solicitação típicas da carga de trabalho do banco de dados atual, leia sobre como estimar unidades de solicitação usando o planejador de capacidade do Azure Cosmos DB

Compartilhar via

Conectar um aplicativo Mongoose do Node.js ao Azure Cosmos DB

Pré-requisitos

Criar uma conta do Azure Cosmos DB

Criar um banco de dados

Configurar seu aplicativo Node.js

Melhores práticas para usar o Mangoose com o Azure Cosmos DB

Uma coleção por modelo de objeto

Usando o Mongoose Discriminators para armazenar dados em uma única coleção

Limpar os recursos

Próximas etapas

Comentários

Recursos adicionais