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

Artigo
08/15/2024

APLICA-SE AO: MongoDB

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

Observação

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

Este artigo mostra como se comunicará com a API do Azure Cosmos DB for MongoDB usando um dos drivers de cliente do MongoDB de software livre para o Python, o PyMongo.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Python 3.8+
Interface de linha de comando do Azure (CLI) ou Azure PowerShell
Recurso do Azure Cosmos DB for MongoDB

Criar um aplicativo Python

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

Observação

Caso deseje apenas ter o código concluído, baixe ou crie um fork e clone o repositório de exemplos de snippets de código que tem o exemplo completo. Use também o git clone no Azure Cloud Shell para percorrer as etapas mostradas neste guia de início rápido.
Crie um arquivo requirements.txt que lista os pacotes PyMongo e python-dotenv. O pacote dotenv é usado para ler as variáveis de ambiente de um arquivo .env 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

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

Para conectar-se ao driver do PyMongo para o 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 parâmetro host, que, neste artigo, é definido como a variável de ambiente COSMOS_CONNECTION_STRING. Outros parâmetros opcionais e parâmetros de palavra-chave podem ser usados no construtor. Muitos dos parâmetros opcionais também podem ser especificados com o parâmetro host. Se a mesma opção for passada com host e como um parâmetro, o parâmetro terá precedência.

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

Obter nome do recurso

Nos comandos abaixo, mostramos msdocs-cosmos como o nome do grupo de recursos. Altere o nome de acordo com 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 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
)

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

Recuperar sua cadeia de conexão

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 
```
Copie os valores de PRIMARY KEY. Você usará essas credenciais mais tarde.

Localize CONNECTION STRING na lista de cadeias de conexão e chaves da conta com o cmdlet Get-AzCosmosDBAccountKey.

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

Copie o valor de CONNECTION STRING. 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>"

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

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

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Criar MongoClient com cadeia de conexão

Adicione dependências para referenciar os 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 leitura de cadeia de conexão 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 instância MongoClient, consulte Fazendo uma conexão com o MongoClient.

Fechar a conexão do MongoClient

Quando o aplicativo for concluído com a conexão, lembre-se de fechá-lo. Essa 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 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. Esse objeto do 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 considerada 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 um esquema dinâmico. O esquema dinâmico significa que os documentos na mesma coleção não precisam ter o mesmo conjunto de campos ou estrutura. Além disso, os campos comuns nos documentos de uma coleção podem conter diferentes tipos de dados.

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

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 o Python

Compartilhar via