Aan de slag met Azure Cosmos DB voor MongoDB en Python

VAN TOEPASSING OP: MongoDB

In dit artikel leest u hoe u verbinding maakt met Azure Cosmos DB voor MongoDB met behulp van het PyMongo-stuurprogrammapakket. Zodra u verbinding hebt gemaakt, kunt u bewerkingen uitvoeren op databases, verzamelingen en documenten.

Notitie

De voorbeeldcodefragmenten zijn beschikbaar op GitHub als een Python-project.

In dit artikel leest u hoe u kunt communiceren met de API van Azure Cosmos DB voor MongoDB met behulp van een van de opensource MongoDB-clientstuurprogramma's voor Python, PyMongo.

Vereisten

• Een Azure-account met een actief abonnement. Gratis een account maken
• Python 3.8+
• Azure-opdrachtregelinterface (CLI) of Azure PowerShell
• Azure Cosmos DB voor MongoDB-resource

Een nieuwe Python-app maken

1. Maak een nieuwe lege map met behulp van de gewenste terminal en wijzig de map in de map.

   Notitie

   Als u alleen de voltooide code wilt, downloadt of forkt u de voorbeeldcodefragmentenopslagplaats met het volledige voorbeeld. U kunt ook git clone de opslagplaats in Azure Cloud Shell gebruiken om de stappen in deze quickstart te doorlopen.

2. Maak een requirements.txt-bestand met de PyMongo - en python-dotenv-pakketten . Het dotenv pakket wordt gebruikt om de omgevingsvariabelen uit een .env bestand te lezen tijdens lokale ontwikkeling.

   # requirements.txt
   pymongo
   python-dotenv
   

3. Maak een virtuele omgeving en installeer de pakketten.

   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
   

Verbinding maken met PyMongo-stuurprogramma naar Azure Cosmos DB voor MongoDB

Als u verbinding wilt maken met het PyMongo-stuurprogramma met Azure Cosmos DB, maakt u een exemplaar van het MongoClient-object . Deze klasse is het startpunt om alle bewerkingen uit te voeren op databases.

De meest voorkomende constructor voor MongoClient vereist alleen de host parameter, die in dit artikel is ingesteld op de COSMOS_CONNECTION_STRING omgevingsvariabele. Er zijn andere optionele parameters en trefwoordparameters die u in de constructor kunt gebruiken. Veel van de optionele parameters kunnen ook worden opgegeven met de host parameter. Als dezelfde optie wordt doorgegeven met host en als parameter, heeft de parameter voorrang.

Raadpleeg de gids voor probleemoplossing voor verbindingsproblemen.

Resourcenaam ophalen

In de onderstaande opdrachten wordt msdocs-cosmos weergegeven als de naam van de resourcegroep. Wijzig de naam zo nodig voor uw situatie.

Azure-CLI

1. Maak een shellvariabele voor resourceGroupName.

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

2. Gebruik de az cosmosdb list opdracht om de naam van het eerste Azure Cosmos DB-account in uw resourcegroep op te halen en op te slaan in de accountName-shellvariabele .

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

PowerShell

1. Maak een shellvariabele voor RESOURCE_GROUP_NAME.

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

2. Gebruik de cmdlet Get-AzCosmosDBAccountKey om de naam van het eerste Azure Cosmos DB-account in uw resourcegroep op te halen en op te slaan in de accountName-shellvariabele.

   # 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

Sla deze stap over en gebruik de informatie voor de portal in de volgende stap.

De verbindingsreeks ophalen

Azure-CLI

1. Zoek de API voor MongoDB-verbindingsreeks in de lijst met verbindingsreeks s voor het account met de az cosmosdb keys list opdracht.

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

2. Noteer de WAARDEN VAN DE PRIMAIRE SLEUTEL . U gebruikt deze referenties later.

PowerShell

1. Zoek de VERBINDINGSREEKS uit de lijst met sleutels en verbindingsreeks s voor het account met de Get-AzCosmosDBAccountKey cmdlet.

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

2. Noteer de waarde CONNECTION STRING . U gebruikt deze referenties later.

Portal

1. Meld u aan bij de Azure-portal.

