Краткое руководство. Создание приложения 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 для таблицы.
1\. Создание учетной записи Azure Cosmos DB
Сначала необходимо создать учетную запись API таблиц Azure Cosmos DB, которая будет содержать таблицы, используемые в приложении. Создайте учетную запись с помощью портал Azure, Azure CLI или Azure PowerShell.
Войдите в портал Azure и выполните следующие действия, чтобы создать учетную запись Azure Cosmos DB.
2\. Создание таблицы
Затем необходимо создать таблицу в учетной записи Azure Cosmos DB, чтобы приложение использовало. В отличие от традиционной базы данных, свойства (столбцы) в таблице указывать не требуется — нужно указать только имя таблицы. При загрузке данных в таблицу свойства (столбцы) автоматически создаются по мере необходимости.
В портал Azure выполните следующие действия, чтобы создать таблицу в учетной записи Azure Cosmos DB.
3. Получение строки подключения Azure Cosmos DB
Для доступа к таблицам в Azure Cosmos DB приложению требуется строка подключения к таблице для учетной записи хранения Cosmos DB. Строку подключения можно получить с помощью портала Azure, Azure CLI или Azure PowerShell.
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_entities
TableClient
объекта , и возвращаются только строки, соответствующие строке фильтра. Аналогичный метод можно использовать в коде для создания подходящих строк фильтра в соответствии с требованиями приложения.
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 в корневом каталоге репозитория .
При первом запуске приложения данные не отображаются, так как таблица пуста. Используйте любую из кнопок в верхней части приложения, чтобы добавить данные в таблицу.
При нажатии кнопки Вставить с помощью сущности таблицы открывается диалоговое окно, в котором можно выполнить операцию вставки или upsert для новой строки с помощью объекта 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, выполнив следующие действия.
Дальнейшие действия
Из этого краткого руководства вы узнали, как создать учетную запись Azure Cosmos DB и таблицу с помощью обозревателя данных, а также как запустить приложение. Теперь вы можете запрашивать данные с помощью API для таблицы.