Краткое руководство. Создание приложения API для таблиц с помощью пакета SDK для Python и Azure Cosmos DB

ПРИМЕНИМО К: Таблица

В этом кратком руководстве показано, как получить доступ к API Azure Cosmos DB для таблиц из приложения Python. Azure Cosmos DB для таблицы — это бессхемное хранилище данных, позволяющее приложениям хранить структурированные данные NoSQL в облаке. Поскольку данные хранятся в структуре без схемы, при добавлении в таблицу объекта с новым атрибутом в нее автоматически добавляются новые свойства (столбцы). Приложения Python могут получить доступ к Azure Cosmos DB для таблиц с помощью пакета SDK azure Data Tables для Python .

Предварительные требования

Пример приложения написан на Python 3.7 или более поздней версии, хотя принципы применимы ко всем приложениям Python 3.7 и более поздних версий. Можно использовать Visual Studio Code в качестве IDE.

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

Пример приложения

Пример приложения для этого учебника можно клонировать или скачать из репозитория https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.

git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git

В репозиторий примеров включены папки 1-starter-app и 2-completed-app . 1-starter-app имеет некоторые функциональные возможности, чтобы завершить со строками с пометкой "#TODO". Фрагменты кода, показанные в этой статье, являются предлагаемыми дополнениями для завершения 1-starter-app.

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

Снимок экрана готового приложения, на котором показаны данные, хранящиеся в таблице Azure Cosmos DB с помощью API для таблицы.

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

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

Войдите в портал Azure и выполните следующие действия, чтобы создать учетную запись Azure Cosmos DB.

Инструкции Снимок экрана
На портале Azure выполните следующие действия:
  1. В верхней части страницы портала в строке поиска введите "cosmos db".
  2. В открывшемся под строкой меню в разделе Службы выберите Azure Cosmos DB.
Снимок экрана: использование поля поиска на верхней панели инструментов для поиска учетных записей Azure Cosmos DB в Azure.
На странице Azure Cosmos DB выберите +Создать. Снимок экрана: расположение кнопки
На странице Выберите вариант API параметр выберите вариант Таблица Azure. Снимок экрана, на котором в качестве правильного варианта выбора показан параметр таблицы Azure.
На странице Создание учетной записи Azure Cosmos DB — таблица Azure заполните форму, как описано ниже.
  1. Создайте новую группу ресурсов для учетной записи хранения с именем rg-msdocs-tables-sdk-demo, выбрав ссылку Создать в разделе Группа ресурсов.
  2. Присвойте учетной cosmos-msdocs-tables-sdk-demo-XYZ записи хранения имя , где XYZ — это любые три случайных символа, чтобы создать уникальное имя учетной записи. Имена учетных записей Azure Cosmos DB должны быть длиной от 3 до 44 символов и могут содержать только строчные буквы, цифры и символ дефиса (-).
  3. Выберите регион для вашей учетной записи хранения.
  4. Выберите для производительности вариант Стандартная.
  5. В разделе Режим емкости выберите для этого примера вариант Подготовленная пропускная способность.
  6. В разделе Применение скидки на основе категории "Бесплатный" для этого примера нажмите Применить.
  7. Нажмите кнопку Просмотр и создание в нижней части экрана, а затем выберите Создать на экране сводки, чтобы создать учетную запись Azure Cosmos DB. Это может занять несколько минут.
Снимок экрана: заполнение полей на странице создания учетной записи Azure Cosmos DB.

2\. Создание таблицы

Затем необходимо создать таблицу в учетной записи Azure Cosmos DB, чтобы приложение использовало. В отличие от традиционной базы данных, свойства (столбцы) в таблице указывать не требуется — нужно указать только имя таблицы. При загрузке данных в таблицу свойства (столбцы) автоматически создаются по мере необходимости.

В портал Azure выполните следующие действия, чтобы создать таблицу в учетной записи Azure Cosmos DB.