2. Navigeer naar de bestaande azure Cosmos DB for MongoDB-accountpagina.

3. Selecteer op de pagina van het Azure Cosmos DB for MongoDB-account de menuoptie Verbinding maken reeksnavigatie.

4. Noteer de waarde voor het veld PRIMAIRE VERBINDINGSREEKS . U gebruikt deze waarde in een latere stap.

   

Omgevingsvariabelen configureren

Als u de WAARDEN VOOR VERBINDINGSREEKS in uw code wilt gebruiken, stelt u deze waarde in in de lokale omgeving waarop de toepassing wordt uitgevoerd. Als u de omgevingsvariabele wilt instellen, gebruikt u de terminal van uw voorkeur om de volgende opdrachten uit te voeren:

Windows

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

Linux/macOS

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

.Env

Een .env bestand is een standaardmethode voor het opslaan van omgevingsvariabelen in een project. Maak een .env bestand in de hoofdmap van uw project. Voeg de volgende regels toe aan het .env bestand:

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

MongoClient maken met verbindingsreeks

1. Voeg afhankelijkheden toe om te verwijzen naar de PyMongo - en python-dotenv-pakketten .

   import os
   import sys
   
   import pymongo
   from dotenv import load_dotenv
   

2. Definieer een nieuw exemplaar van de MongoClient klasse met behulp van de constructor en de verbindingsreeks gelezen uit een omgevingsvariabele.

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

Zie Een Verbinding maken ion maken met MongoClient voor meer informatie over verschillende manieren om een MongoClient exemplaar te maken.

Sluit de MongoClient-verbinding

Wanneer uw toepassing klaar is met de verbinding, moet u deze sluiten. Deze .close() aanroep moet zijn nadat alle databaseaanroepen zijn uitgevoerd.

client.close()

MongoDB-clientklassen gebruiken met Azure Cosmos DB voor API voor MongoDB

Voordat u begint met het bouwen van de toepassing, gaan we kijken naar de hiërarchie van resources in Azure Cosmos DB. Azure Cosmos DB heeft een specifiek objectmodel dat wordt gebruikt voor het maken en openen van resources. Azure Cosmos DB maakt resources in een hiërarchie die bestaat uit accounts, databases, verzamelingen en documenten.

Hiërarchisch diagram met een Azure Cosmos DB DB-account bovenaan. Het account heeft twee onderliggende databaseknooppunten. Een van de databaseknooppunten bevat twee onderliggende verzamelingsknooppunten. Het andere databaseknooppunt bevat één onderliggend verzamelingsknooppunt. Dat knooppunt voor één verzameling heeft drie onderliggende doc-knooppunten.

Elk type resource wordt vertegenwoordigd door een of meer gekoppelde Python-klassen. Hier volgt een lijst met de meest voorkomende klassen:

• MongoClient : de eerste stap bij het werken met PyMongo is het maken van een MongoClient om verbinding te maken met de API van Azure Cosmos DB voor MongoDB. Het clientobject wordt gebruikt om aanvragen aan de service te configureren en uitvoeren.

• Database : de API van Azure Cosmos DB voor MongoDB kan een of meer onafhankelijke databases ondersteunen.

• Verzameling : een database kan een of meer verzamelingen bevatten. Een verzameling is een groep documenten die zijn opgeslagen in MongoDB en kan worden beschouwd als ongeveer het equivalent van een tabel in een relationele database.

• Document - Een document is een set sleutel-waardeparen. Documenten hebben een dynamisch schema. Dynamisch schema betekent dat documenten in dezelfde verzameling niet dezelfde set velden of structuur hoeven te hebben. En algemene velden in documenten van een verzameling kunnen verschillende typen gegevens bevatten.

Zie het artikel over het Azure Cosmos DB-resourcemodel voor meer informatie over de hiërarchie van entiteiten.

Zie ook

• PyPI-pakket
• API-naslaginformatie

Volgende stappen

Nu u verbinding hebt gemaakt met een API voor MongoDB-account, gebruikt u de volgende handleiding voor het maken en beheren van databases.

Een database maken in Azure Cosmos DB voor MongoDB met behulp van Python