Краткое руководство. Создание приложения API для таблиц с помощью пакета SDK для Python и Azure Cosmos DB
Область применения: 
Таблица
В этом кратком руководстве показано, как получить доступ к API Azure Cosmos DB для таблицы из приложения Python. Azure Cosmos DB для таблицы — это хранилище данных без схемы, позволяющее приложениям хранить структурированные данные NoSQL в облаке. Поскольку данные хранятся в структуре без схемы, при добавлении в таблицу объекта с новым атрибутом в нее автоматически добавляются новые свойства (столбцы). Приложения Python могут получить доступ к Azure Cosmos DB для таблицы с помощью пакета Azure Data Table sdk для 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 sample folder. Приложение 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.
| Instructions | Снимок экрана |
|---|---|
В портал Azure:
|
|
| На странице Azure Cosmos DB выберите +Создать. | 
|
| На странице Выберите вариант API параметр выберите вариант Таблица Azure. | 
|
На странице Создание учетной записи Azure Cosmos DB — таблица Azure заполните форму, как описано ниже.
|
|
2. Создание таблицы
Затем необходимо создать таблицу в учетной записи Azure Cosmos DB для использования приложения. В отличие от традиционной базы данных, свойства (столбцы) в таблице указывать не требуется — нужно указать только имя таблицы. При загрузке данных в таблицу свойства (столбцы) автоматически создаются по мере необходимости.
В портал Azure выполните следующие действия, чтобы создать таблицу в учетной записи Azure Cosmos DB.
| Instructions | Снимок экрана |
|---|---|
На портале Azure перейдите к странице общих сведений об учетной записи Azure Cosmos DB.
|
|
| На странице обзора нажмите кнопку +Добавить таблицу. Диалоговое окно "Новая таблица" выходит из правой части страницы. | 
|
В диалоговом окне Новая таблица укажите данные, как описано ниже.
|
|
3. Получение строка подключения Azure Cosmos DB
Чтобы получить доступ к таблицам в Azure Cosmos DB, приложению требуется таблица строка подключения для учетной записи хранения Cosmos DB. Строку подключения можно получить с помощью портала Azure, Azure CLI или Azure PowerShell.
| Instructions | Снимок экрана |
|---|---|
| В левой части страницы учетной записи 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 классе, расположенном в вспомогательном файле в каталоге webapp. Чтобы работать с объектами в клиентской библиотеке azure.data.tables для Python, необходимо импортировать TableServiceClient класс в верхней части этого файла.
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, чтобы добавить столбцы, как в традиционной базе данных.
Эта модель обеспечивает гибкость работы приложения с источниками данных, которые могут добавлять или изменять то, какие данные должны быть записаны со временем или в каких случаях различные входные данные предоставляют разные сведения приложению. В примере приложения мы можем имитировать метеостанцию, которая отправляет не только базовые данные о погоде, но и некоторые дополнительные значения. Когда объект с этими новыми свойствами впервые хранится в таблице, соответствующие свойства (столбцы) автоматически добавляются в таблицу.
Чтобы вставить или upsert такой объект с помощью API для таблицы, сопоставить свойства расширяемого объекта с TableEntity объектом и использовать create_entityupsert_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, выполнив следующие действия.
| Instructions | Снимок экрана |
|---|---|
| Чтобы перейти в группу ресурсов, в строке поиска введите ее имя. На вкладке Группы ресурсов выберите имя нужной группы. | 
|
| Выберите Удалить группу ресурсов на панели инструментов в верхней части страницы группы ресурсов. | 
|
В правой части экрана появится диалоговое окно с просьбой подтвердить удаление группы ресурсов.
|
|
Следующие шаги
Из этого краткого руководства вы узнали, как создать учетную запись Azure Cosmos DB и таблицу с помощью обозревателя данных, а также как запустить приложение. Теперь вы можете запросить данные с помощью API для таблицы.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по