Início Rápido: driver do Azure Cosmos DB for MongoDB para Node.js

APLICA-SE AO: MongoDB

Introdução ao pacote npm do MongoDB para criar bancos de dados, coleções e documentos no recurso do Azure Cosmos DB. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Documentação de referência da API para MongoDB | Pacote MongoDB (NuGet) pacotes/Microsoft.Azure.Cosmos) | Azure Developer CLI

Pré-requisitos

Configurando

Implante o contêiner de desenvolvimento deste projeto no seu ambiente. Em seguida, use o Azure Developer CLI (azd) para criar uma conta do Azure Cosmos DB for MongoDB e implantar um aplicativo de exemplo em contêiner. O aplicativo de exemplo usa a biblioteca de clientes para gerenciar, criar, ler e consultar dados de exemplo.

1. Abra um terminal no diretório raiz do projeto.

2. Autentique-se no Azure Developer CLI usando azd auth login. Siga as etapas especificadas pela ferramenta para se autenticar na CLI usando suas credenciais preferenciais do Azure.

   azd auth login
   

3. Execute azd init para inicializar o projeto.

   azd init --template cosmos-db-mongodb-nodejs-quickstart
   

   Observação

   Este início rápido usa o repositório GitHub do modelo azure-samples/cosmos-db-mongodb-nodejs-quickstart. A CLI do Desenvolvedor do Azure clonará automaticamente esse projeto em seu computador se ele ainda não estiver lá.

4. Durante a inicialização, configure um nome de ambiente exclusivo.

   Dica

   O nome do ambiente também será usado como o nome do grupo de recursos de destino. Neste início rápido, considere o uso de msdocs-cosmos-db.

5. Implante a conta do Azure Cosmos DB usando azd up. Os modelos do Bicep também implantam um aplicativo Web de exemplo.

   azd up
   

6. Durante o processo de provisionamento, selecione sua assinatura e o local desejado. Aguarde o processo de provisionamento ser concluído. O processo pode levar aproximadamente cinco minutos.

7. Depois que o provisionamento dos recursos do Azure for concluído, uma URL para o aplicativo Web em execução será incluída na saída.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Use a URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

   

Instalar o pacote

Adicione o pacote npm do MongoDB ao projeto JavaScript. Use o comando npm install package que especifica o nome do pacote npm. O pacote dotenv é usado para ler as variáveis de ambiente de um arquivo .env durante o desenvolvimento local.

npm install mongodb dotenv

Modelo de objeto

Antes de começar a criar o aplicativo, vamos examinar a hierarquia de recursos no Azure Cosmos DB. O Azure Cosmos DB tem um modelo de objeto específico que é usado para criar e acessar recursos. Ele cria recursos em uma hierarquia que consiste em contas, bancos de dados, contêineres e documentos.

Você usa as seguintes classes do MongoDB para interagir com esses recursos:

• MongoClient ─ Esta classe fornece a representação lógica do lado do cliente da camada da API do MongoDB no Azure Cosmos DB. Esse objeto do cliente é usado para configurar e executar solicitações no serviço.
• Db: essa classe é uma referência a um banco de dados que pode ou não existir no serviço. O banco de dados é validado no lado do servidor quando você tenta acessá-lo ou executa uma operação nele.
• Collection: essa classe é uma referência a uma coleção que também pode ainda não existir no serviço. A coleção é validada no lado do servidor quando você tenta trabalhar com ela.

Exemplos de código

• Autenticar o cliente
• Obter instância de banco de dados
• Obter instância de coleção
• Usar métodos encadeados
• Crie um índice
• Criar um documento
• Obter um documento
• Executar consultas

O código de exemplo descrito neste artigo cria um banco de dados chamado adventureworks com uma coleção chamada products. A coleção products foi projetada para conter detalhes do produto, como nome, categoria, quantidade e um indicador de venda. Cada produto também contém um identificador exclusivo.

Neste procedimento, o banco de dados não usa fragmentação.

Autenticar o cliente

1. No diretório do projeto, crie um arquivo index.js. Em seu editor, adicione instruções requires para fazer referência aos pacotes npm do MongoDB e do DotEnv.

   // Read .env file and set environment variables
   require('dotenv').config();
   const random = Math.floor(Math.random() * 100);
   
   // Use official mongodb driver to connect to the server
   const { MongoClient, ObjectId } = require('mongodb');
   

