Guia de início rápido: Azure Cosmos DB for MongoDB para Python com o driver do MongoDB

Artigo
08/15/2024

APLICA-SE AO: MongoDB

Introdução ao uso do MongoDB para criar bancos de dados, coleções e documentos no recurso do Azure Cosmos DB. Siga estas etapas para implantar uma solução mínima no seu ambiente usando o Azure Developer CLI.

Documentação de referência da API para MongoDB | pacote pymongo | Azure Developer CLI

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Conta do GitHub

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
CLI do Desenvolvedor do Azure
Docker Desktop

Configurando

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

Importante

As contas do GitHub incluem um direito a horas de armazenamento e núcleo sem nenhum custo. Para obter mais informações, confira Horas de armazenamento e núcleo incluídas nas contas do GitHub.

Abra um terminal no diretório raiz do projeto.
Autentique-se no Azure Developer CLI usando azd auth login. Siga as etapas especificadas pela ferramenta para se autenticar na CLI usando suas credenciais preferenciais do Azure.
```
azd auth login
```
Execute azd init para inicializar o projeto.
```
azd init --template cosmos-db-mongodb-python-quickstart
```
Observação

Este início rápido usa o repositório GitHub do modelo azure-samples/cosmos-db-mongodb-python-quickstart. A Azure Developer CLI clona automaticamente esse projeto em seu computador se ele ainda não estiver lá.
Durante a inicialização, configure um nome de ambiente exclusivo.

Dica

O nome do ambiente também será usado como o nome do grupo de recursos de destino. Neste início rápido, considere o uso de msdocs-cosmos-db.
Implante a conta do Azure Cosmos DB usando azd up. Os modelos do Bicep também implantam um aplicativo Web de exemplo.
```
azd up
```
Durante o processo de provisionamento, selecione sua assinatura e o local desejado. Aguarde o processo de provisionamento ser concluído. O processo pode levar aproximadamente cinco minutos.

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.

Use a URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

Instalar a biblioteca de clientes

