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

  • Artigo

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.

Observação

Os snippets de código de exemplo estão disponíveis no GitHub como um projeto JavaScript.

Documentação de referência da API for MongoDB | Pacote do MongoDB (NuGet)

Pré-requisitos

Verificação de pré-requisitos

  • Em uma janela de terminal ou de comando, execute node --version para verificar se o Node.js tem uma das versões de LTS.
  • Execute az --version (CLI do Azure) ou Get-Module -ListAvailable AzureRM (Azure PowerShell) para verificar se você tem as ferramentas de linha de comando do Azure apropriadas instaladas.

Configurando

Esta seção aborda a criação de uma conta do Azure Cosmos DB e a configuração de um projeto que usa o pacote npm do MongoDB.

Criar uma conta do Azure Cosmos DB

Este guia de início rápido criará uma só conta do Azure Cosmos DB usando a API do MongoDB.

  1. Crie variáveis em shell para accountName, resourceGroupName e localização.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-quickstart-rg"
location="westus"

# Variable for account name with a randomnly generated suffix
let suffix=$RANDOM*$RANDOM
accountName="msdocs-$suffix"

  2. Caso ainda não tenha feito isso, entre na CLI do Azure usando o comando az login.

  3. Use o comando az group create para criar um grupo de recursos na assinatura.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. Use o comando az cosmosdb create para criar uma conta do Azure Cosmos DB for MongoDB com configurações padrão.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --kind MongoDB

Obter cadeia de conexão do MongoDB

  1. Localize a cadeia de conexão da API do MongoDB na lista de cadeias de conexão da conta com o comando az cosmosdb keys list.

    az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. Copie os valores de PRIMARY KEY. Você usará essas credenciais mais tarde.

Criar um aplicativo JavaScript

Crie um aplicativo JavaScript em uma pasta vazia usando seu terminal de preferência. Use o comando npm init para iniciar os prompts para criar o arquivo package.json. Aceite os padrões para os prompts.

npm init

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

Configurar variáveis de ambiente

Para usar os valores de CONNECTION STRING no código, defina esse valor no ambiente local que executa o aplicativo. Para definir a variável de ambiente, use seu terminal preferido para executar os seguintes comandos:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

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.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

Você usará 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 - 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 executa uma operação nele.
  • 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

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.

Nesse procedimento, o banco de dados não usará 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.

Use o az group delete comando para excluir o grupo de recursos.

az group delete --name $resourceGroupName

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.

Migrar o MongoDB para o Azure Cosmos DB for MongoDB offline