Udostępnij za pośrednictwem

Szybki start: usługa Azure Cosmos DB dla bazy danych MongoDB dla języka Python ze sterownikiem bazy danych MongoDB

  • Artykuł

DOTYCZY: MongoDB

Rozpocznij pracę z bazą danych MongoDB, aby tworzyć bazy danych, kolekcje i dokumenty w ramach zasobu usługi Azure Cosmos DB. Wykonaj następujące kroki, aby wdrożyć minimalne rozwiązanie w środowisku przy użyciu interfejsu wiersza polecenia dla deweloperów platformy Azure.

Dokumentacja referencyjna interfejsu API dla bazy danych | MongoDB dotycząca pakietu pymongo pakietu | interfejsu wiersza polecenia dla deweloperów platformy Azure

Wymagania wstępne

Konfigurowanie

Wdróż kontener projektowy w swoim środowisku. Następnie użyj interfejsu wiersza polecenia dla deweloperów platformy Azure (azd), aby utworzyć konto usługi Azure Cosmos DB dla bazy danych MongoDB i wdrożyć konteneryzowaną przykładową aplikację. Przykładowa aplikacja używa biblioteki klienta do zarządzania, tworzenia, odczytywania i wykonywania zapytań dotyczących przykładowych danych.

Otwieranie w usłudze GitHub Codespaces

Otwórz w kontenerze deweloperskim

Ważne

Konta usługi GitHub obejmują uprawnienia do magazynowania i godzin podstawowych bez ponoszenia kosztów. Aby uzyskać więcej informacji, zobacz uwzględnione godziny magazynowania i rdzeni dla kont usługi GitHub.

  1. Otwórz terminal w katalogu głównym projektu.

  2. Uwierzytelnianie w interfejsie wiersza polecenia dla deweloperów platformy Azure przy użyciu polecenia azd auth login. Wykonaj kroki określone przez narzędzie, aby uwierzytelnić się w interfejsie wiersza polecenia przy użyciu preferowanych poświadczeń platformy Azure.

    azd auth login

  3. Użyj azd init polecenia , aby zainicjować projekt.

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

    Uwaga

    W tym przewodniku Szybki start jest używane repozytorium GitHub szablonu azure-samples/cosmos-db-mongodb-python-quickstart . Interfejs wiersza polecenia dla deweloperów platformy Azure automatycznie klonuje ten projekt na maszynę, jeśli jeszcze go nie ma.

  4. Podczas inicjowania skonfiguruj unikatową nazwę środowiska.

    Napiwek

    Nazwa środowiska będzie również używana jako nazwa docelowej grupy zasobów. W tym przewodniku Szybki start rozważ użycie polecenia msdocs-cosmos-db.

  5. Wdróż konto usługi Azure Cosmos DB przy użyciu polecenia azd up. Szablony Bicep wdrażają również przykładową aplikację internetową.

    azd up

  6. Podczas procesu aprowizacji wybierz subskrypcję i żądaną lokalizację. Poczekaj na zakończenie procesu aprowizacji. Proces może potrwać około pięciu minut.

  7. Po zakończeniu aprowizacji zasobów platformy Azure adres URL uruchomionej aplikacji internetowej zostanie uwzględniony w danych wyjściowych.

    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. Użyj adresu URL w konsoli, aby przejść do aplikacji internetowej w przeglądarce. Obserwuj dane wyjściowe uruchomionej aplikacji.

    Zrzut ekranu przedstawiający uruchomioną aplikację internetową.

Instalowanie biblioteki klienta

  1. requirements.txt Utwórz plik w katalogu aplikacji zawierający listę pakietów PyMongo i python-dotenv.

    # requirements.txt
pymongo
python-dotenv

  2. Utwórz środowisko wirtualne i zainstaluj pakiety.

    # 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

Model obiektów

Przyjrzyjmy się hierarchii zasobów w interfejsie API dla bazy danych MongoDB i modelu obiektów używanego do tworzenia tych zasobów i uzyskiwania do nich dostępu. Usługa Azure Cosmos DB tworzy zasoby w hierarchii składające się z kont, baz danych, kolekcji i dokumentów.

Diagram hierarchii usługi Azure Cosmos DB, w tym kont, baz danych, kolekcji i dokumentacji.

Każdy typ zasobu jest reprezentowany przez klasę języka Python. Oto najbardziej typowe klasy:

  • MongoClient — pierwszym krokiem podczas pracy z rozwiązaniem PyMongo jest utworzenie klienta MongoClient w celu nawiązania połączenia z interfejsem API usługi Azure Cosmos DB dla bazy danych MongoDB. Obiekt klienta służy do konfigurowania i wykonywania żądań względem usługi.

  • Baza danych — interfejs API usługi Azure Cosmos DB dla bazy danych MongoDB może obsługiwać co najmniej jedną niezależną bazę danych.

  • Kolekcja — baza danych może zawierać co najmniej jedną kolekcję. Kolekcja jest grupą dokumentów przechowywanych w bazie danych MongoDB i może być uważana za mniej więcej równoważną tabeli w relacyjnej bazie danych.

  • Dokument — dokument jest zestawem par klucz-wartość. Dokumenty mają schemat dynamiczny. Schemat dynamiczny oznacza, że dokumenty w tej samej kolekcji nie muszą mieć tego samego zestawu pól ani struktury. Typowe pola w dokumentach kolekcji mogą zawierać różne typy danych.

