Início rápido: Use o Azure DocumentDB com o driver MongoDB para Python

Neste quickstart, crias uma aplicação básica do Azure DocumentDB usando Python. O Azure DocumentDB é um armazenamento de dados NoSQL que permite às aplicações armazenar documentos na cloud e aceder a eles usando drivers oficiais do MongoDB. Este guia mostra como criar documentos e realizar tarefas básicas no seu cluster Azure DocumentDB usando Python.

Referência 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 Azure DocumentDB

Para começar, primeiro precisa de criar um cluster Azure DocumentDB, que serve como base para armazenar e gerir os seus dados NoSQL.

Iniciar sessão no portal Azure (https://portal.azure.com).
A partir do menu do portal do Azure ou a partir da Home page, selecione Criar um recurso.
Na página Nova, pesquise e selecione Azure DocumentDB.
Na página Criar cluster Azure DocumentDB e na secção Básicos, selecione a opção Configurar na secção nível do Cluster.
Na página Escalar , configure estas opções e depois selecione Guardar para persistir as alterações no nível do cluster.

Valor

Camada de cluster M30 tier, 2 vCore, 8-GiB RAM

Armazenamento por fragmento 128 GiB

	Valor
Camada de cluster	`M30 tier, 2 vCore, 8-GiB RAM`
Armazenamento por fragmento	`128 GiB`

De volta à secção Básicos , configure as seguintes opções:

	Valor
Subscription	Selecione sua assinatura do Azure
Grupo de recursos	Criar um novo grupo de recursos ou selecionar um grupo de recursos existente
Nome do cluster	Forneça um nome globalmente exclusivo
Localização	Selecione uma região do Azure suportada para a sua subscrição
Versão do MongoDB	Selecione `8.0`
Nome de utilizador de administrador	Crie um nome de utilizador para aceder ao cluster como administrador de utilizadores
Senha	Use uma palavra-passe única associada ao nome de utilizador

Captura de ecrã a mostrar parâmetros do cluster.

Sugestão

Regista os valores que usas como nome de utilizador e palavra-passe. Estes valores são usados mais adiante neste guia. Para mais informações sobre valores válidos, consulte limitações de cluster.

Selecionar Seguinte: Rede.

Na secção de regras de firewall no separador Rede , configure estas opções:

	Valor
Método de conectividade	`Public access`
Permitir o acesso público dos serviços e recursos Azure dentro do Azure para este cluster	Ativado

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

Sugestão

Em muitos ambientes corporativos, os endereços IP da máquina do desenvolvedor são ocultos devido a uma VPN ou outras configurações de rede corporativa. Nestes casos, pode permitir temporariamente o acesso a todos os endereços IP adicionando o intervalo 0.0.0.0 - 255.255.255.255 de endereços IP como uma regra de firewall. Use esta regra do firewall apenas temporariamente como parte dos testes e desenvolvimento de ligações.
Selecione Verificar + criar.
Reveja as definições fornecidas e, em seguida, selecione Criar. A criação do cluster demora alguns minutos. Aguarde que a implementação dos recursos esteja concluída.
Por fim, selecione Ir para recurso para navegar até ao cluster Azure DocumentDB no portal.

Captura de ecrã a mostrar as opções para aceder ao recurso.

Obter credenciais de cluster

Obtenha as credenciais que usa para se ligar ao cluster.

Na página do cluster, selecione a opção Cadeias de Conexão no menu dos recursos.
Na secção Strings de Ligação, copie ou grave o valor do campo String de Ligação.

Captura de ecrã mostrando a opção de cadeias de ligação.

Importante

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

Inicializar o projeto

Crie um novo projeto Python e crie um ambiente virtual no seu diretório atual.

Comece 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 cliente

A biblioteca cliente está disponível através do PyPI, como pacote pymongo .

Instala o driver Python do MongoDB usando pip.
```
pip install pymongo
```
Crie um novo ficheiro Python com o nome main.py do código da sua aplicação.

Importa os módulos necessários para o código da tua aplicação:

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 nesta aplicação liga-se a uma base de dados nomeada adventureworks e a uma coleção chamada products. A products coleção contém detalhes como nome, categoria, quantidade, um identificador único e uma bandeira de venda para cada produto. Os exemplos de código aqui realizam as operações mais comuns ao trabalhar com uma coleção.

Autenticar o cliente

Primeiro, ligue-se ao cliente usando uma cadeia de ligação básica.

Cria a função principal e configura a cadeia de ligação. Substitua <your-cluster-name>, <your-username>, e <your-password> pela informação real 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)

Liga-te ao cliente MongoDB e verifica a ligação.

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

Obtenha uma coleção

Agora, obtenha a sua base de dados e coleção. Se a base de dados e a coleção ainda não existirem, use o driver para criar isso automaticamente para si.

Pede uma referência para a base de dados.

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

Obtenha uma referência para a coleção dentro da base de dados.

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

Criar um documento

Depois, crie alguns novos documentos na sua coleção. Atualize os documentos para garantir que substituem quaisquer documentos existentes, caso já existam com o mesmo identificador único.

Crie exemplos de documentos de produtos.

        # 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

De seguida, realiza uma operação de leitura pontual para recuperar um documento específico da tua coleção.

Defina o filtro para encontrar 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 múltiplos documentos utilizando a Linguagem de Consulta MongoDB (MQL).

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

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

Itere pelos resultados para mostrar 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()

Explore os seus dados usando o Visual Studio Code

Utilize a extensão DocumentDB no Visual Studio Code para realizar operações centrais na base de dados, incluindo consultas, inserção, atualização e eliminação de dados.

Abra o Visual Studio Code.
Navegue até à vista Extensões e pesquise o termo DocumentDB. Localize a extensão DocumentDB para VS Code.
Selecione o botão Instalar para a extensão. Aguarde a conclusão da instalação. Recarregue o Visual Studio Code, se pedido.
Navegue até à extensão DocumentDB selecionando o ícone correspondente na Barra de Atividade.
No painel de Ligações do DocumentDB , selecione + Nova Ligação....
No diálogo, selecione Descoberta de Serviços e depois Azure DocumentDB - Azure Descoberta de Serviços.
Selecione a sua subscrição Azure e o seu cluster Azure DocumentDB recém-criado.

Sugestão

Em muitos ambientes corporativos, os endereços IP da máquina do desenvolvedor são ocultos devido a uma VPN ou outras configurações de rede corporativa. Nestes casos, pode permitir temporariamente o acesso a todos os endereços IP adicionando o intervalo 0.0.0.0 - 255.255.255.255 de endereços IP como uma regra de firewall. Use esta regra do firewall apenas temporariamente como parte dos testes e desenvolvimento de ligações. Para obter mais informações, consulte Configurar firewall.
De volta ao painel de Conexões do DocumentDB , expanda o nó do seu cluster e navegue até aos nós existentes de documentos e coleções.
Abra o menu contextual da coleção e depois selecione DocumentDB Scrapbook > New DocumentDB Scrapbook.
Insira os seguintes comandos da Linguagem de Consulta MongoDB (MQL) e depois selecione Executar Tudo. Observe a saída dos comandos.
```
db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)
```

Limpeza de recursos

Quando terminares com o cluster Azure DocumentDB, podes eliminar os recursos Azure que criaste para não incorreres em mais encargos.

Na barra de pesquisa do portal do Azure, procure e selecione Grupos de recursos.
Na lista, selecione o grupo de recursos usado para este início rápido.
Na página do grupo de recursos, selecione Excluir grupo de recursos.
Na caixa de diálogo de confirmação de exclusão, digite 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