Share via

Snabbstart: Azure Cosmos DB för MongoDB för Python med MongoDB-drivrutin

  • Artikel

GÄLLER FÖR: Mongodb

Kom igång med PyMongo-paketet för att skapa databaser, samlingar och dokument i din Azure Cosmos DB-resurs. Följ de här stegen för att installera paketet och prova exempelkod för grundläggande uppgifter.

Kommentar

Exempelkodfragmenten är tillgängliga på GitHub som ett Python-projekt.

I den här snabbstarten kommunicerar du med Azure Cosmos DB:s API för MongoDB med hjälp av en av MongoDB-klientdrivrutinerna med öppen källkod för Python, PyMongo. Dessutom använder du MongoDB-tilläggskommandona, som är utformade för att hjälpa dig att skapa och hämta databasresurser som är specifika för Azure Cosmos DB-kapacitetsmodellen.

Förutsättningar

Kravkontroll

  • I ett terminal- eller kommandofönster kör du python --version för att kontrollera att du har en ny version av Python.
  • Kör az --version (Azure CLI) eller Get-Module -ListAvailable Az* (Azure PowerShell) för att kontrollera att du har rätt Azure-kommandoradsverktyg installerade.

Konfigurera

Det här avsnittet beskriver hur du skapar ett Azure Cosmos DB-konto och konfigurerar ett projekt som använder MongoDB npm-paketet.

Skapa ett Azure Cosmos DB-konto

Den här snabbstarten skapar ett enda Azure Cosmos DB-konto med hjälp av API:et för MongoDB.

  1. Skapa gränssnittsvariabler för accountName, resourceGroupName och plats.

    # 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. Om du inte redan har gjort det loggar du in på Azure CLI med kommandot az login .

  3. az group create Använd kommandot för att skapa en ny resursgrupp i din prenumeration.

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

  4. az cosmosdb create Använd kommandot för att skapa ett nytt Azure Cosmos DB för MongoDB-konto med standardinställningar.

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

Hämta anslutningssträngen för MongoDB

  1. Leta upp API:et för MongoDB-anslutningssträng från listan över anslutningssträng för kontot med az cosmosdb keys list kommandot .

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

  2. Registrera primärnyckelvärdena. Du använder dessa autentiseringsuppgifter senare.

Skapa en ny Python-app

  1. Skapa en ny tom mapp med önskad terminal och ändra katalogen till mappen.

    Kommentar

    Om du bara vill ha den färdiga koden laddar du ned eller förgrenar och klonar exempelkodfragmentlagringsplatsen som har det fullständiga exemplet. Du kan också git clone använda lagringsplatsen i Azure Cloud Shell för att gå igenom stegen som visas i den här snabbstarten.

  2. Skapa en requirements.txt-fil som visar paketen PyMongo och python-dotenv .

    # requirements.txt
pymongo
python-dotenv

  3. Skapa en virtuell miljö och installera paketen.

    # 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

Konfigurera miljövariabler

Om du vill använda VÄRDENA FÖR ANSLUTNINGSSTRÄNG i koden anger du det här värdet i den lokala miljö som kör programmet. Om du vill ange miljövariabeln använder du önskad terminal för att köra följande kommandon:

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

Objektmodell

Nu ska vi titta på resurshierarkin i API:et för MongoDB och objektmodellen som används för att skapa och komma åt dessa resurser. Azure Cosmos DB skapar resurser i en hierarki som består av konton, databaser, samlingar och dokument.

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

Varje typ av resurs representeras av en Python-klass. Här är de vanligaste klasserna:

  • MongoClient – Det första steget när du arbetar med PyMongo är att skapa en MongoClient för att ansluta till Azure Cosmos DB:s API för MongoDB. Klientobjektet används för att konfigurera och köra begäranden mot tjänsten.

  • Databas – Azure Cosmos DB:s API för MongoDB kan stödja en eller flera oberoende databaser.

  • Samling – En databas kan innehålla en eller flera samlingar. En samling är en grupp dokument som lagras i MongoDB och kan betraktas som ungefär samma som en tabell i en relationsdatabas.

  • Dokument – Ett dokument är en uppsättning nyckel/värde-par. Dokument har dynamiskt schema. Dynamiskt schema innebär att dokument i samma samling inte behöver ha samma uppsättning fält eller struktur. Och vanliga fält i en samlings dokument kan innehålla olika typer av data.

