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
- Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
- Účet GitHub
- Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
- Azure Developer CLI
- Docker Desktop
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.
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.
Otevřete terminál v kořenovém adresáři projektu.
Ověřte se v Rozhraní příkazového řádku Azure Developer CLI pomocí
azd auth login
rozhraní 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
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í.
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
Nasaďte účet služby Azure Cosmos DB pomocí
azd up
. Šablony Bicep také nasazují ukázkovou webovou aplikaci.azd up
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.
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.
Pomocí adresy URL v konzole přejděte do webové aplikace v prohlížeči. Sledujte výstup spuštěné aplikace.
Instalace klientské knihovny
Vytvořte
requirements.txt
soubor v adresáři aplikace, který obsahuje balíčky PyMongo a python-dotenv .# requirements.txt pymongo python-dotenv
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ů.
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
- Ověření klienta
- Získání databáze
- Získání kolekce
- Vytvoření indexu
- Vytvoření dokumentu
- Získání dokumentu
- Dotazování dokumentů
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
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
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")
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