Rychlý start: Azure Cosmos DB pro MongoDB pro Python s ovladačem MongoDB

  • Článek

PLATÍ PRO: MongoDB

Začněte s balíčkem PyMongo a vytvářejte databáze, kolekce a dokumenty v rámci prostředku služby Azure Cosmos DB. Pomocí těchto kroků nainstalujte balíček a vyzkoušejte si ukázkový kód pro základní úlohy.

Poznámka:

Ukázkové fragmenty kódu jsou k dispozici na GitHubu jako projekt Pythonu.

V tomto rychlém startu budete komunikovat s rozhraním API služby Azure Cosmos DB pro MongoDB pomocí jednoho z opensourcových klientských ovladačů MongoDB pro Python, PyMongo. Použijete také příkazy rozšíření MongoDB, které jsou navržené tak, aby vám pomohly vytvářet a získávat databázové prostředky specifické pro model kapacity Azure Cosmos DB.

Požadavky

Kontrola požadovaných součástí

  • V terminálu nebo příkazovém okně spusťte kontrolu python --version , jestli máte nejnovější verzi Pythonu.
  • Spusťte az --version (Azure CLI) nebo Get-Module -ListAvailable Az* (Azure PowerShell) a zkontrolujte, jestli máte nainstalované odpovídající nástroje příkazového řádku Azure.

Nastavení

Tato část vás provede vytvořením účtu služby Azure Cosmos DB a nastavením projektu, který používá balíček npm MongoDB.

Vytvoření účtu služby Azure Cosmos DB

V tomto rychlém startu vytvoříte jeden účet služby Azure Cosmos DB pomocí rozhraní API pro MongoDB.

  1. Vytvořte proměnné prostředí pro accountName, resourceGroupName a umístění.

    # 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. Pokud jste to ještě neudělali, přihlaste se k Azure CLI pomocí az login příkazu.

  3. az group create Pomocí příkazu vytvořte v předplatném novou skupinu prostředků.

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

  4. az cosmosdb create Pomocí příkazu vytvořte nový účet Azure Cosmos DB pro MongoDB s výchozím nastavením.

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

Získání připojovacího řetězce MongoDB

  1. V seznamu připojovací řetězec pro účet pomocí az cosmosdb keys list příkazu vyhledejte rozhraní API pro MongoDB připojovací řetězec.

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

  2. Poznamenejte si hodnoty PRIMÁRNÍHO KLÍČE . Tyto přihlašovací údaje použijete později.

Vytvoření nové aplikace v Pythonu

  1. Vytvořte novou prázdnou složku pomocí upřednostňovaného terminálu a změňte adresář na složku.

    Poznámka:

    Pokud chcete jenom hotový kód, stáhněte nebo fork a naklonujte úložiště ukázkových fragmentů kódu, které obsahuje celý příklad. Úložiště můžete také git clone v Azure Cloud Shellu projít postupem uvedeným v tomto rychlém startu.

  2. Vytvořte soubor requirements.txt se seznamem balíčků PyMongo a python-dotenv.

    # requirements.txt
pymongo
python-dotenv

  3. Vytvořte virtuální prostředí a nainstalujte balíčky.

    # 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

Konfigurace proměnných prostředí

Pokud chcete použít hodnoty CONNECTION STRING v kódu, nastavte tuto hodnotu v místním prostředí, ve kterém je aplikace spuštěná. Pokud chcete nastavit proměnnou prostředí, použijte upřednostňovaný terminál a spusťte následující příkazy:

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

Objektový model

Pojďme se podívat na hierarchii prostředků v rozhraní API pro MongoDB a na objektový model, který se používá k vytváření a přístupu k těmto prostředkům. Azure Cosmos DB vytváří prostředky v hierarchii, které se skládají z účtů, databází, kolekcí a dokumentů.

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

Každý typ prostředku je reprezentován třídou Pythonu. Tady jsou nejběžnější třídy:

  • MongoClient – prvním krokem při práci s PyMongo je vytvoření MongoClientu pro připojení k rozhraní API služby Azure Cosmos DB pro MongoDB. Objekt klienta slouží ke konfiguraci a spouštění požadavků na službu.

  • Databáze – Rozhraní API služby Azure Cosmos DB pro MongoDB může podporovat jednu nebo více nezávislých databází.

  • Kolekce – Databáze může obsahovat jednu nebo více kolekcí. Kolekce je skupina dokumentů uložených v MongoDB a dá se považovat za zhruba ekvivalent tabulky v relační databázi.

  • Dokument – Dokument je sada párů klíč-hodnota. Dokumenty mají dynamické schéma. Dynamické schéma znamená, že dokumenty ve stejné kolekci nemusí mít stejnou sadu polí nebo struktury. Běžná pole v dokumentech kolekce můžou obsahovat různé typy dat.

