Início Rápido: Usar o Azure DocumentDB com o driver do MongoDB para Python

Neste início rápido, você criará um aplicativo básico do Azure DocumentDB usando o Python. O Azure DocumentDB é um armazenamento de dados NoSQL que permite que os aplicativos armazenem documentos na nuvem e os acessem usando drivers oficiais do MongoDB. Este guia mostra como criar documentos e executar tarefas básicas em seu cluster do Azure DocumentDB usando o Python.

Referência de API | Código-fonte | Pacote (PyPI)

Pré-requisitos

Uma assinatura do Azure
- Se você não tiver uma assinatura do Azure, crie uma conta gratuita

Python 3.12 ou posterior

Criar um cluster do Azure DocumentDB

Para começar, primeiro você precisa criar um cluster do Azure DocumentDB, que serve como base para armazenar e gerenciar seus dados NoSQL.

Entre no portal do Azure (https://portal.azure.com).
No menu do portal do Azure ou na Home page, selecione Criar um recurso.
Na página Novo , pesquise e selecione o Azure DocumentDB.
Na página Criar cluster do Azure DocumentDB e na seção Configurações básicas, selecione a opção Configurar na seção Camada Cluster.
Na página Dimensionar , configure essas opções e, em seguida, selecione Salvar para persistir suas alterações na camada de cluster.

Value

Nível do cluster M30 tier, 2 vCore, 8-GiB RAM

Armazenamento por fragmento 128 GiB

	Value
Nível do cluster	`M30 tier, 2 vCore, 8-GiB RAM`
Armazenamento por fragmento	`128 GiB`

De volta à seção Noções básicas , configure as seguintes opções:

	Value
Subscription	Selecione sua Assinatura do Azure.
Grupo de recursos	Crie um novo grupo de recursos ou escolha um grupo de recursos existente
Nome do cluster	Forneça um nome global exclusivo
Localidade	Escolha uma região do Azure compatível com sua assinatura
Versão do MongoDB	Selecione `8.0`
Nome de usuário do administrador	Criar um nome de usuário para acessar o cluster como administrador de usuário
Senha	Usar uma senha exclusiva associada ao nome de usuário

Captura de tela mostrando parâmetros de cluster.

Dica

Registre os valores usados para nome de usuário e senha. Esses valores são usados posteriormente neste guia. Para obter mais informações sobre valores válidos, consulte as limitações do cluster.

Selecione Avançar: Rede.

Na seção Regras de Firewall na guia Rede , configure estas opções:

	Value
Método de conectividade	`Public access`
Permitir acesso público de serviços e recursos do Azure dentro do Azure para esse cluster	Habilitado

Adicione uma regra de firewall para o dispositivo cliente atual para conceder acesso ao cluster selecionando + Adicionar endereço IP do cliente atual.

Dica

Em muitos ambientes corporativos, os endereços IP do computador do desenvolvedor ficam ocultos devido a uma VPN ou outras configurações de rede corporativa. Nesses casos, você pode permitir temporariamente o acesso a todos os endereços IP adicionando o 0.0.0.0 - 255.255.255.255 intervalo de endereços IP como uma regra de firewall. Use essa regra de firewall apenas temporariamente como parte do teste de conexão e do desenvolvimento.
Selecione Examinar + criar.
Examine as configurações fornecidas e selecione Criar. São necessários alguns minutos para criar o cluster. Aguarde a conclusão da implantação do recurso.
Por fim, selecione Ir para o recurso para navegar até o cluster do Azure DocumentDB no portal.

Captura de tela mostrando as opções de recurso goto.

Obter credenciais do cluster

Obtenha as credenciais que você usa para se conectar ao cluster.

Na página do cluster, selecione a opção Cadeias de conexão no menu de recursos.
Na seção Cadeias de conexão , copie ou registre o valor do campo Cadeia de conexão .

Captura de tela mostrando a opção de cadeias de conexão.

Importante

A cadeia de conexão no portal não inclui o valor da senha. Você deve substituir o <password> placeholder pelas credenciais inseridas quando criou o cluster ou inserir a senha de forma interativa.

Inicializar o projeto

Crie um novo projeto do Python e configure um ambiente virtual em seu diretório atual.

Inicie em um diretório vazio.
Abra um terminal no diretório atual.

Crie e ative um ambiente virtual.

python -m venv venv
venv\Scripts\activate

Instalar a biblioteca de clientes

A biblioteca de cliente está disponível por meio do PyPI, como pacote pymongo.

Instale o driver Python do MongoDB usando pip.
```
pip install pymongo
```
Crie um novo arquivo Python nomeado main.py para o código do aplicativo.

Importe os módulos necessários para o código do aplicativo:

from pymongo import MongoClient
from pymongo.errors import ConnectionFailure
import sys

Modelo de objeto

Nome	Description
`MongoClient`	Tipo usado para se conectar ao MongoDB.
`Database`	Representa um banco de dados no cluster.
`Collection`	Representa uma coleção dentro de um banco de dados no cluster.

O código neste aplicativo se conecta a um banco de dados nomeado adventureworks e a uma coleção chamada products. A products coleção contém detalhes como nome, categoria, quantidade, um identificador exclusivo e um sinalizador de venda para cada produto. Os exemplos de código aqui executam as operações mais comuns ao trabalhar com uma coleção.

Autenticar o cliente

Primeiro, conecte-se ao cliente usando uma cadeia de conexão básica.

Crie a função principal e configure a cadeia de conexão. Substitua <your-cluster-name>, <your-username>e <your-password> com suas informações reais do cluster.

def main():
    try:
        # Connection string for Azure DocumentDB cluster
        connection_string = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000"

        # Create a new client and connect to the server
        client = MongoClient(connection_string)

Conecte-se ao cliente MongoDB e verifique a conexão.

        # Ping the server to verify connection
        client.admin.command('ping')
        print("Successfully connected and pinged Azure DocumentDB")

Adquirir uma coleção

Agora, obtenha seu banco de dados e coleção. Se o banco de dados e a coleção ainda não existirem, use o driver para criá-lo automaticamente.

Obtenha uma referência ao banco de dados.

        # Get database reference
        database = client["adventureworks"]
        print(f"Connected to database: {database.name}")

Obtenha uma referência à coleção no banco de dados.

        # Get collection reference
        collection = database["products"]
        print("Connected to collection: products")

Criar um documento

Em seguida, crie alguns documentos novos em sua coleção. Insira ou atualize os documentos para garantir que eles substituam qualquer documento existente se já houver um com o mesmo identificador exclusivo.

Crie documentos de produto de exemplo.

        # Create sample products
        products = [
            {
                "_id": "00000000-0000-0000-0000-000000004018",
                "name": "Windry Mittens",
                "category": "apparel-accessories-gloves-and-mittens",
                "quantity": 121,
                "price": 35.00,
                "sale": False,
            },
            {
                "_id": "00000000-0000-0000-0000-000000004318",
                "name": "Niborio Tent",
                "category": "gear-camp-tents",
                "quantity": 140,
                "price": 420.00,
                "sale": True,
            }
        ]

Insira os documentos usando operações upsert.

        # Insert documents with upsert
        for product in products:
            filter_doc = {"_id": product["_id"]}
            collection.replace_one(filter_doc, product, upsert=True)
            print(f"Upserted product: {product['name']}")

Recuperar um documento

Em seguida, execute uma operação de leitura de ponto para recuperar um documento específico de sua coleção.

Defina o filtro para localizar um documento específico por ID.

        # Retrieve a specific document by ID
        filter_doc = {"_id": "00000000-0000-0000-0000-000000004018"}

Execute a consulta e recupere o resultado.

        retrieved_product = collection.find_one(filter_doc)

        if retrieved_product:
            print(f"Retrieved product: {retrieved_product['name']} - ${retrieved_product['price']}")
        else:
            print("Product not found")

Consultar documentos

Por fim, consulte vários documentos usando a Linguagem de Consulta do MongoDB (MQL).

Defina uma consulta para localizar documentos que correspondam a critérios específicos.

        # Query for products on sale
        sale_filter = {"sale": True}
        sale_products = list(collection.find(sale_filter))

Percorra os resultados para exibir os documentos correspondentes.

        print("Products on sale:")
        for product in sale_products:
            print(f"- {product['name']}: ${product['price']:.2f} (Category: {product['category']})")

    except ConnectionFailure as e:
        print(f"Could not connect to MongoDB: {e}")
        sys.exit(1)
    except Exception as e:
        print(f"An error occurred: {e}")
        sys.exit(1)
    finally:
        client.close()

if __name__ == "__main__":
    main()

Explorar seus dados usando o Visual Studio Code

Use a extensão do DocumentDB no Visual Studio Code para executar operações de banco de dados principais, incluindo consulta, inserção, atualização e exclusão de dados.

Abra o Visual Studio Code.
Navegue até a visualização de Extensões e pesquise o termo DocumentDB. Localize a extensão DocumentDB for VS Code.
Selecione o botão Instalar para a extensão. Aguarde a conclusão da instalação. Recarregue o Visual Studio Code, se for solicitado.
Navegue até a extensão do DocumentDB selecionando o ícone correspondente na Barra de Atividades.
No painel Conexões do DocumentDB , selecione + Nova Conexão....
Na caixa de diálogo, selecione Descoberta de Serviço e, em seguida , Azure DocumentDB – Descoberta de Serviço do Azure.
Selecione sua assinatura do Azure e seu cluster do Azure DocumentDB recém-criado.

Dica

Em muitos ambientes corporativos, os endereços IP do computador do desenvolvedor ficam ocultos devido a uma VPN ou outras configurações de rede corporativa. Nesses casos, você pode permitir temporariamente o acesso a todos os endereços IP adicionando o 0.0.0.0 - 255.255.255.255 intervalo de endereços IP como uma regra de firewall. Use essa regra de firewall apenas temporariamente como parte do teste de conexão e do desenvolvimento. Para obter mais informações, consulte configurar o firewall.
De volta ao painel Conexões do DocumentDB, expanda o nó do seu cluster e navegue até os nós de documento e coleção existentes.
Abra o menu de contexto da coleção e, em seguida, selecione > Novo DocumentDB Scrapbook.
Insira os seguintes comandos MQL (Linguagem de Consulta do MongoDB) e selecione Executar Tudo. Observe a saída dos comandos.
```
db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)
```

Limpar os recursos

Quando terminar de usar o cluster do Azure DocumentDB, você poderá excluir os recursos do Azure criados para não incorrer em mais encargos.

Na barra de pesquisa do portal do Azure, procure e selecione Grupos de recursos.
Na lista, selecione o grupo de recursos criado neste início rápido.
Na página Grupo de recursos, selecione Excluir grupo de recursos.
Na caixa de diálogo de confirmação de exclusão, insira o nome do grupo de recursos para confirmar que você pretende excluí-lo. Por fim, selecione Excluir para excluir permanentemente o grupo de recursos.

O que é o Azure DocumentDB?

Comentários

Esta página foi útil?

Last updated on 2025-11-19