Introdução ao Azure Cosmos DB para MongoDB e Python

APLICA-SE A: MongoDB

Este artigo mostra como se conectar ao Azure Cosmos DB para MongoDB usando o pacote de driver PyMongo. Uma vez conectado, você pode executar operações em bancos de dados, coleções e documentos.

Nota

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

Este artigo mostra como 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.

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• Python 3.8+
• Interface de Linha de Comando (CLI) do Azure ou Azure PowerShell
• Recurso do Azure Cosmos DB para MongoDB

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 . O dotenv pacote é usado para ler as variáveis de ambiente de um .env arquivo durante o desenvolvimento local.

   # requirements.txt
   pymongo
   python-dotenv
   

3. Crie um ambiente virtual e instale os pacotes.

   Windows

   # 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
   

   Linux / macOS

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

Conecte-se com o driver PyMongo ao Azure Cosmos DB para MongoDB

Para se conectar com o driver PyMongo ao Azure Cosmos DB, crie uma instância do objeto MongoClient . Essa classe é o ponto de partida para executar todas as operações em bancos de dados.

O construtor mais comum para MongoClient requer apenas o host parâmetro, que neste artigo é definido como a COSMOS_CONNECTION_STRING variável de ambiente. Há outros parâmetros opcionais e parâmetros de palavra-chave que você pode usar no construtor. Muitos dos parâmetros opcionais também podem ser especificados com o host parâmetro. Se a mesma opção for passada com host e como parâmetro, o parâmetro terá precedência.

Consulte o Guia de solução de problemas para problemas de conexão.

Obter nome do recurso

Nos comandos abaixo, mostramos msdocs-cosmos como o nome do grupo de recursos. Altere o nome conforme apropriado para a sua situação.

CLI do Azure

1. Crie uma variável de shell para resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos"
   

2. Use o az cosmosdb list comando para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName .

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

PowerShell

1. Crie uma variável de shell para RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos"
   

2. Use o cmdlet Get-AzCosmosDBAccountKey para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName.

   # Get the name of the first Azure Cosmos DB account in your resource group
   $ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
   

Portal

Ignore esta etapa e use as informações do portal na próxima etapa.

Obter a cadeia de ligação

CLI do Azure

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.

PowerShell

1. Encontre a CADEIA DE CONEXÃO na lista de chaves e cadeias de conexão da conta com o Get-AzCosmosDBAccountKey cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary MongoDB Connection String"    
   

2. Registre o valor CONNECTION STRING . Você usará essas credenciais mais tarde.

Portal

1. Inicie sessão no portal do Azure.

2. Navegue até a página de conta existente do Azure Cosmos DB para MongoDB.

3. Na página da conta do Azure Cosmos DB para MongoDB, selecione a opção do menu de navegação Cadeia de Conexão .

4. Registre o valor do campo CADEIA DE CONEXÃO PRIMÁRIA. Você usa esse valor em uma etapa posterior.

   

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:

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env

Um .env arquivo é uma maneira padrão de armazenar variáveis de ambiente em um projeto. Crie um .env arquivo na raiz do seu projeto. Adicione as seguintes linhas ao .env ficheiro:

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Criar MongoClient com cadeia de conexão

1. Adicione dependências para fazer referência aos pacotes PyMongo e python-dotenv .

   import os
   import sys
   
   import pymongo
   from dotenv import load_dotenv
   

2. Defina uma nova instância da classe usando o construtor e a cadeia de conexão lida MongoClient de uma variável de ambiente.

   load_dotenv()
   CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
   client = pymongo.MongoClient(CONNECTION_STRING)
   
   for prop, value in vars(client.options).items():
       print("Property: {}: Value: {} ".format(prop, value))
   

Para obter mais informações sobre diferentes maneiras de criar uma MongoClient instância, consulte Fazendo uma conexão com MongoClient.

Feche a conexão MongoClient

Quando o aplicativo terminar a conexão, lembre-se de fechá-lo. Essa chamada deve ser feita depois de .close() todas as chamadas de banco de dados serem feitas.

client.close()

Usar classes de cliente MongoDB com o Azure Cosmos DB para API para MongoDB

Antes de começar a criar o aplicativo, vamos examinar a hierarquia de recursos no Azure Cosmos DB. O Azure Cosmos DB tem um modelo de objeto específico usado para criar e acessar recursos. O Azure Cosmos DB cria recursos em uma hierarquia que consiste em contas, bancos de dados, coleções e documentos.

Diagrama hierárquico mostrando uma conta do Azure Cosmos DB para MongoDB na parte superior. A conta tem dois nós de banco de dados filho. Um dos nós de banco de dados inclui dois nós de coleção filho. O outro nó do banco de dados inclui um único nó de coleção filho. Esse único nó de coleção tem três nós de doc filho.

Cada tipo de recurso é representado por uma ou mais classes Python associadas. Aqui está uma lista das 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.

Consulte também

• Pacote PyPI
• Referência da API

Próximos passos

Agora que você se conectou a uma API para a conta do MongoDB, use o próximo guia para criar e gerenciar bancos de dados.

Criar um banco de dados no Azure Cosmos DB para MongoDB usando Python