Compartilhar via

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

  • Artigo

APLICA-SE AO: MongoDB

Introdução ao pacote do PyMongo para criar bancos de dados, coleções e documentos no seu recurso do Azure Cosmos DB. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Observação

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

Neste guia de início rápido, você 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. Além disso, você usará os comandos de extensão do MongoDB, que foram projetados para ajudar você a criar e obter recursos de banco de dados específicos do modelo de capacidade do Azure Cosmos DB.

Pré-requisitos

Verificação de pré-requisitos

  • Em um terminal ou em uma janela de comando, execute python --version para verificar se você tem uma versão recente do Python.
  • Execute az --version (CLI do Azure) ou Get-Module -ListAvailable Az* (Azure PowerShell) para verificar se você tem as ferramentas de linha de comando do Azure apropriadas instaladas.

Configurando

Esta seção aborda a criação de uma conta do Azure Cosmos DB e a configuração de um projeto que usa o pacote npm do MongoDB.

Criar uma conta do Azure Cosmos DB

Este guia de início rápido criará uma só conta do Azure Cosmos DB usando a API do MongoDB.

  1. Crie variáveis em shell para accountName, resourceGroupName e localização.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-quickstart-rg"
location="westus"

# Variable for account name with a randomnly generated suffix
let suffix=$RANDOM*$RANDOM
accountName="msdocs-$suffix"

  2. Caso ainda não tenha feito isso, entre na CLI do Azure usando o comando az login.

  3. Use o comando az group create para criar um grupo de recursos na assinatura.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. Use o comando az cosmosdb create para criar uma conta do Azure Cosmos DB for MongoDB com configurações padrão.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --kind MongoDB

Obter cadeia de conexão do MongoDB

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

  2. Copie os valores de PRIMARY KEY. Você usará essas credenciais mais tarde.

Criar um aplicativo Python

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

  2. Crie um arquivo requirements.txt que lista os pacotes PyMongo e python-dotenv.

    # requirements.txt
pymongo
python-dotenv

  3. Crie um ambiente virtual e instale os pacotes.

    # 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

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

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.

Exemplos de código

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

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

  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 as constantes que você usará no código.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Conectar-se à API do Azure Cosmos DB for 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