Поделиться через

Краткое руководство. Azure Cosmos DB для MongoDB для Python с драйвером MongoDB

  • Статья

Область применения: MongoDB

Начало работы с MongoDB для создания баз данных, коллекций и документов в ресурсе Azure Cosmos DB. Выполните следующие действия, чтобы развернуть минимальное решение в вашей среде с помощью Интерфейса командной строки разработчика Azure.

Справочная документация | по API для MongoDB для пакета Pymongo для | Azure Developer CLI

Необходимые компоненты

Установка

Разверните контейнер разработки этого проекта в вашей среде. Затем используйте интерфейс командной строки разработчика Azure (azd) для создания учетной записи Azure Cosmos DB для MongoDB и развертывания контейнерного примера приложения. Пример приложения использует клиентская библиотека для управления, создания, чтения и запроса примеров данных.

Открытие в GitHub Codespaces

Открытие в контейнере разработки

Внимание

Учетные записи GitHub включают право на хранение и основные часы без затрат. Дополнительные сведения см . в разделе о хранилище и основных часах для учетных записей GitHub.

  1. Откройте терминал в корневом каталоге проекта.

  2. Проверка подлинности в интерфейсе командной строки разработчика Azure с помощью azd auth login. Выполните действия, указанные средством для проверки подлинности в CLI с помощью предпочитаемых учетных данных Azure.

    azd auth login

  3. Используется azd init для инициализации проекта.

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

    Примечание.

    В этом кратком руководстве используется репозиторий шаблонов GitHub в azure-samples/cosmos-db-mongodb-python-quickstart . Интерфейс командной строки разработчика Azure автоматически клонирует этот проект на компьютер, если он еще не существует.

  4. Во время инициализации настройте уникальное имя среды.

    Совет

    Имя среды также будет использоваться в качестве имени целевой группы ресурсов. В этом кратком руководстве рекомендуется использовать msdocs-cosmos-db.

  5. Разверните учетную запись Azure Cosmos DB с помощью azd up. Шаблоны Bicep также развертывают пример веб-приложения.

    azd up

  6. В процессе подготовки выберите подписку и нужное расположение. Дождитесь завершения процесса подготовки. Процесс может занять около пяти минут.

  7. После завершения подготовки ресурсов Azure в выходные данные будет включен URL-адрес работающего веб-приложения.

    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. Используйте URL-адрес консоли для перехода к веб-приложению в браузере. Просмотрите выходные данные запущенного приложения.

    Снимок экрана: работающее веб-приложение.

Установка клиентской библиотеки

  1. Создайте файл в каталоге requirements.txt приложений, который перечисляет пакеты PyMongo и python-dotenv .

    # requirements.txt
pymongo
python-dotenv

  2. Создайте виртуальную среду и установите пакеты.

    # 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

Объектная модель

Давайте рассмотрим иерархию ресурсов в API для MongoDB и объектную модель, используемую для создания и доступа к этим ресурсам. Azure Cosmos DB создает ресурсы в иерархии, состоящей из учетных записей, баз данных, коллекций и документов.

Схема иерархии Azure Cosmos DB с учетными записями, базами данными, коллекциями и документами.

Каждый тип ресурса представлен классом Python. Ниже приведены наиболее распространенные классы:

  • MongoClient — первый шаг при работе с PyMongo — создание MongoClient для подключения к API Azure Cosmos DB для MongoDB. Этот клиентский объект позволяет настраивать и выполнять запросы к службе.

  • База данных — API Azure Cosmos DB для MongoDB может поддерживать одну или несколько независимых баз данных.

  • Коллекция — база данных может содержать одну или несколько коллекций. Коллекция представляет собой группу документов, хранящихся в MongoDB, и можно рассматривать как примерно эквивалент таблицы в реляционной базе данных.

  • Документ — это набор пар "ключ-значение". Документы имеют динамическую схему. Динамическая схема означает, что документы в одной коллекции не должны иметь одинаковый набор полей или структуры. И общие поля в документах коллекции могут содержать различные типы данных.

