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

  • Artigo

APLICA-SE A: MongoDB

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

Nota

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

Neste início rápido, você se comunicará com a API do Azure Cosmos DB para MongoDB usando um dos drivers de cliente MongoDB de código aberto para Python, PyMongo. Além disso, você usará os comandos de extensão do MongoDB, que são projetados para ajudá-lo a criar e obter recursos de banco de dados específicos para o modelo de capacidade do Azure Cosmos DB.

Pré-requisitos

Verificação de pré-requisitos

  • Em um terminal ou 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 apropriadas do Azure instaladas.

Configuração

Esta seção orienta você na criação de uma conta do Azure Cosmos DB e na configuração de um projeto que usa o pacote npm do MongoDB.

Criar uma conta do Azure Cosmos DB

Este início rápido criará uma única conta do Azure Cosmos DB usando a API para MongoDB.

  1. Crie variáveis de shell para accountName, resourceGroupName e location.

    # 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. Se ainda não o fez, entre na CLI do Azure usando o az login comando.

  3. Use o az group create comando para criar um novo grupo de recursos em sua assinatura.

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

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

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

Obter a cadeia de ligação do MongoDB

  1. Encontre a API para a cadeia de conexão do MongoDB na lista de cadeias de conexão da conta com o az cosmosdb keys list comando.

    az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. Registre os valores de CHAVE PRIMÁRIA . Você usará essas credenciais mais tarde.

Criar um novo aplicativo Python

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

    Nota

    Se você quiser apenas o código concluído, baixe ou bifurque e clone o repositório de trechos de código de exemplo que tem o exemplo completo. Você também git clone pode usar o repositório no Azure Cloud Shell para percorrer as etapas mostradas neste início rápido.

  2. Crie um arquivo requirements.txt que liste 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 CONNECTION STRING dentro do seu 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 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.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

Cada tipo de recurso é representado por uma classe Python. Aqui estão as classes mais comuns:

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

Exemplos de código

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

Resolva os 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 comando para excluir o az group delete grupo de recursos.

az group delete --name $resourceGroupName