Начало работы с Azure Cosmos DB для MongoDB и Python

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

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

Примечание.

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

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

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

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

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

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

   Примечание.

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

2. Создайте файл requirements.txt, который перечисляет пакеты PyMongo и python-dotenv. Пакет dotenv используется для считывания переменных среды из файла .env во время локальной разработки.

   # requirements.txt
   pymongo
   python-dotenv
   

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

   Windows

   # 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
   

   Linux / macOS

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

Подключение с помощью драйвера PyMongo к Azure Cosmos DB для MongoDB

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

Наиболее распространенный конструктор для MongoClient требует только host параметра, который в этой статье задан для переменной COSMOS_CONNECTION_STRING среды. В конструкторе можно использовать другие необязательные параметры и ключевые слова. Многие необязательные параметры также можно указать с параметром host . Если тот же параметр передается с параметром и в host качестве параметра, параметр имеет приоритет.

Сведения о проблемах подключения см. в руководстве по устранению неполадок.

Получение имени ресурса

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

Azure CLI

1. Создайте переменную оболочки для resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos"
   

2. Используйте команду az cosmosdb list, чтобы получить имя первой учетной записи Azure Cosmos DB в группе ресурсов и сохранить его в переменной оболочки accountName.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

PowerShell

1. Создайте переменную оболочки для RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos"
   

2. Используйте командлет Get-AzCosmosDBAccountKey, чтобы получить имя первой учетной записи Azure Cosmos DB в группе ресурсов и сохранить ее в переменной оболочки accountName.

   # Get the name of the first Azure Cosmos DB account in your resource group
   $ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
   

Портал

Пропустите этот шаг и используйте сведения для портала на следующем шаге.

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

Azure CLI

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

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

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

PowerShell

1. Найдите CONNECTION STRING (строка подключения) в списке ключей и строк подключения для учетной записи с помощью командлета Get-AzCosmosDBAccountKey.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary MongoDB Connection String"    
   

2. Запишите значение CONNECTION STRING. Эти учетные данные понадобятся позже.

Портал

1. Войдите на портал Azure.

2. Перейдите на существующую страницу учетной записи Azure Cosmos DB для MongoDB.

3. На странице учетной записи Azure Cosmos DB для MongoDB выберите пункт меню навигации по строке подключения.

4. Запишите значение для поля ОСНОВНАЯ СТРОКА ПОДКЛЮЧЕНИЯ. Вы будете использовать это значение на дальнейших этапах.

   

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

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

Windows

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

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env

Файл .env — это стандартный способ для хранения переменных среды в проекте. Создайте файл .env в корне проекта. Добавьте следующие строки в файл .env :

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Создание MongoClient с помощью строки подключения

1. Добавьте зависимости для ссылки на пакеты PyMongo и python-dotenv .

   import os
   import sys
   
   import pymongo
   from dotenv import load_dotenv
   

2. Определите новый экземпляр MongoClient класса с помощью конструктора и строка подключения считывания из переменной среды.

   load_dotenv()
   CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
   client = pymongo.MongoClient(CONNECTION_STRING)
   
   for prop, value in vars(client.options).items():
       print("Property: {}: Value: {} ".format(prop, value))
   

Дополнительные сведения о различных способах создания экземпляра MongoClient см. в разделе "Подключение к MongoClient".

Закрытие подключения MongoClient

Когда приложение завершится с подключением, не забудьте закрыть его. Вызов .close() должен осуществляться после выполнения всех вызовов базы данных.

client.close()

Использование клиентских классов MongoDB с Azure Cosmos DB для API для MongoDB

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

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

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

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

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

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

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

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

См. также

• Пакет PyPI
• Справочник по API

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

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

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