2. Defina uma nova instância da classe MongoClient, usando o construtor e process.env. para ler a variável de ambiente que você criou anteriormente.

   // New instance of MongoClient with connection string
   // for Cosmos DB
   const url = process.env.COSMOS_CONNECTION_STRING;
   const client = new MongoClient(url);
   

Para saber mais sobre diferentes maneiras de criar uma instância MongoClient, confira Início Rápido do driver NodeJS do MongoDB.

Configurar operações assíncronas

No arquivo index.js, adicione o seguinte código para dar suporte às operações assíncronas:

async function main(){

// The remaining operations are added here
// in the main function

}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

Os snippets de código a seguir devem ser adicionados à função main para manipular a sintaxe async/await.

Conectar-se ao banco de dados

Use o método MongoClient.connect para se conectar ao recurso Azure Cosmos DB for MongoDB. O método conectar retorna uma referência ao banco de dados.

// Use connect method to connect to the server
await client.connect();

Obter instância de banco de dados

Use o MongoClient.db para obter uma referência a um banco de dados.

// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);

Obter instância de coleção

O MongoClient.Db.collection obtém uma referência a uma coleção.

// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);

Instâncias encadeadas

Você pode encadear o cliente, o banco de dados e a coleção juntos. O encadeamento é mais conveniente se você precisar acessar vários bancos de dados ou coleções.

const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)

Crie um índice

Use o Collection.createIndex para criar um índice nas propriedades do documento que você pretende usar para classificar com o método FindCursor.sort do MongoDB.

// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);

Criar um documento

Crie um documento com as propriedades product para o banco de dados adventureworks:

• Uma propriedade _id para o identificador exclusivo do produto.
• Uma propriedade de categoria. Essa propriedade pode ser usada como a chave de partição lógica.
• Uma propriedade de nome.
• Uma propriedade de quantidade de estoque.
• Uma propriedade de venda, indicando se o produto está à venda.

// Create new doc and upsert (create or replace) to collection
const product = {
    category: "gear-surf-surfboards",
    name: `Yamba Surfboard-${random}`,
    quantity: 12,
    sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};

// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);

// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);

Crie um documento na coleção chamando Collection.UpdateOne. Neste exemplo, optamos por executar upsert em vez de criar um item caso você execute esse código de exemplo mais de uma vez.

Obter um documento

No Azure Cosmos DB, é possível executar uma operação de leitura de ponto menos cara usando o identificador exclusivo (_id) e a chave de partição (category).

// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding,    should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
    _id: ObjectId(upsertResult1.upsertedId), 
    category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);

Consultar documentos

Depois de inserir um documento, é possível executar uma consulta para obter todos os documentos que correspondem a um filtro específico. Este exemplo localiza todos os documentos que correspondem a uma categoria específica: gear-surf-surfboards. Depois que a consulta for definida, chame Collection.find para obter um resultado FindCursor. Converta o cursor em uma matriz para usar métodos de matriz JavaScript.

// select all from product category
const allProductsQuery = { 
    category: "gear-surf-surfboards" 
};

// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));

Solucionar problemas:

• Se você receber um erro como The index path corresponding to the specified order-by item is excluded., verifique se o índice foi criado.

Executar o código

Esse aplicativo cria um banco de dados e uma coleção para a API do MongoDB, cria um documento e lê exatamente o mesmo documento novamente. Por fim, o exemplo emite uma consulta que só deve retornar esse único documento. A cada etapa, o exemplo gera informações para o console sobre as etapas executadas.

Para executar o aplicativo, use um terminal para navegar até o diretório do aplicativo e execute o aplicativo.

node index.js

A saída do aplicativo deve ser semelhante a este exemplo:

New database:   adventureworks

New collection: products

upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}

upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}

foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}

indexResult: "name_1"

1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done

Limpar os recursos

Quando a conta do Azure Cosmos DB for MongoDB não for mais necessária, exclua o grupo de recursos correspondente a ela.

az group delete --name $resourceGroupName

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Próximas etapas

Neste guia de início rápido, você aprendeu a criar uma conta do Azure Cosmos DB for MongoDB, um banco de dados e uma coleção usando o driver do MongoDB. Agora você pode se aprofundar no Azure Cosmos DB for MongoDB para importar mais dados, realizar consultas complexas e gerenciar recursos do Azure Cosmos DB for MongoDB.