Mer information om entitetshierarkin finns i artikeln Azure Cosmos DB-resursmodell .

Kodexempel

Exempelkoden som beskrivs i den här artikeln skapar en databas med namnet adventureworks med en samling med namnet products. Samlingen products är utformad för att innehålla produktinformation som namn, kategori, kvantitet och en försäljningsindikator. Varje produkt innehåller också en unik identifierare. Den fullständiga exempelkoden är på https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

För stegen nedan använder databasen inte horisontell partitionering och visar ett synkront program med pymongodrivrutinen. Använd motordrivrutinen för asynkrona program.

Autentisera klienten

  1. Skapa en run.py fil i projektkatalogen. I redigeringsprogrammet lägger du till kräv-instruktioner för referenspaket som du använder, inklusive PyMongo- och python-dotenv-paketen.

    import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv

  2. Hämta anslutningsinformationen från miljövariabeln som definierats i en .env-fil .

    load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")

  3. Definiera konstanter som du ska använda i koden.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Anslut till Azure Cosmos DB:s API för MongoDB

Använd MongoClient-objektet för att ansluta till din Azure Cosmos DB for MongoDB-resurs. Connect-metoden returnerar en referens till databasen.

client = pymongo.MongoClient(CONNECTION_STRING)

Hämta databas

Kontrollera om databasen finns med list_database_names metod. Om databasen inte finns använder du kommandot skapa databastillägg för att skapa den med ett angivet etablerat dataflöde.

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

Hämta samling

Kontrollera om samlingen finns med metoden list_collection_names . Om samlingen inte finns använder du kommandot skapa samlingstillägg för att skapa den.

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

Skapa ett index

Skapa ett index med hjälp av kommandot för uppdateringssamlingstillägget. Du kan också ange indexet i kommandot skapa samlingstillägg. Ange indexet till name egenskap i det här exemplet så att du senare kan sortera med sorteringsmetoden för markörklass efter produktnamn.

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

Skapa ett dokument

Skapa ett dokument med produktegenskapernaadventureworks för databasen:

  • En kategoriegenskap . Den här egenskapen kan användas som den logiska partitionsnyckeln.
  • En namnegenskap .
  • En lagerkvantitetsegenskap.
  • En försäljningsfastighet som anger om produkten är till salu.
"""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))

Skapa ett dokument i samlingen genom att anropa åtgärden på samlingsnivå update_one. I det här exemplet ökar du i stället för att skapa ett nytt dokument. Upsert är inte nödvändigt i det här exemplet eftersom produktnamnet är slumpmässigt. Det är dock en bra idé att öka om du kör koden mer än en gång och produktnamnet är detsamma.

Resultatet av åtgärden update_one innehåller det _id fältvärde som du kan använda i efterföljande åtgärder. Egenskapen _id skapades automatiskt.

Hämta ett dokument

Använd metoden find_one för att hämta ett dokument.

doc = collection.find_one({"_id": result.upserted_id})
print("Found a document with _id {}: {}\n".format(result.upserted_id, doc))

I Azure Cosmos DB kan du utföra en billigare punktläsningsåtgärd med hjälp av både den unika identifieraren (_id) och en partitionsnyckel.

Köra en fråga mot dokument

När du har infogat ett dokument kan du köra en fråga för att hämta alla dokument som matchar ett visst filter. Det här exemplet hittar alla dokument som matchar en specifik kategori: gear-surf-surfboards. När frågan har definierats anropar du Collection.find för att hämta ett Cursor resultat och använder sedan sortering.

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

Felsökning:

  • Om du får ett fel, till exempel The index path corresponding to the specified order-by item is excluded., kontrollerar du att du har skapat indexet.

Kör koden

Den här appen skapar ett API för MongoDB-databas och samling och skapar ett dokument och läser sedan exakt samma dokument tillbaka. Slutligen utfärdar exemplet en fråga som returnerar dokument som matchar en angiven produktkategori. Med varje steg matar exemplet ut information till konsolen om de steg som den har utfört.

Om du vill köra appen använder du en terminal för att navigera till programkatalogen och köra programmet.

python run.py

Utdata från appen bör likna det här exemplet:


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}

Rensa resurser

När du inte längre behöver Azure Cosmos DB för NoSQL-kontot kan du ta bort motsvarande resursgrupp.

az group delete Använd kommandot för att ta bort resursgruppen.

az group delete --name $resourceGroupName