Начало работы с Azure Cosmos DB для NoSQL с помощью Python

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

В этой статье показано, как подключиться к Azure Cosmos DB для NoSQL с помощью пакета SDK для Python. После подключения можно выполнять операции с базами данных, контейнерами и элементами.

Пакет (PyPi) | Справочник по | APIИсходный код | библиотекиПредоставление отзывов

Предпосылки

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Учетная запись Azure Cosmos DB для NoSQL. Создайте API для учетной записи NoSQL.
• Python версии 3.7 или выше
• Интерфейс командной строки (CLI) Azure или Azure PowerShell

Настройка проекта

Создайте среду, в которой можно запустить код Python.

Виртуальная среда

В виртуальной среде можно установить пакеты Python в изолированной среде, не влияя на остальную часть системы.

Установите пакет Azure Cosmos DB SDK для Python для NoSQL в виртуальной среде.

pip install azure-cosmos

Контейнер разработки

Контейнер разработки — это предварительно настроенная среда, которую можно использовать для запуска кода Python.

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

• Visual Studio Code: клонируйте этот репозиторий на локальный компьютер и откройте папку с помощью расширения контейнеров разработки.

• GitHub Codespaces: откройте этот репозиторий в браузере, используя GitHub Codespace.

Установите SDK для Python для NoSQL в Azure Cosmos DB в контейнере разработки.

pip install azure-cosmos

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

В среде создайте файл app.py и добавьте в него следующий код:

import json
import os
import sys
import uuid

from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey

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

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

Чтобы подключиться к API для NoSQL Azure Cosmos DB, создайте экземпляр CosmosClient класса. Этот класс является начальной точкой для выполнения всех операций с базами данных.

Чтобы подключиться к API для NoSQL-учетной записи с помощью Microsoft Entra, используйте учетный объект безопасности. Тип основного элемента будет зависеть от того, где хостится код вашего приложения. Приведенная ниже таблица служит кратким справочным руководством.

Место выполнения приложения	Субъект безопасности
Локальный компьютер (разработка и тестирование)	Удостоверение пользователя или сервисный принципал
Лазурный	Управляемая идентичность
Серверы или клиенты вне Azure	Субъект-служба

Импорт Azure.Identity

Пакет azure-identity содержит основные функции проверки подлинности , общие для всех библиотек пакета SDK Azure.

Импортируйте пакет azure-identity в среду.

pip install azure-identity

Создайте CosmosClient с реализацией учетных данных по умолчанию

Если вы тестируете на локальном компьютере или приложение будет выполняться в службах Azure с прямой поддержкой управляемых удостоверений, получите маркер OAuth, создав экземпляр DefaultAzureCredential.

В вашем app.py:

• Получите конечную точку для подключения к учетной записи и задайте ее в качестве переменной COSMOS_ENDPOINTсреды.

• Импортируйте DefaultAzureCredential и создайте его экземпляр.

• Создайте новый экземпляр класса CosmosClient с конечной точкой и учетными данными в качестве параметров.

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

Внимание

Дополнительные сведения о том, как добавить правильную роль для работы DefaultAzureCredential, см. в статье Настройка управления доступом на основе ролей с помощью Microsoft Entra ID для учетной записи Azure Cosmos DB. В частности, ознакомьтесь с разделом по созданию ролей и назначению их основному идентификатору.

Создайте ваше приложение

При создании приложения код будет в основном взаимодействовать с четырьмя типами ресурсов:

• API для учетной записи NoSQL, которое является уникальным пространством имен верхнего уровня для данных Azure Cosmos DB.

• Базы данных, которые упорядочивают контейнеры в учетной записи.

• Контейнеры, содержащие набор отдельных элементов в базе данных.

• Элементы, представляющие документ JSON в контейнере.

На следующей схеме показана связь между этими ресурсами.

Иерархическая схема с учетной записью Azure Cosmos DB в верхней части. У учетной записи есть два дочерних узла базы данных. Один из узлов базы данных включает в себя два узла-контейнера, являющихся дочерними. Другой узел базы данных содержит один дочерний узел-контейнер. У этого одного узла контейнера есть три дочерних узла.

Каждый тип ресурса представлен одним или несколькими связанными классами Python. Ниже приведен список наиболее распространенных классов для синхронного программирования. (Существуют аналогичные классы для асинхронного программирования в пространстве имен azure.cosmos.aio .)

Класс	Описание
CosmosClient	Этот класс является логическим представлением службы Azure Cosmos DB на стороне клиента. Этот клиентский объект позволяет настраивать и выполнять запросы к службе.
DatabaseProxy	Интерфейс к базе данных, которая может или не может существовать в службе. Этот класс не следует создавать напрямую. Вместо этого следует использовать метод CosmosClient get_database_client .
ContainerProxy	Интерфейс для взаимодействия с определенным контейнером Cosmos DB. Этот класс не следует создавать напрямую. Вместо этого используйте метод DatabaseProxy get_container_client для получения существующего контейнера или метода create_container для создания нового контейнера.

Сведения об использовании каждого из этих классов для создания приложения приведены в следующих руководствах.

Руководство	Описание
Создание базы данных	Создание баз данных
Создание контейнера	Создание контейнеров

См. также

• PyPi
• Справочник по API
• Исходный код библиотеки
• Обратная связь

Следующие шаги

Создание базы данных в Azure Cosmos DB для NoSQL с помощью Python