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

  • Статья

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

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

Примечание.

Пример фрагментов кода доступен на сайте GitHub в качестве проекта Python.

В этом кратком руководстве вы будете взаимодействовать с API Azure Cosmos DB для MongoDB с помощью одного из клиентских драйверов MongoDB с открытым кодом для Python, PyMongo. Кроме того, вы будете использовать команды расширения MongoDB, которые помогут вам создать и получить ресурсы базы данных, относящиеся к модели емкости Azure Cosmos DB.

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

Проверка предварительных условий

  • В окне терминала или командной строки запустите python --version проверка, что у вас есть последняя версия Python.
  • Выполните az --version (Azure CLI) или Get-Module -ListAvailable Az* (Azure PowerShell), чтобы убедиться, что установлены соответствующие средства командной строки Azure.

Установка

В этом разделе описывается создание учетной записи Azure Cosmos DB и настройка проекта, использующего пакет npm MongoDB.

Создание учетной записи Azure Cosmos DB

В этом кратком руководстве будет создана отдельная учетная запись Azure Cosmos DB с помощью API для MongoDB.

  1. Создайте переменные оболочки для accountName, resourceGroupName и 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. Если вы еще этого не сделали, войдите в Azure CLI с помощью команды az login.

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

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

  4. az cosmosdb create Используйте команду для создания новой учетной записи Azure Cosmos DB для MongoDB с параметрами по умолчанию.

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

Получение строки подключения MongoDB

  1. Найдите API для MongoDB строка подключения из списка строка подключения для учетной записи с az cosmosdb keys list помощью команды.

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

  2. Скопируйте значения PRIMARY KEY (первичный ключ). Эти учетные данные понадобятся позже.

Создание нового приложения Python

  1. Создайте пустую папку с помощью предпочтительного терминала и измените каталог на папку.

    Примечание.

    Если требуется просто готовый код, скачайте или вилку и клонируйте пример репозитория фрагментов кода, имеющего полный пример. Вы также git clone можете использовать репозиторий в Azure Cloud Shell, чтобы выполнить действия, описанные в этом кратком руководстве.

  2. Создайте файл requirements.txt, который содержит пакеты PyMongo и python-dotenv.

    # requirements.txt
pymongo
python-dotenv

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

    # 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

Настройка переменных среды

Чтобы использовать значения CONNECTION STRING в коде, задайте это значение в локальной среде, в которой запущено приложение. Чтобы задать переменную среды, используйте предпочтительный терминал для выполнения следующих команд:

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

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

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

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

Каждый тип ресурса представлен классом 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