Sdílet prostřednictvím


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

PLATÍ PRO: MongoDB

Začněte s MongoDB vytvářet databáze, kolekce a dokumenty v rámci prostředku služby Azure Cosmos DB. Pomocí následujícího postupu nasaďte do svého prostředí minimální řešení pomocí Azure Developer CLI.

Referenční dokumentace | k rozhraní API pro MongoDB s balíčkem pymongo v | Azure Developer CLI

Požadavky

Nastavení

Nasaďte vývojový kontejner tohoto projektu do svého prostředí. Pak pomocí Azure Developer CLI (azd) vytvořte účet služby Azure Cosmos DB pro MongoDB a nasaďte kontejnerizovanou ukázkovou aplikaci. Ukázková aplikace používá klientskou knihovnu ke správě, vytváření, čtení a dotazování ukázkových dat.

Otevřít v GitHub Codespaces

Otevřít v vývojovém kontejneru

Důležité

Účty GitHubu zahrnují nárok na úložiště a hodiny jádra bez poplatků. Další informace najdete v zahrnutých hodinách úložiště a jader pro účty GitHubu.

  1. Otevřete terminál v kořenovém adresáři projektu.

  2. Ověřte se v Rozhraní příkazového řádku Azure Developer CLI pomocí azd auth loginrozhraní příkazového řádku . Postupujte podle kroků určených nástrojem k ověření v rozhraní příkazového řádku pomocí vašich upřednostňovaných přihlašovacích údajů Azure.

    azd auth login
    
  3. Slouží azd init k inicializaci projektu.

    azd init --template cosmos-db-mongodb-python-quickstart
    

    Poznámka:

    V tomto rychlém startu se používá úložiště GitHub šablony azure-samples/cosmos-db-mongodb-python-quickstart . Azure Developer CLI tento projekt automaticky naklonuje na váš počítač, pokud tam ještě není.

  4. Během inicializace nakonfigurujte jedinečný název prostředí.

    Tip

    Název prostředí se také použije jako název cílové skupiny prostředků. Pro účely tohoto rychlého startu zvažte použití .msdocs-cosmos-db

  5. Nasaďte účet služby Azure Cosmos DB pomocí azd up. Šablony Bicep také nasazují ukázkovou webovou aplikaci.

    azd up
    
  6. Během procesu zřizování vyberte své předplatné a požadované umístění. Počkejte na dokončení procesu zřizování. Proces může trvat přibližně pět minut.

  7. Po dokončení zřizování prostředků Azure se do výstupu zahrne adresa URL spuštěné webové aplikace.

    Deploying services (azd deploy)
    
      (✓) Done: Deploying service web
    - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
    
    SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
    
  8. Pomocí adresy URL v konzole přejděte do webové aplikace v prohlížeči. Sledujte výstup spuštěné aplikace.

    Snímek obrazovky se spuštěnou webovou aplikací


Instalace klientské knihovny

  1. Vytvořte requirements.txt soubor v adresáři aplikace, který obsahuje balíčky PyMongo a python-dotenv .

    # requirements.txt
    pymongo
    python-dotenv
    
  2. 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
    

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 hierarchie služby Azure Cosmos DB, včetně účtů, databází, kolekcí a dokumentů

Hierarchický diagram znázorňující účet služby Azure Cosmos DB v horní části Účet má dva podřízené horizontální oddíly databáze. Jeden z horizontálních oddílů databáze zahrnuje dvě podřízené horizontální oddíly kolekce. Druhý horizontální oddíl databáze zahrnuje jeden podřízený horizontální oddíl kolekce. Tento horizontální oddíl jedné kolekce má tři podřízené horizontální oddíly dokumentace.

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