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

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

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.

1. Abra um terminal no diretório raiz do projeto.

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

3. 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á.

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

5. Implante a conta do Azure Cosmos DB usando azd upo . Os modelos Bicep também implantam um aplicativo Web de exemplo.

   azd up
   

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

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

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

1. Crie um requirements.txt arquivo no diretório do seu aplicativo que liste os pacotes PyMongo e python-dotenv .

   # requirements.txt
   pymongo
   python-dotenv
   

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

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.

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.

Exemplos de código

• Autenticar o cliente
• Obter base de dados
• Obter coleção
• Criar um índice
• Criar um documento
• Obter um documento
• Consultar documentos

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

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

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

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

az group delete --name $resourceGroupName

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