Инструкции Снимок экрана
На портале Azure перейдите к странице общих сведений об учетной записи Azure Cosmos DB.
  1. Вы можете перейти на страницу обзора учетной записи Azure Cosmos DB, введя имя (cosmos-msdocs-tables-sdk-demo-XYZ) учетной записи Azure Cosmos DB в верхней строке поиска и просмотрев заголовок ресурсов.

  2. Выберите имя учетной записи Azure Cosmos DB, чтобы перейти на страницу Обзор .

Снимок экрана: использование поля поиска на верхней панели инструментов для поиска учетной записи Azure Cosmos DB.
На странице Обзор выберите +Добавить таблицу. Диалоговое окно Новая таблица будет выдвигается с правой стороны страницы. Снимок экрана, на котором показано положение кнопки
В диалоговом окне Новая таблица укажите данные, как описано ниже.
  1. В качестве идентификатора таблице введите WeatherData. Это значение является именем таблицы.
  2. Выберите Вручную в разделе Пропускная способность таблицы для этого примера.
  3. В разделе предполагаемого количества запросов в секунду оставьте значение по умолчанию (400).
  4. Нажмите кнопку ОК, чтобы создать таблицу.
Снимок экрана: диалоговое окно

3. Получение строки подключения Azure Cosmos DB

Для доступа к таблицам в Azure Cosmos DB приложению требуется строка подключения к таблице для учетной записи хранения Cosmos DB. Строку подключения можно получить с помощью портала Azure, Azure CLI или Azure PowerShell.

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

4\. Установка пакета SDK таблиц данных Azure для Python

После создания учетной записи Azure Cosmos DB необходимо установить пакет SDK таблиц данных Microsoft Azure для Python. Дополнительные сведения по установке пакета SDK см. в файле README.md в репозитории GitHub на странице пакета SDK для таблиц данных для Python.

Установка клиентской библиотеки таблиц Azure для Python с помощью PIP:

pip install azure-data-tables

Не забудьте также установить requirements.txt в папках 1-starter-app или 2-completed-app .


5. Настройка клиента таблицы в ENV-файле

Скопируйте строку подключения учетной записи Azure Cosmos DB с портала Azure и создайте объект TableServiceClient, используя скопированную строку подключения. Перейдите в папку 1-starter-app или 2-completed-app . Независимо от того, с какого приложения вы начинаете работу, необходимо определить переменные среды в .env файле.

# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"

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

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

self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)

6. Реализация операций с таблицами Azure Cosmos DB

Все операции с таблицами Azure Cosmos DB для примера приложения реализуются в TableServiceHelper классе, расположенном во вспомогательном файле в каталоге веб-приложения . Чтобы работать с объектами в клиентской TableServiceClient библиотеке azure.data.tables для Python, необходимо импортировать класс в верхней части этого файла.

from azure.data.tables import TableServiceClient

В начале класса TableServiceHelper добавьте конструктор и переменную-элемент для объекта TableClient, чтобы разрешить внедрение объекта TableClient в класс.

def __init__(self, table_name=None, conn_str=None):
    self.table_name = table_name if table_name else os.getenv("table_name")
    self.conn_str = conn_str if conn_str else os.getenv("conn_str")
    self.table_service = TableServiceClient.from_connection_string(self.conn_str)
    self.table_client = self.table_service.get_table_client(self.table_name)

Фильтрация строк, возвращенных из таблицы

Для фильтрации строк, возвращаемых из таблицы, можно передать строку фильтра стиля OData в метод query_entities. Например, если требуется получить все показатели погоды в Чикаго с полуночи 1 июля до полуночи 2 июля 2021 года (включительно), передается следующая строка фильтра.

PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'

Связанные операторы фильтров OData можно просмотреть на веб-сайте azure-data-tables в разделе Написание фильтров.

