Guia de início rápido: driver do Azure Cosmos DB para MongoDB para Node.js

APLICA-SE A: MongoDB

Comece com o pacote npm do MongoDB para criar bancos de dados, coleções e documentos em seu 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 Pacotes do pacote MongoDB (NuGet) /Microsoft.Azure.Cosmos) | CLI do desenvolvedor do Azure

Pré-requisitos

Configuração

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

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

2. Autentique-se na CLI do Desenvolvedor do Azure usando azd auth logino . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.

   azd auth login
   

3. Use azd init para inicializar o projeto.

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

   Nota

   Este guia de início rápido usa o repositório GitHub azure-samples/cosmos-db-mongodb-nodejs-quickstart . A CLI do Desenvolvedor do Azure clonará automaticamente esse projeto para sua máquina se ela ainda não estiver lá.

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

   Gorjeta

   O nome do ambiente também será usado como o nome do grupo de recursos de destino. Para este guia de início rápido, considere usar msdocs-cosmos-dbo .

5. Implante a conta do Azure Cosmos DB usando azd upo . Os modelos 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 a conclusão do processo de provisionamento. 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 o 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 npm install package comando especificando o nome do pacote npm. O dotenv pacote é usado para ler as variáveis de ambiente de um .env arquivo 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 usado para criar e acessar recursos. O Azure Cosmos DB cria recursos em uma hierarquia que consiste em contas, bancos de dados, coleções e documentos.

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

• MongoClient - Esta classe fornece uma representação lógica do lado do cliente para a camada API for MongoDB no Azure Cosmos DB. O objeto cliente é usado para configurar e executar solicitações no serviço.
• Db - Esta classe é uma referência a um banco de dados que pode, ou não, existir no serviço ainda. O banco de dados é validado no lado do servidor quando você tenta acessá-lo ou executar uma operação em relação a ele.
• Collection - Esta classe é uma referência a uma coleção que também pode não existir no serviço ainda. 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 coleta
• Usar métodos encadeados
• Criar um índice
• Criar um documento
• Obter um documento
• Executar consultas

O código de exemplo descrito neste artigo cria um banco de dados nomeado adventureworks com uma coleção chamada products. A products coleção 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.

Para este 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, add requer instruções para fazer referência aos pacotes npm MongoDB e 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 usando o construtor e process.env. leia a variável de MongoClient, ambiente criada anteriormente.

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

Para obter mais informações sobre diferentes maneiras de criar uma MongoClient instância, consulte MongoDB NodeJS Driver Quick Start.

Configurar operações assíncronas

index.js No arquivo, 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 trechos de código a seguir devem ser adicionados à função principal para manipular a sintaxe async/await.

Ligue-se à base de dados

Use o MongoClient.connect método para se conectar ao seu recurso do Azure Cosmos DB for MongoDB. O método connect 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 obtém 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 coleta

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

Criar um índice

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

// 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 do produto para o adventureworks banco de dados:

• Uma propriedade _id para o identificador exclusivo do produto.
• Uma propriedade de categoria . Esta propriedade pode ser usada como a chave de partição lógica.
• Uma propriedade name .
• Uma propriedade de quantidade de inventário.
• 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 upsert em vez de criar um novo documento caso você execute esse código de exemplo mais de uma vez.

Obter um documento

No Azure Cosmos DB, você pode executar uma operação de leitura pontual menos dispendiosa 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, você pode 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. Uma vez definida a consulta, ligue Collection.find para obter um FindCursor resultado. 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)}`));

Resolução de problemas:

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

Executar o código

Este aplicativo cria uma API para banco de dados e coleção MongoDB e cria um documento e, em seguida, lê exatamente o mesmo documento de volta. Finalmente, o exemplo emite uma consulta que só deve retornar esse único documento. Com cada etapa, o exemplo envia 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 executar 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

Clean up resources (Limpar recursos)

Quando não precisar mais da conta do Azure Cosmos DB para MongoDB, você poderá excluir o grupo de recursos correspondente.

az group delete --name $resourceGroupName

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

Próximos passos

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