Introdução ao Azure Cosmos DB para MongoDB e Python

Aplica-se a: ✅ MongoDB

APLICA-SE A: MongoDB

Importante

Você está procurando migrar um aplicativo MongoDB existente ou usar os recursos MQL (MongoDB Query Language)? Considere Azure DocumentDB.

Você está procurando uma solução de banco de dados para cenários de alta escala com um contrato de nível de serviço (SLA) de disponibilidade de 99.999%, dimensionamento automático instantâneo e failover automático em várias regiões? Considere Azure Cosmos DB para NoSQL.

Este artigo mostra como se conectar ao Azure Cosmos DB para MongoDB usando o pacote de driver PyMongo. Uma vez conectado, você pode executar operações em bancos de dados, coleções e documentos.

Nota

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

Este artigo mostra como se comunicar com a API do Azure Cosmos DB para MongoDB usando um dos drivers de cliente MongoDB de código aberto para Python, PyMongo.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Python 3.8+
Interface de Linha de Comando (CLI) do Azure ou Azure PowerShell
Recurso do Azure Cosmos DB para MongoDB

Criar um novo aplicativo Python

Crie uma nova pasta vazia usando seu terminal preferido e altere o diretório para a pasta.

Nota

Se quiser apenas o código concluído, faça um fork e clone o repositório de trechos de código de exemplo que inclui o exemplo completo. Você pode também usar git clone o repositório no Azure Cloud Shell para percorrer os passos apresentados neste guia prático.
Crie um arquivo requirements.txt que liste os pacotes PyMongo e python-dotenv . O dotenv pacote é usado para ler as variáveis de ambiente de um .env arquivo durante o desenvolvimento local.
```
# requirements.txt
pymongo
python-dotenv
```

Crie um ambiente virtual e instale os pacotes.

Windows
Linux / macOS

# py -3 uses the global python interpreter. You can also use python3 -m venv .venv.
py -3 -m venv .venv
source .venv/Scripts/activate   
pip install -r requirements.txt

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Conecte-se com o driver PyMongo ao Azure Cosmos DB para MongoDB

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

O construtor mais comum para MongoClient requer apenas o host parâmetro, que neste artigo é definido como a COSMOS_CONNECTION_STRING variável de ambiente. Há outros parâmetros opcionais e parâmetros de palavra-chave que você pode usar no construtor. Muitos dos parâmetros opcionais também podem ser especificados com o host parâmetro. Se a mesma opção for passada com host e como parâmetro, o parâmetro terá precedência.

Consulte o Guia de solução de problemas para problemas de conexão.

Obter nome do recurso

Nos comandos abaixo, mostramos msdocs-cosmos como o nome do grupo de recursos. Altere o nome conforme apropriado para a sua situação.

Crie uma variável de shell para resourceGroupName.

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

Use o comando az cosmosdb list para recuperar o nome da primeira conta do Azure Cosmos DB no 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
)

Crie uma variável de shell para RESOURCE_GROUP_NAME.

# Variable for resource group name
$RESOURCE_GROUP_NAME = "msdocs-cosmos"

Use o cmdlet Get-AzCosmosDBAccountKey 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.
```
# Get the name of the first Azure Cosmos DB account in your resource group
$ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
```

Obter a cadeia de ligação

Encontre 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 
```
Registre os valores de CHAVE PRIMÁRIA . Você usará essas credenciais mais tarde.

Encontre a CADEIA DE CONEXÃO na lista de chaves e cadeias de conexão da conta com o Get-AzCosmosDBAccountKey cmdlet.

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary MongoDB Connection String"

Anote o CONNECTION STRING. Você usará essas credenciais mais tarde.

Configurar variáveis de ambiente

Para usar os valores CONNECTION STRING dentro do seu 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>"

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Um .env arquivo é uma maneira padrão de armazenar variáveis de ambiente em um projeto. Crie um .env arquivo na raiz do seu projeto. Adicione as seguintes linhas ao .env ficheiro:

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Criar MongoClient com cadeia de conexão

Adicione dependências para fazer referência aos pacotes PyMongo e python-dotenv .
```
import os
import sys

import pymongo
from dotenv import load_dotenv
```

Defina uma nova instância da classe MongoClient usando o construtor e a cadeia de conexão lida de uma variável de ambiente.

load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
client = pymongo.MongoClient(CONNECTION_STRING)

for prop, value in vars(client.options).items():
    print("Property: {}: Value: {} ".format(prop, value))

Para obter mais informações sobre diferentes maneiras de criar uma MongoClient instância, consulte Fazendo uma conexão com MongoClient.

Feche a conexão MongoClient

Quando o aplicativo terminar a conexão, lembre-se de fechá-lo. Essa .close() chamada deve ser feita depois de serem feitas todas as chamadas de banco de dados.

client.close()

Usar classes cliente do MongoDB com o Azure Cosmos DB para a API do 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 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.

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

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

MongoClient - A primeira etapa ao trabalhar com o PyMongo é criar um MongoClient para se conectar à API do Azure Cosmos DB para MongoDB. O objeto cliente é usado para configurar e executar solicitações no serviço.
Banco de dados - A API do Azure Cosmos DB para MongoDB pode dar suporte a um ou mais bancos de dados independentes.
Coleção - Um banco de dados pode conter uma ou mais coleções. Uma coleção é um grupo de documentos armazenados no MongoDB, e pode ser pensado como aproximadamente o equivalente a uma tabela em um banco de dados relacional.
Documento - Um documento é um conjunto de pares chave-valor. Os documentos têm esquema dinâmico. Esquema dinâmico significa que os documentos na mesma coleção não precisam ter o mesmo conjunto de campos ou estrutura. E os campos comuns nos documentos de uma coleção podem conter diferentes tipos de dados.

Para saber mais sobre a hierarquia de entidades, consulte o artigo Modelo de recursos do Azure Cosmos DB.

Consulte também

Próximos passos

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

Criar um banco de dados no Azure Cosmos DB para MongoDB usando Python

Comentários

Esta página foi útil?

Last updated on 2026-02-27