Когда параметр request.args передается в метод query_entity в классе TableServiceHelper, он создает строку фильтра для каждого значения свойства, отличного от NULL. Затем он создает объединенную строку фильтра, объединяя все значения вместе с помощью предложения and. Эта объединенная строка фильтра передается методу query_entitiesTableClient объекта , и возвращаются только строки, соответствующие строке фильтра. Аналогичный метод можно использовать в коде для создания подходящих строк фильтра в соответствии с требованиями приложения.

def query_entity(self, params):
    filters = []
    if params.get("partitionKey"):
        filters.append("PartitionKey eq '{}'".format(params.get("partitionKey")))
    if params.get("rowKeyDateStart") and params.get("rowKeyTimeStart"):
        filters.append("RowKey ge '{} {}'".format(params.get("rowKeyDateStart"), params.get("rowKeyTimeStart")))
    if params.get("rowKeyDateEnd") and params.get("rowKeyTimeEnd"):
        filters.append("RowKey le '{} {}'".format(params.get("rowKeyDateEnd"), params.get("rowKeyTimeEnd")))
    if params.get("minTemperature"):
        filters.append("Temperature ge {}".format(params.get("minTemperature")))
    if params.get("maxTemperature"):
        filters.append("Temperature le {}".format(params.get("maxTemperature")))
    if params.get("minPrecipitation"):
        filters.append("Precipitation ge {}".format(params.get("minPrecipitation")))
    if params.get("maxPrecipitation"):
        filters.append("Precipitation le {}".format(params.get("maxPrecipitation")))
    return list(self.table_client.query_entities(" and ".join(filters)))

Вставка данных с помощью объекта TableEntity

Самый простой способ добавить данные в таблицу — использовать объект TableEntity. В этом примере данные сопоставляются из объекта входной модели с объектом TableEntity. Свойства входного объекта, представляющего имя метеостанции и дату и время наблюдения, PartitionKey сопоставляются со свойствами и соответственно RowKey , которые вместе образуют уникальный ключ для строки в таблице. Затем дополнительные свойства объекта входной модели сопоставляются со свойствами словаря объекта TableEntity. Наконец, для вставки данных в таблицу используется метод create_entity объекта TableClient.

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

def insert_entity(self):
    entity = self.deserialize()
    return self.table_client.create_entity(entity)
    
@staticmethod
def deserialize():
    params = {key: request.form.get(key) for key in request.form.keys()}
    params["PartitionKey"] = params.pop("StationName")
    params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
    return params

Выполнение операции upsert с данными с помощью объекта TableEntity

При попытке вставить в таблицу строку, сочетание ключа секции и ключа строки которой уже существует в этой таблице, будет выдано сообщение об ошибке. По этой причине часто предпочтительнее использовать upsert_entity вместо метода при добавлении create_entity строк в таблицу. Если заданное сочетание ключа секции и ключа строки уже существует в таблице, upsert_entity метод обновляет существующую строку. В противном случае строка добавляется в таблицу.

def upsert_entity(self):
    entity = self.deserialize()
    return self.table_client.upsert_entity(entity)
    
@staticmethod
def deserialize():
    params = {key: request.form.get(key) for key in request.form.keys()}
    params["PartitionKey"] = params.pop("StationName")
    params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
    return params

Выполнение операции вставки или upsert с данными с помощью свойств переменной

Одним из преимуществ использования Azure Cosmos DB для таблицы является то, что если объект, загружаемый в таблицу, содержит новые свойства, эти свойства автоматически добавляются в таблицу и значения, хранящиеся в Azure Cosmos DB. Нет необходимости выполнять инструкции DDL, такие как ALTER TABLE, чтобы добавить столбцы, как в традиционной базе данных.

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

Чтобы вставить или вставить такой объект с помощью API для таблицы, сопоставьте свойства расширяемого объекта с TableEntity объектом и используйте create_entity методы или upsert_entity в TableClient объекте соответствующим образом.

В примере приложения функция upsert_entity также может реализовать функцию вставки или upsert данных с помощью свойств переменной

def insert_entity(self):
    entity = self.deserialize()
    return self.table_client.create_entity(entity)