Дополнительные сведения об иерархии сущностей см. в статье Модель ресурсов Azure Cosmos DB.

Примеры кода

В этой статье описан пример кода, который создает базу данных adventureworks с коллекцией products. Коллекция products предназначена для хранения сведений о продукте, таких как имя, категория, количество и индикатор продажи. Каждый продукт также содержит уникальный идентификатор. Полный пример кода находится по адресу https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/.

Для приведенных ниже действий база данных не будет использовать сегментирование и отображает синхронное приложение с помощью драйвера PyMongo . Для асинхронных приложений используйте драйвер двигателя .

аутентификация клиента;

  1. В каталоге проекта создайте файл run.py . В редакторе добавьте инструкции для ссылки на используемые пакеты, включая пакеты PyMongo и python-dotenv.

    import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv

  2. Получите сведения о подключении из переменной среды, определенной в env-файле .

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

  3. Определите константы, которые будут использоваться в коде.

    DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Подключение к API Azure Cosmos DB для MongoDB

Используйте объект MongoClient для подключения к ресурсу Azure Cosmos DB для MongoDB. Этот метод подключения возвращает ссылку на базу данных.

client = pymongo.MongoClient(CONNECTION_STRING)

Получение базы данных

Проверьте, существует ли база данных с помощью метода list_database_names . Если база данных не существует, используйте команду расширения базы данных для создания базы данных с указанной подготовленной пропускной способностью.

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

Получение коллекции

Проверьте, существует ли коллекция с помощью метода list_collection_names . Если коллекция не существует, используйте команду расширения для создания коллекции.

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

Создание индекса

Создайте индекс с помощью команды расширения коллекции обновлений. Можно также задать индекс в команде расширения создания коллекции. Задайте для индекса name свойство в этом примере, чтобы можно было позже сортировать метод сортировки класса курсора по имени продукта.

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

Создание документа

Создайте документ со свойствами продукта для adventureworks базы данных:

  • Свойство category. Это свойство можно использовать в качестве ключа логической секции.
  • Свойство name.
  • Свойство quantity для инвентаризации.
  • Свойство sale, указывающее, участвует ли продукт в распродаже.
"""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))

Создайте документ в коллекции, вызвав операцию уровня коллекции update_one. В этом примере вместо создания нового документа вы добавите upsert. Upsert не требуется в этом примере, так как имя продукта является случайным. Тем не менее, рекомендуется использовать upsert в случае, если вы запускаете код несколько раз, и имя продукта совпадает.

Результат update_one операции содержит _id значение поля, которое можно использовать в последующих операциях. Свойство _id было создано автоматически.

Получение документа

Используйте метод find_one для получения документа.

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

В Azure Cosmos DB можно выполнять менее затратную операцию чтения точек с помощью уникального идентификатора (_id) и ключа секции.

Запрос документов

После вставки документа можно выполнить запрос, чтобы получить все документы, соответствующие определенному фильтру. В этом примере выполняется поиск всех документов, соответствующих определенной категории: gear-surf-surfboards. После определения запроса вызовите Collection.find результат Cursor , а затем используйте сортировку.

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

Устранение неполадок:

  • Если возникает ошибка, например The index path corresponding to the specified order-by item is excluded., убедитесь, что вы создали индекс.

Выполнение кода

Это приложение создает API для базы данных и коллекции MongoDB и создает документ, а затем считывает тот же документ обратно. Наконец, в примере возникает запрос, возвращающий документы, соответствующие указанной категории продукта. При каждом шаге пример выводит сведения в консоль о выполненных шагах.

Чтобы запустить приложение, перейдите в каталог приложения и запустите его с помощью терминала.

python run.py

Выходные данные приложения должны выглядеть следующим образом:


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}

Очистка ресурсов

Если учетная запись Azure Cosmos DB для NoSQL больше не нужна, можно удалить соответствующую группу ресурсов.

Используйте команду az group delete, чтобы удалить группу ресурсов.

az group delete --name $resourceGroupName