Краткое руководство: клиентская библиотека Azure Cosmos DB для Apache Cassandra для Python

2025-07-21
Применяется к: ✅ Apache Cassanda

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

Справочная документация по | APIИсходный код | библиотекиПакет (PyPI)

Предпосылки

подписка Azure
- Если у вас нет подписки на Azure, создайте бесплатную учетную запись перед началом.

Последняя версия Azure CLI в Azure Cloud Shell.
- Если вы предпочитаете локально запускать справочные команды CLI, войдите в Azure CLI с помощью az login команды.

Python 3.12 или более поздней версии

Настройка

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

Создать аккаунт

Сначала создайте API для учетной записи Apache Cassandra. После создания учетной записи создайте пространство ключей и ресурсы для таблицы.

Azure CLI
Портал Azure

Если у вас еще нет целевой группы ресурсов, используйте az group create команду для создания новой группы ресурсов в подписке.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```
az cosmosdb create Используйте команду для создания новой учетной записи Azure Cosmos DB для Apache Cassandra с параметрами по умолчанию.
```
az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"
```

Создайте новое пространство ключей с именем cosmicworks с помощью az cosmosdb cassandra keyspace create.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Создайте новый объект JSON для представления схемы с помощью команды Bash с несколькими строками. Затем используйте az cosmosdb cassandra table create команду, чтобы создать новую таблицу с именем products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Войдите на портал Azure (https://portal.azure.com).
Введите Azure Cosmos DB в глобальной строке поиска.
В службах выберите Azure Cosmos DB.
В области Azure Cosmos DB выберите "Создать", а затем Azure Cosmos DB для Apache Cassandra на вкладке "Другие ".
Выберите тип учетной записи учетная запись базы данных единицы запроса (RU).

В области "Основные сведения" настройте следующие параметры и нажмите кнопку "Проверить и создать".

	Ценность
Тип рабочей нагрузки	Обучение
Подписка	Выберите подписку Azure.
Группа ресурсов	Создание новой группы ресурсов или выбор существующей группы ресурсов
Имя аккаунта	Укажите глобально уникальное имя
Зоны доступности	Отключить
Местоположение	Выбор поддерживаемого региона Azure для подписки

Подсказка

Вы можете оставить любые не указанные параметры значениями по умолчанию. Вы также можете настроить учетную запись, чтобы ограничить общую пропускную способность учетной записи до 1000 единиц запросов в секунду (ЕЗ/с) или включить бесплатный уровень для минимизации затрат.

На панели "Проверка и создание" дождитесь успешной проверки учетной записи и нажмите кнопку "Создать".
Портал автоматически переходит в область развертывания. Дождитесь завершения развертывания.
После завершения развертывания выберите "Перейти к ресурсу" , чтобы перейти к новой учетной записи API для Apache Cassandra.
В меню ресурсов выберите параметр Обозревателя данных .
В обозревателе данных выберите +Создать таблицу.

В диалоговом окне "Добавить таблицу " настройте следующие параметры и нажмите кнопку "ОК".

	Ценность
Пространство ключей	Создать
Имя пространства ключей	`cosmicworks`
Имя таблицы	`product`
Схема таблицы	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Подсказка

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

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

Теперь получите пароль для клиентской библиотеки для создания подключения к недавно созданной учетной записи.

Azure CLI
Портал Azure

Используйте az cosmosdb show, чтобы получить точку контакта и имя пользователя для учетной записи.
```
az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"
```
Запишите значение свойств contactPoint и username из вывода предыдущих команд. Эти свойства представляют собой контактную точку и имя пользователя , которое вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.

Используйте az cosmosdb keys list для получения ключей для учетной записи.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Запишите значение primaryMasterKey свойства из выходных данных предыдущих команд. Это значение свойства — это пароль , который вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.

Подготовка среды разработки

Затем настройте среду разработки с новым проектом и клиентской библиотекой. Этот шаг является последним обязательным предварительным условием, прежде чем перейти к остальной части этого руководства.

Начните в пустом каталоге.
cassandra-driver Импортируйте пакет из индекса пакетов Python (PyPI).
```
pip install cassandra-driver
```
Создайте файл app.py.

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

	Описание
`Cluster`	Представляет определенное подключение к кластеру

Проверка подлинности клиента

Начните с проверки подлинности клиента с помощью учетных данных, собранных ранее в этом руководстве.

Откройте файл app.py в интегрированной среде разработки (IDE).
Импортируйте следующие типы из cassandra-driver модуля:
- cassandra.cluster.Cluster
- cassandra.auth.PlainTextAuthProvider
```
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
```
Импортируйте следующие типы из ssl модуля:
- ssl.PROTOCOL_TLS_CLIENT
- ssl.SSLContext
- ssl.CERT_NONE
```
from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
```
Создайте строковые переменные для учетных данных, собранных ранее в этом руководстве. Присвойте переменным usernamepasswordи contactPoint.
```
username = "<username>"
password = "<password>"
contactPoint = "<contact-point>"
```
Настройте SSLContext, создав новую переменную с именем ssl_context, задав протокол PROTOCOL_TLS_CLIENT, отключив проверку имени узла и установив режим проверки CERT_NONE.
```
ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
ssl_context.check_hostname = False
ssl_context.verify_mode = CERT_NONE
```
Создайте объект PlainTextAuthProvider с учетными данными, указанными на предыдущих шагах. Сохраните результат в переменной под названием auth_provider.
```
auth_provider = PlainTextAuthProvider(username=username, password=password)
```
Cluster Создайте объект с помощью учетных данных и переменных конфигурации, созданных на предыдущих шагах. Сохраните результат в переменной под названием cluster.
```
cluster = Cluster([contactPoint], port=10350, auth_provider=auth_provider, ssl_context=ssl_context)
```
Подключение к кластеру.
```
session = cluster.connect("cosmicworks")
```

Предупреждение

Полная проверка уровня транспорта (TLS) отключена в этом руководстве для упрощения проверки подлинности. Для рабочих развертываний полностью включите проверку.

Обновление-вставка данных

Затем переведите новые данные в таблицу. Upserting гарантирует, что данные создаются или заменяются соответствующим образом в зависимости от того, существуют ли те же данные в таблице.

Создайте новую строковую переменную insertQuery с языковым запросом Cassandra (CQL) для вставки новой строки данных.
```
insertQuery = """
INSERT INTO
    product (id, name, category, quantity, price, clearance)
VALUES
    (%(id)s, %(name)s, %(category)s, %(quantity)s, %(price)s, %(clearance)s)
"""
```

Создайте объект с различными свойствами нового продукта и сохраните его в переменной с именем params.

params = {
    "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "name": "Yamba Surfboard",
    "category": "gear-surf-surfboards",
    "quantity": 12,
    "price": 850.00,
    "clearance": False
}

Используйте функцию execute для выполнения запроса с указанными параметрами.
```
session.execute(insertQuery, params)
```

Чтение данных

Затем считывайте данные, которые ранее были добавлены в таблицу.

Создайте новую строковую переменную с именем readQuery, содержащую CQL-запрос, который выбирает элементы с тем же полем id.
```
readQuery = "SELECT * FROM product WHERE id = %s LIMIT 1"
```
Создайте строковую переменную id с тем же значением, что и продукт, созданный ранее в этом руководстве.
```
id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
```
Используйте функцию execute для выполнения запроса, хранящегося в readQuery, передав переменную id в качестве аргумента. Сохраните результат в переменной под названием readResults.
```
readResults = session.execute(readQuery, (id,))
```
Используйте функцию one получения ожидаемого единого результата. Сохраните этот один результат в переменной с именем matchedProduct.
```
matchedProduct = readResults.one()
```

Запрос данных

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

Создайте строковые переменные с именем findQuery и category с помощью запроса CQL и обязательного параметра.
```
findQuery = "SELECT * FROM product WHERE category = %s ALLOW FILTERING"
category = "gear-surf-surfboards"
```
Используйте две строковые переменные и execute функцию для запроса нескольких результатов. Сохраните результат этого запроса в переменной с именем findResults.
```
findResults = session.execute(findQuery, (category,))
```
for Используйте цикл для итерации результатов запроса.
```
for row in findResults:
    # Do something here with each result
```

Запустите код

Запустите созданное приложение с помощью терминала в каталоге приложения.

python app.py

Очистите ресурсы

Если учетная запись больше не нужна, удалите учетную запись из подписки Azure, удалив ресурс.

Azure CLI
Портал Azure

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

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

Обзор Azure Cosmos DB для Apache Cassandra