def upsert_entity(self):
    entity = self.deserialize()
    return self.table_client.upsert_entity(entity)

@staticmethod
def deserialize():
    params = {key: request.form.get(key) for key in request.form.keys()}
    params["PartitionKey"] = params.pop("StationName")
    params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
    return params

Обновление сущности

Сущности можно обновить, вызвав метод update_entity объекта TableClient.

В примере приложения этот объект передается в метод upsert_entity класса TableClient. Он обновляет объект сущности и использует метод upsert_entity, чтобы сохранить обновления в базе данных.

def update_entity(self):
    entity = self.update_deserialize()
    return self.table_client.update_entity(entity)
    
@staticmethod
def update_deserialize():
    params = {key: request.form.get(key) for key in request.form.keys()}
    params["PartitionKey"] = params.pop("StationName")
    params["RowKey"] = params.pop("ObservationDate")
    return params

Удаление сущности

Чтобы удалить сущность из таблицы, вызовите метод delete_entity объекта TableClient с ключом секции и ключом строки объекта.

def delete_entity(self):
    partition_key = request.form.get("StationName")
    row_key = request.form.get("ObservationDate")
    return self.table_client.delete_entity(partition_key, row_key)

7\. Выполнение кода

Запустите пример приложения для взаимодействия с Azure Cosmos DB для таблицы. Например, начиная с папки 2-completed-app с установленными требованиями можно использовать:

python3 run.py webapp

Дополнительные сведения о запуске примера приложения см. в файле README.md в корневом каталоге репозитория .

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

Снимок экрана: приложение с расположением кнопок, используемых для вставки данных в Azure Cosmos DB с помощью API таблиц.

При нажатии кнопки Вставить с помощью сущности таблицы открывается диалоговое окно, в котором можно выполнить операцию вставки или upsert для новой строки с помощью объекта TableEntity.

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

При нажатии кнопки Вставить с помощью расширяемых данных откроется диалоговое окно, позволяющее вставить объект с настраиваемыми свойствами, демонстрируя, как Azure Cosmos DB для таблицы автоматически добавляет свойства (столбцы) в таблицу при необходимости. Чтобы добавить одно или несколько новых свойств и продемонстрировать эту возможность, воспользуйтесь кнопкой Добавить настраиваемое поле.

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

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

  • Для папки с примером 1-starter-app необходимо по крайней мере завершить код функции для submit_transaction работы примера вставки данных.

  • Пример данных загружается из файла sample_data.json . Переменная project_root_path.env сообщает приложению, где найти этот файл. Например, если вы запускаете приложение из папки 1-starter-app или 2-completed-app , задайте значение project_root_path "" (пусто).

Снимок экрана приложения, на котором показано расположение кнопки

В верхнем меню выберите пункт Фильтрация результатов для отображения страницы "Фильтрация результатов". На этой странице заполните условия фильтра, чтобы продемонстрировать, как можно создать предложение фильтра и передать его в Azure Cosmos DB для таблицы.

Снимок экрана приложения, на котором показана страница

Очистка ресурсов

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

Группу ресурсов можно удалить на портале Azure, выполнив следующие действия.

Инструкции Снимок экрана
Чтобы перейти в группу ресурсов, в строке поиска введите ее имя. На вкладке Группы ресурсов выберите имя нужной группы. Снимок экрана, на котором показано, как найти группу ресурсов.
Выберите Удалить группу ресурсов на панели инструментов в верхней части страницы группы ресурсов. Снимок экрана, на котором показано расположение кнопки
В правой части экрана появится диалоговое окно с запросом подтвердить удаление группы ресурсов.
  1. В текстовом поле введите полное имя группы ресурсов, чтобы подтвердить удаление.
  2. Нажмите кнопку Удалить в нижней части страницы.
Снимок экрана, на котором показано диалоговое окно подтверждения удаления группы ресурсов.

Дальнейшие действия

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