Introdução ao Azure Cosmos DB for MongoDB usando JavaScript

  • Artigo

APLICA-SE AO: MongoDB

Este artigo mostra como se conectar ao Azure Cosmos DB for MongoDB usando o pacote npm do MongoDB nativo. Depois de conectado, você poderá executar operações em bancos de dados, coleções e documentos.

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 (npm)

Pré-requisitos

Criar um aplicativo JavaScript

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

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

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

    node index.js

Conectar-se ao driver nativo do MongoDB para o Azure Cosmos DB for MongoDB

Para conectar-se ao driver nativo do MongoDB para o Azure Cosmos DB, crie uma instância da classe MongoClient. Essa classe é o ponto de partida para executar todas as operações em bancos de dados.

O construtor mais comum para MongoClient tem dois parâmetros:

Parâmetro Valor de exemplo Descrição
url A variável de ambiente COSMOS_CONNECTION_STRING Cadeia de conexão da API para MongoDB a ser usada para todas as solicitações
options {ssl: true, tls: true, } Opções do MongoDB para a conexão.

Veja o Guia de solução de problemas de conexão.

Obter nome do recurso

  1. Crie uma variável de shell para resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos"

  2. Use o comando az cosmosdb list para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

Recuperar sua cadeia de conexão

  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.

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>"

Criar MongoClient com cadeia de conexão

  1. Adicione dependências para referenciar os pacotes npm do MongoDB e do DotEnv.

    // Read .env file and set environment variables
require('dotenv').config();

// Use official mongodb driver to connect to the server
const { MongoClient } = require('mongodb');

  2. Defina uma nova instância da classe MongoClient usando o construtor e process.env. para usar a cadeia de conexão.

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

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

// client options
const options = client.options
console.log(`Options:\n${Object.keys(options).map(key => `\t${key}: ${options[key]}\n`)}`);

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

Fechar a conexão do MongoClient

Quando o aplicativo for concluído com a conexão, lembre-se de fechá-lo. A chamada .close() deve ser depois que todas as chamadas ao banco de dados forem feitas.

client.close()

Usar classes do cliente do MongoDB com a API do Azure Cosmos DB para MongoDB

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.

Diagrama da hierarquia de banco de dados do Azure Cosmos DB, incluindo contas, bancos de dados, coleções e documentos.

Cada tipo de recurso é representado por um ou mais classes associadas do JavaScript. Aqui está uma lista das classes mais comuns:

Classe Descrição
MongoClient Esta classe fornece a representação lógica do lado do cliente da camada da API para 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 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.

Os guias a seguir mostram como usar cada uma dessas classes para compilar seu aplicativo.

Guia:

Confira também

Próximas etapas

Agora que você se conectou a uma conta da API para MongoDB, use o próximo guia para criar e gerenciar bancos de dados.

Criar um banco de dados no Azure Cosmos DB for MongoDB usando JavaScript