Crie um arquivo requirements.txt no diretório do aplicativo que lista os pacotes PyMongo e python-dotenv.
```
# 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

Modelo de objeto

Vamos dar uma olhada na hierarquia de recursos na API for MongoDB e no modelo de objeto usado para criar e acessar esses recursos. O Azure Cosmos DB cria recursos em uma hierarquia que consiste em contas, bancos de dados, contêineres e documentos.

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

Cada tipo de recurso é representado por uma classe Python. Aqui estão as 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.

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. O código de exemplo completo está em https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

Para as etapas abaixo, o banco de dados não usará a fragmentação e mostrará um aplicativo síncrono usando o driver do PyMongo. Para os aplicativos assíncronos, use o driver do Motor.

Autenticar o cliente

No diretório do projeto, crie um arquivo run.py. No editor, adicione instruções require para referenciar os pacotes que você usará, incluindo os pacotes do PyMongo e python-dotenv.
```
import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv
```
Obtenha as informações de conexão da variável de ambiente definida em um arquivo .env.
```
load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
```

Defina as constantes que você usará no código.

DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Conectar-se à API do Azure Cosmos DB para MongoDB

Use o método MongoClient para se conectar ao recurso do Azure Cosmos DB for MongoDB. O método conectar retorna uma referência ao banco de dados.

client = pymongo.MongoClient(CONNECTION_STRING)

Obter banco de dados

Verifique se o banco de dados existe com o método list_database_names. Se o banco de dados não existir, use o comando create database extension para criá-lo com uma taxa de transferência provisionada especificada.

# Create database if it doesn't exist
db = client[DB_NAME]
if DB_NAME not in client.list_database_names():
    # Create a database with 400 RU throughput that can be shared across
    # the DB's collections
    db.command({"customAction": "CreateDatabase", "offerThroughput": 400})
    print("Created db '{}' with shared throughput.\n".format(DB_NAME))
else:
    print("Using database: '{}'.\n".format(DB_NAME))

Obter coleção

Verifique se a coleção existe com o método list_collection_names. Se a coleção não existir, use o comando create collection extension para criá-la.

# Create collection if it doesn't exist
collection = db[COLLECTION_NAME]
if COLLECTION_NAME not in db.list_collection_names():
    # Creates a unsharded collection that uses the DBs shared throughput
    db.command(
        {"customAction": "CreateCollection", "collection": COLLECTION_NAME}
    )
    print("Created collection '{}'.\n".format(COLLECTION_NAME))
else:
    print("Using collection: '{}'.\n".format(COLLECTION_NAME))

Crie um índice

Crie um índice usando o comando update collection extension. Você também pode definir o índice no comando create collection extension. Defina o índice como a propriedade name neste exemplo para que você possa classificá-lo posteriormente com o método sort de classe de cursor no nome do produto.

indexes = [
    {"key": {"_id": 1}, "name": "_id_1"},
    {"key": {"name": 2}, "name": "_id_2"},
]
db.command(
    {
        "customAction": "UpdateCollection",
        "collection": COLLECTION_NAME,
        "indexes": indexes,
    }
)
print("Indexes are: {}\n".format(sorted(collection.index_information())))

Criar um documento

Crie um documento com as propriedades product para o banco de dados adventureworks:

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 document and upsert (create or replace) to collection"""
product = {
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard-{}".format(randint(50, 5000)),
    "quantity": 1,
    "sale": False,
}
result = collection.update_one(
    {"name": product["name"]}, {"$set": product}, upsert=True
)
print("Upserted document with _id {}\n".format(result.upserted_id))

Crie um documento na coleção chamando a operação de nível de coleção update_one. Neste exemplo, você fará upsert em vez de criar um documento. O upsert não é necessário neste exemplo porque o nome do produto é aleatório. No entanto, é uma boa prática fazer upsert caso você execute o código mais de uma vez e o nome do produto seja o mesmo.

O resultado da operação update_one contém o valor do campo _id que você pode usar em operações posteriores. A propriedade _id foi criada automaticamente.

Obter um documento

Use o método find_one para obter um documento.

doc = collection.find_one({"_id": result.upserted_id})
print("Found a document with _id {}: {}\n".format(result.upserted_id, doc))

No Azure Cosmos DB, é possível executar uma operação de leitura de ponto menos cara usando o identificador exclusivo (_id) e uma chave de partição.

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 Cursor e use sort.

"""Query for documents in the collection"""
print("Products with category 'gear-surf-surfboards':\n")
allProductsQuery = {"category": "gear-surf-surfboards"}
for doc in collection.find(allProductsQuery).sort(
    "name", pymongo.ASCENDING
):
    print("Found a product with _id {}: {}\n".format(doc["_id"], doc))

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 da API for MongoDB, cria um documento e lê exatamente o mesmo documento de novo. Por fim, o exemplo emite uma consulta que retorna os documentos que correspondem a uma categoria de produto especificada. 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.

python run.py

A saída do aplicativo deve ser semelhante a este exemplo:


Created db 'adventureworks' with shared throughput.

Created collection 'products'.

Indexes are: ['_id_', 'name_1']

Upserted document with _id <ID>

Found a document with _id <ID>:
{'_id': <ID>,
'category': 'gear-surf-surfboards',
'name': 'Yamba Surfboard-50',
'quantity': 1,
'sale': False}

Products with category 'gear-surf-surfboards':

Found a product with _id <ID>:
{'_id': ObjectId('<ID>'),
'name': 'Yamba Surfboard-386',
'category': 'gear-surf-surfboards',
'quantity': 1,
'sale': False}

Limpar os recursos

Quando a conta do Azure Cosmos DB for NoSQL 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

Use o Remove-AzResourceGroup cmdlet para excluir o grupo de recursos.

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

Compartilhar via