Краткое руководство. Библиотека Azure Cosmos DB для NoSQL для Python

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

• .NET
• Node.js
• Java
• Python
• Go

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

Справочная документация по | API— пакет исходного кода | (PyPI) | Azure Developer CLI

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Учетная запись GitHub

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Интерфейс командной строки разработчика Azure
• Docker Desktop

Установка

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

Внимание

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

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

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

   azd auth login
   

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

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

   Примечание.

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

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

   

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

Клиентская библиотека доступна через индекс пакета Python в качестве библиотеки azure-cosmos .

1. Откройте терминал и перейдите в папку /src .

   cd ./src
   

2. Если пакет еще не установлен, установите azure-cosmos его с помощью pip install.

   pip install azure-cosmos
   

3. Кроме того, установите azure-identity пакет, если он еще не установлен.

   pip install azure-identity
   

4. Откройте и просмотрите файл src/requirements.txt , чтобы проверить наличие azure-cosmos и azure-identity записи.

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

Имя	Описание
CosmosClient	Этот класс является основным клиентским классом и используется для управления метаданными или базами данных на уровне учетной записи.
DatabaseProxy	Этот класс представляет базу данных в учетной записи.
ContainerProxy	Этот класс в основном используется для выполнения операций чтения, обновления и удаления в контейнере или элементов, хранящихся в контейнере.
PartitionKey	Этот класс представляет ключ логического раздела. Этот класс необходим для многих распространенных операций и запросов.

Примеры кода

• аутентификация клиента;
• Получение базы данных
• Получение контейнера
• Создание элемента
• Получение элемента
• Запрос элементов

Пример кода в шаблоне использует базу данных с именем cosmicworks и контейнером products. Контейнер products содержит такие сведения, как имя, категория, количество, уникальный идентификатор и флаг продажи для каждого продукта. Контейнер использует /category свойство в качестве ключа логического раздела.

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

Запросы приложений к большинству служб Azure должны быть авторизованы. DefaultAzureCredential Используйте тип в качестве предпочтительного способа реализации подключения без пароля между приложениями и Azure Cosmos DB для NoSQL. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения.

Внимание

Вы также можете авторизовать запросы к службам Azure с помощью паролей, строка подключения или других учетных данных напрямую. Однако этот подход следует использовать с осторожностью. Разработчики должны быть старательными, чтобы никогда не предоставлять эти секреты в небезопасном расположении. Любой, кто получает доступ к паролю или секретному ключу, может пройти проверку подлинности в службе базы данных. DefaultAzureCredential предлагает улучшенные преимущества управления и безопасности по сравнению с ключом учетной записи, чтобы разрешить проверку подлинности без пароля без риска хранения ключей.

В этом примере создается новый экземпляр CosmosClient типа и выполняется проверка подлинности с помощью экземпляра DefaultAzureCredential .

credential = DefaultAzureCredential()
client = CosmosClient(url=endpoint, credential=credential)

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

Используется client.get_database_client для извлечения существующей базы данных с именем cosmicworks.

database = client.get_database_client("cosmicworks")

Получение контейнера

Получение существующего products контейнера с помощью database.get_container_client.

container = database.get_container_client("products")

Создание элемента

Создайте новый объект со всеми элементами, которые необходимо сериализовать в JSON. В этом примере тип имеет уникальный идентификатор и поля для категории, имени, количества, цены и продажи. Создайте элемент в контейнере с помощью container.upsert_item. Этот метод "upserts" элемент фактически заменяет элемент, если он уже существует.

new_item = {
    "id": "70b63682-b93a-4c77-aad2-65501347265f",
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard",
    "quantity": 12,
    "sale": False,
}
created_item = container.upsert_item(new_item)

Чтение элемента

Выполните операцию чтения точек с помощью полей уникального идентификатора (id) и ключа секции. Используется container.read_item для эффективного извлечения определенного элемента.

existing_item = container.read_item(
    item="70b63682-b93a-4c77-aad2-65501347265f",
    partition_key="gear-surf-surfboards",
)

Элементы запроса

Выполнение запроса по нескольким элементам в контейнере с помощью container.GetItemQueryIterator. Найдите все элементы в указанной категории с помощью этого параметризованного запроса:

SELECT * FROM products p WHERE p.category = @category

queryText = "SELECT * FROM products p WHERE p.category = @category"
results = container.query_items(
    query=queryText,
    parameters=[
        dict(
            name="@category",
            value="gear-surf-surfboards",
        )
    ],
    enable_cross_partition_query=False,
)

Прокрутите результаты запроса.

items = [item for item in results]
output = json.dumps(items, indent=True)

Связанный контент

• Краткое руководство по .NET
• Краткое руководство по Node.js
• Краткое руководство для Java
• Краткое руководство по переходу

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

Пакет PyPI