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

Artigo
08/15/2024

APLICA-SE A: MongoDB

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

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

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Conta do GitHub

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
CLI do desenvolvedor do Azure
Área de trabalho do Docker

Configuração

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

Importante

As contas do GitHub incluem um direito de armazenamento e horas essenciais sem nenhum custo. Para obter mais informações, consulte armazenamento incluído e horas principais para contas do GitHub.

Abra um terminal no diretório raiz do projeto.
Autentique-se na CLI do Desenvolvedor do Azure usando azd auth logino . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.
```
azd auth login
```
Use azd init para inicializar o projeto.
```
azd init --template cosmos-db-mongodb-python-quickstart
```
Nota

Este guia de início rápido usa o repositório GitHub azure-samples/cosmos-db-mongodb-python-quickstart . A CLI do Desenvolvedor do Azure clona automaticamente esse projeto para sua máquina se ela ainda não estiver lá.
Durante a inicialização, configure um nome de ambiente exclusivo.

Gorjeta

O nome do ambiente também será usado como o nome do grupo de recursos de destino. Para este guia de início rápido, considere usar msdocs-cosmos-dbo .
Implante a conta do Azure Cosmos DB usando azd upo . Os modelos Bicep também implantam um aplicativo Web de exemplo.
```
azd up
```
Durante o processo de provisionamento, selecione sua assinatura e o local desejado. Aguarde a conclusão do processo de provisionamento. 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 o URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

Instalar a biblioteca de cliente

Crie um requirements.txt arquivo no diretório do seu aplicativo que liste 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 examinar a hierarquia de recursos na API do MongoDB e o 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, coleções 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. 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.

O código de exemplo descrito neste artigo cria um banco de dados nomeado adventureworks com uma coleção chamada products. A products coleção 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á fragmentação e mostra um aplicativo síncrono usando o driver PyMongo . Para aplicações assíncronas, use o driver do motor .

Autenticar o cliente

No diretório do projeto, crie um arquivo run.py . No seu editor, adicione instruções require aos pacotes de referência que você usará, incluindo os pacotes 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 constantes que você usará no código.

DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Conectar-se à API do Azure Cosmos DB para MongoDB

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

client = pymongo.MongoClient(CONNECTION_STRING)

Obter base de dados

Verifique se o banco de dados existe com list_database_names método. 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))

Criar um índice

Crie um índice usando o comando update collection extension. Você também pode definir o índice no comando create collection extension. Defina a propriedade index to name neste exemplo para que você possa classificar posteriormente com o método de classificação 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 do produto para o adventureworks banco de dados:

Uma propriedade de categoria . Esta propriedade pode ser usada como a chave de partição lógica.
Uma propriedade name .
Uma propriedade de quantidade de inventário.
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ê atualizará em vez de criar um novo documento. 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 contém o update_one _id valor de campo que você pode usar em operações subsequentes. 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, você pode executar uma operação de leitura pontual menos dispendiosa usando o identificador exclusivo (_id) e uma chave de partição.

Consultar documentos

Depois de inserir um documento, você pode 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 estiver definida, ligue Collection.find para obter um Cursor resultado e, em seguida, use a classificação.

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

Resolução de problemas:

Se você receber um erro como The index path corresponding to the specified order-by item is excluded., certifique-se de ter criado o índice.

Executar o código

Este aplicativo cria uma API para banco de dados e coleção MongoDB e cria um documento e, em seguida, lê exatamente o mesmo documento de volta. Finalmente, o exemplo emite uma consulta que retorna documentos que correspondem a uma categoria de produto especificada. Com cada etapa, o exemplo envia 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 executar 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}

Clean up resources (Limpar recursos)

Quando não precisar mais da conta do Azure Cosmos DB para NoSQL, você poderá excluir o grupo de recursos correspondente.

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

Partilhar via