Aby dowiedzieć się więcej na temat hierarchii jednostek, zobacz artykuł Dotyczący modelu zasobów usługi Azure Cosmos DB.

Przykłady kodu

Przykładowy kod opisany w tym artykule tworzy bazę danych o nazwie z kolekcją o nazwie adventureworks products. Kolekcja została zaprojektowana products tak, aby zawierała szczegóły produktu, takie jak nazwa, kategoria, ilość i wskaźnik sprzedaży. Każdy produkt zawiera również unikatowy identyfikator. Kompletny przykładowy kod znajduje się pod adresem https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

W poniższych krokach baza danych nie będzie używać fragmentowania i pokazuje synchroniczną aplikację przy użyciu sterownika PyMongo . W przypadku aplikacji asynchronicznych należy użyć sterownika motorowego.

Uwierzytelnianie użytkownika

  1. W katalogu projektu utwórz plik run.py . W edytorze dodaj instrukcje require, aby odwoływać się do pakietów, których będziesz używać, w tym pakietów PyMongo i python-dotenv.

    import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv

  2. Pobierz informacje o połączeniu ze zmiennej środowiskowej zdefiniowanej w pliku env .

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

  3. Zdefiniuj stałe, których będziesz używać w kodzie.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Nawiązywanie połączenia z interfejsem API usługi Azure Cosmos DB dla bazy danych MongoDB

Użyj obiektu MongoClient, aby nawiązać połączenie z zasobem usługi Azure Cosmos DB dla bazy danych MongoDB. Metoda connect zwraca odwołanie do bazy danych.

client = pymongo.MongoClient(CONNECTION_STRING)

Pobieranie bazy danych

Sprawdź, czy baza danych istnieje z metodą list_database_names . Jeśli baza danych nie istnieje, użyj polecenia create database extension , aby utworzyć ją z określoną aprowizowaną przepływnością.

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

Pobieranie kolekcji

Sprawdź, czy kolekcja istnieje z metodą list_collection_names . Jeśli kolekcja nie istnieje, użyj polecenia create collection extension, aby go utworzyć.

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

Tworzenie indeksu

Utwórz indeks przy użyciu polecenia rozszerzenia kolekcji aktualizacji. Indeks można również ustawić w poleceniu create collection extension (Tworzenie rozszerzenia kolekcji). Ustaw indeks na name właściwość w tym przykładzie, aby później można było sortować za pomocą metody sortowania klasy kursora w nazwie 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())))

Tworzenie dokumentu

Utwórz dokument z właściwościami produktu dla adventureworks bazy danych:

  • Właściwość category. Tej właściwości można użyć jako klucza partycji logicznej.
  • Właściwość name .
  • Właściwość ilości zapasów.
  • Nieruchomość sprzedaży wskazująca, czy produkt jest w sprzedaży.
"""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))

Utwórz dokument w kolekcji, wywołując operację poziomu kolekcji update_one. W tym przykładzie utworzysz nowy dokument zamiast go utworzyć. W tym przykładzie funkcja Upsert nie jest konieczna, ponieważ nazwa produktu jest losowa. Jednak dobrym rozwiązaniem jest upsert w przypadku uruchomienia kodu więcej niż raz, a nazwa produktu jest taka sama.

Wynik update_one operacji zawiera _id wartość pola, której można użyć w kolejnych operacjach. Właściwość _id została utworzona automatycznie.

Pobieranie dokumentu

Użyj metody find_one, aby uzyskać dokument.

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

W usłudze Azure Cosmos DB można wykonać mniej kosztowną operację odczytu punktu przy użyciu zarówno unikatowego identyfikatora (_id) jak i klucza partycji.

Dokumenty z zapytaniami

Po wstawieniu dokumentu można uruchomić zapytanie, aby pobrać wszystkie dokumenty pasujące do określonego filtru. W tym przykładzie znajdują się wszystkie dokumenty pasujące do określonej kategorii: gear-surf-surfboards. Po zdefiniowaniu zapytania wywołaj Collection.find metodę Cursor , aby uzyskać wynik, a następnie użyj sortowania.

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

Rozwiązywanie problemów:

  • Jeśli wystąpi błąd, taki jak The index path corresponding to the specified order-by item is excluded., upewnij się, że utworzono indeks.

Uruchamianie kodu

Ta aplikacja tworzy interfejs API dla bazy danych MongoDB i kolekcji oraz tworzy dokument, a następnie odczytuje dokładnie ten sam dokument z powrotem. Na koniec przykład powoduje problemy z zapytaniem, które zwraca dokumenty pasujące do określonej kategorii produktów. W każdym kroku przykład generuje informacje do konsoli o wykonanych krokach.

Aby uruchomić aplikację, użyj terminalu, aby przejść do katalogu aplikacji i uruchomić aplikację.

python run.py

Dane wyjściowe aplikacji powinny być podobne do tego przykładu:


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}

Czyszczenie zasobów

Jeśli nie potrzebujesz już konta usługi Azure Cosmos DB for NoSQL, możesz usunąć odpowiednią grupę zasobów.

Użyj polecenia , az group delete aby usunąć grupę zasobów.

az group delete --name $resourceGroupName