Další informace o hierarchii entit najdete v článku o modelu prostředků služby Azure Cosmos DB.

Příklady kódu

Vzorový kód popsaný v tomto článku vytvoří databázi s názvem adventureworks kolekce s názvem products. Kolekce products je navržená tak, aby obsahovala podrobnosti o produktu, jako je název, kategorie, množství a indikátor prodeje. Každý produkt obsahuje také jedinečný identifikátor. Kompletní vzorový kód je na https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/adrese .

V následujících krocích databáze nebude používat horizontální dělení a zobrazí synchronní aplikaci používající ovladač PyMongo . Pro asynchronní aplikace použijte ovladač Motoru .

Ověření klienta

  1. V adresáři projektu vytvořte soubor run.py . V editoru přidejte příkazy vyžadovat pro odkazy na balíčky, které budete používat, včetně balíčků PyMongo a python-dotenv.

    import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv

  2. Získejte informace o připojení z proměnné prostředí definované v souboru .env .

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

  3. Definujte konstanty, které použijete v kódu.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Připojení k rozhraní API služby Azure Cosmos DB pro MongoDB

Pomocí objektu MongoClient se připojte k prostředku Azure Cosmos DB for MongoDB. Metoda connect vrátí odkaz na databázi.

client = pymongo.MongoClient(CONNECTION_STRING)

Získání databáze

Zkontrolujte, jestli databáze existuje s metodou list_database_names . Pokud databáze neexistuje, pomocí příkazu create database extension ji vytvořte se zadanou zřízenou propustností.

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

Získání kolekce

Zkontrolujte, jestli kolekce existuje s metodou list_collection_names . Pokud kolekce neexistuje, vytvořte ji pomocí příkazu create collection extension.

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

Vytvoření indexu

Vytvořte index pomocí příkazu rozšíření kolekce aktualizací. Index můžete také nastavit v příkazu create collection extension. Nastavte index na name vlastnost v tomto příkladu, abyste později mohli řadit metodou řazení třídy kurzoru podle názvu produktu.

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

Vytvoření dokumentu

Vytvořte dokument s vlastnostmi produktu pro adventureworks databázi:

  • Vlastnost kategorie. Tuto vlastnost lze použít jako klíč logického oddílu.
  • Vlastnost name .
  • Vlastnost skladového množství .
  • Nemovitost prodeje označující, zda je produkt v prodeji.
"""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))

Vytvořte v kolekci dokument voláním operace na úrovni kolekce update_one. V tomto příkladu místo vytvoření nového dokumentu upsertujete. Upsert není v tomto příkladu nutný, protože název produktu je náhodný. Pro případ, že kód spustíte více než jednou a název produktu je stejný, je vhodné ho upsertovat.

Výsledek update_one operace obsahuje _id hodnotu pole, kterou můžete použít v následných operacích. Vlastnost _id byla vytvořena automaticky.

Získání dokumentu

K získání dokumentu použijte metodu find_one .

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

Ve službě Azure Cosmos DB můžete provést levnější operaci čtení bodů pomocí jedinečného identifikátoru (_id) i klíče oddílu.

Dotazování na dokumenty

Po vložení dokumentu můžete spustit dotaz, abyste získali všechny dokumenty, které odpovídají určitému filtru. Tento příklad najde všechny dokumenty, které odpovídají určité kategorii: gear-surf-surfboards. Jakmile je dotaz definovaný, zavolejte Collection.find k získání výsledku Cursor a pak použijte řazení.

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

Řešení potíží:

  • Pokud se zobrazí například chyba The index path corresponding to the specified order-by item is excluded., ujistěte se, že jste vytvořili index.

Spuštění kódu

Tato aplikace vytvoří rozhraní API pro databázi a kolekci MongoDB a vytvoří dokument a pak přečte stejný dokument zpět. Nakonec příklad vydá dotaz, který vrátí dokumenty, které odpovídají zadané kategorii produktu. V každém kroku příklad vypíše informace do konzoly o krocích, které provedl.

Pokud chcete aplikaci spustit, přejděte pomocí terminálu do adresáře aplikace a spusťte aplikaci.

python run.py

Výstup aplikace by měl být podobný tomuto příkladu:


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}

Vyčištění prostředků

Pokud už účet Azure Cosmos DB for NoSQL nepotřebujete, můžete odstranit odpovídající skupinu prostředků.

az group delete Pomocí příkazu odstraňte skupinu prostředků.

az group delete --name $resourceGroupName