Share via

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 pakietem PyMongo, aby utworzyć bazy danych, kolekcje i dokumenty w ramach zasobu usługi Azure Cosmos DB. Wykonaj następujące kroki, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

Uwaga

Przykładowe fragmenty kodu są dostępne w witrynie GitHub jako projekt języka Python.

W tym przewodniku Szybki start komunikujesz się z interfejsem API usługi Azure Cosmos DB dla bazy danych MongoDB przy użyciu jednego z sterowników klienta bazy danych MongoDB typu open source dla języka Python, PyMongo. Ponadto użyjesz poleceń rozszerzenia MongoDB, które zostały zaprojektowane w celu ułatwienia tworzenia i uzyskiwania zasobów bazy danych specyficznych dla modelu pojemności usługi Azure Cosmos DB.

Wymagania wstępne

Sprawdzanie wymagań wstępnych

  • W terminalu lub oknie polecenia uruchom polecenie python --version , aby sprawdzić, czy masz najnowszą wersję języka Python.
  • Uruchom polecenie az --version (interfejs wiersza polecenia platformy Azure) lub Get-Module -ListAvailable Az* (Azure PowerShell), aby sprawdzić, czy masz zainstalowane odpowiednie narzędzia wiersza polecenia platformy Azure.

Konfigurowanie

W tej sekcji opisano proces tworzenia konta usługi Azure Cosmos DB i konfigurowania projektu korzystającego z pakietu npm bazy danych MongoDB.

Tworzenie konta usługi Azure Cosmos DB

Ten przewodnik Szybki start utworzy pojedyncze konto usługi Azure Cosmos DB przy użyciu interfejsu API dla bazy danych MongoDB.

  1. Utwórz zmienne powłoki dla parametrów accountName, resourceGroupName i location.

    # 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. Jeśli jeszcze tego nie zrobiono, zaloguj się do interfejsu az login wiersza polecenia platformy Azure przy użyciu polecenia .

  3. Użyj polecenia , az group create aby utworzyć nową grupę zasobów w ramach subskrypcji.

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

  4. az cosmosdb create Użyj polecenia , aby utworzyć nowe konto usługi Azure Cosmos DB dla bazy danych MongoDB z ustawieniami domyślnymi.

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

Uzyskiwanie parametrów połączenia bazy danych MongoDB

  1. Znajdź interfejs API dla bazy danych MongoDB parametry połączenia z listy parametry połączenia dla konta za az cosmosdb keys list pomocą polecenia .

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

  2. Zapisz wartości KLUCZ PODSTAWOWY. Te poświadczenia będą używane później.

Tworzenie nowej aplikacji w języku Python

  1. Utwórz nowy pusty folder przy użyciu preferowanego terminalu i zmień katalog na folder.

    Uwaga

    Jeśli chcesz po prostu gotowy kod, pobierz lub rozwidlenie i sklonuj przykładowe repozytorium fragmentów kodu, które zawiera pełny przykład. Repozytorium można również git clone wykonać w usłudze Azure Cloud Shell, aby zapoznać się z krokami przedstawionymi w tym przewodniku Szybki start.

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

    # requirements.txt
pymongo
python-dotenv

  3. 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

Skonfiguruj zmienne środowiskowe

Aby użyć wartości PARAMETRY POŁĄCZENIA w kodzie, ustaw tę wartość w środowisku lokalnym, w którym uruchomiono aplikację. Aby ustawić zmienną środowiskową, użyj preferowanego terminalu, aby uruchomić następujące polecenia:

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

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 of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

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 adventureworksproducts. 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"

Połączenie do interfejsu 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