Inicio rápido: Creación de una aplicación de API para Table con el SDK de Python y Azure Cosmos DB
SE APLICA A: 
Table
En este inicio rápido, se muestra cómo acceder a la API para Table de Azure Cosmos DB desde una aplicación de Python. Azure Cosmos DB for Table es un almacén de datos sin esquema que permite a las aplicaciones almacenar datos NoSQL estructurados en la nube. Dado que los datos se almacenan en un diseño sin esquema, las nuevas propiedades (columnas) se agregan automáticamente a la tabla cuando se agrega un objeto con un nuevo atributo a la tabla. Las aplicaciones de Python pueden acceder a Azure Cosmos DB for Table mediante el paquete SDK de Azure Data Tables para Python.
Prerrequisitos
La aplicación de ejemplo se escribe en Python 3.7 o posteriores, aunque los principios se aplican a todas las aplicaciones Python 3.7 o posteriores. Puede usar Visual Studio Code como IDE.
Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
Aplicación de ejemplo
La aplicación de ejemplo de este tutorial se puede clonar o descargar desde el repositorio 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
En el repositorio de ejemplo se incluyen una carpeta de ejemplo de 1-starter-app y 2-completed-app . 1-starter-app tiene algunas funcionalidades pendientes de completar con líneas marcadas como "#TODO". Los fragmentos de código que se muestran en este artículo son las adiciones sugeridas para completar la carpeta 1-starter-app.
La aplicación de ejemplo completada usa datos meteorológicos para demostrar las funcionalidades de la API para Table. Los objetos que representan observaciones meteorológicas se almacenan y recuperan mediante la API para Table, incluido el almacenamiento de objetos con propiedades adicionales para mostrar las funcionalidades sin esquema de dicha API. En la imagen siguiente se muestra la aplicación local que se ejecuta en un explorador y se muestran los datos del tiempo almacenados en Azure Cosmos DB for Table.
1 - Creación de una cuenta de Azure Cosmos DB
En primer lugar, debe crear una cuenta de API for Table de Azure Cosmos DB que contendrá las tablas usadas en la aplicación. Cree una cuenta con Azure Portal, la CLI de Azure o Azure PowerShell.
Inicie sesión en Azure Portal y siga estos pasos para crear una cuenta de Azure Cosmos DB.
| Instrucciones | Instantánea |
|---|---|
En Azure Portal:
|
|
| En la página Azure Cosmos DB, seleccione +Crear. | 
|
| En la página Selección de la opción de API, elija la opción Tabla de Azure. | 
|
En la página Creación de una cuenta de Azure Cosmos DB: Tabla de Azure, rellene el formulario de la siguiente manera.
|
|
2 - Creación de una tabla
Después, debe crear una tabla dentro de la cuenta de Azure Cosmos DB que es la que usará la aplicación. A diferencia de una base de datos tradicional, solo es necesario especificar el nombre de la tabla, no las propiedades (columnas) de la tabla. A medida que se cargan datos en la tabla, las propiedades (columnas) se crean automáticamente según sea necesario.
En Azure Portal, complete los pasos siguientes para crear una tabla dentro de la cuenta de Azure Cosmos DB.
| Instrucciones | Instantánea |
|---|---|
En Azure Portal, vaya a la página de información general de la cuenta de Azure Cosmos DB.
|
|
| En la página de información general, seleccione +Agregar tabla. El cuadro de diálogo Nueva tabla se desliza desde el lado derecho de la página. | 
|
En el cuadro de diálogo Nueva tabla, complete el formulario de la siguiente manera.
|
|
3 - Obtención de la cadena de conexión de Azure Cosmos DB
Para acceder a las tablas de Azure Cosmos DB, la aplicación necesita la cadena de conexión de la tabla para la cuenta de almacenamiento de Cosmos DB. La cadena de conexión se puede recuperar mediante Azure Portal, la CLI de Azure o Azure PowerShell.
| Instrucciones | Instantánea |
|---|---|
| En el lado izquierdo de la página de la cuenta de Azure Cosmos DB, busque el elemento de menú denominado Cadenas de conexión en el encabezado Configuración y selecciónelo. Se le llevará a una página donde puede recuperar la cadena de conexión para la cuenta de Azure Cosmos DB. | 
|
| Copie el valor CADENA DE CONEXIÓN PRINCIPAL para usarlo en la aplicación. | 
|
4 - Instalación del SDK de Azure Data Tables para Python
Después de crear una cuenta de Azure Cosmos DB, el paso siguiente consiste en instalar el SDK de Microsoft Azure Data Tables para Python. Para más información sobre la instalación del SDK, consulte el archivo README.md del SDK de tablas de datos para el repositorio de Python en GitHub.
Instale la biblioteca cliente de Azure Tables para Python con el pip:
pip install azure-data-tables
No olvide instalar también requirements.txt en las carpetas 1-starter-app o 2-completed-app.
5 - Configuración del cliente de Table en un archivo .env
Copie la cadena de conexión de la cuenta de Azure Cosmos DB desde Azure Portal y cree un objeto TableServiceClient con la cadena de conexión copiada. Cambie a la carpeta 1-starter-app o 2-completed-app. Independientemente de la aplicación con la que empiece, debe definir variables de entorno en un archivo .env.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Azure SDK se comunica con Azure mediante objetos de cliente para ejecutar diferentes operaciones en Azure. El objeto TableServiceClient es el objeto que se usa para comunicarse con Azure Cosmos DB for Table. Normalmente, una aplicación tendrá un único TableServiceClient general y tendrá un TableClient por tabla.
Por ejemplo, el código siguiente crea un objeto de TableServiceClient mediante la cadena de conexión de la variable de entorno.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 - Implementación de las operaciones de tabla de Azure Cosmos DB
Todas las operaciones de tabla de Azure Cosmos DB de la aplicación de ejemplo se implementan en la clase TableServiceHelper ubicada en el archivo helper del directorio webapp. Tendrá que importar la clase TableServiceClient en la parte superior de este archivo para trabajar con los objetos de la librería cliente azure.data.tables para Python.
from azure.data.tables import TableServiceClient
Al principio de la clase TableServiceHelper, cree un constructor y agregue una variable de miembro para el objeto TableClient para permitir que el objeto TableClient se inserte en la clase.
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)
Filtrado de las filas devueltas de una tabla
Para filtrar las filas devueltas de una tabla, puede pasar una cadena de filtro de estilo OData al método query_entities. Por ejemplo, si quisiera obtener todas las lecturas meteorológicas de Chicago entre la medianoche del 1 de julio de 2021 y la medianoche del 2 de julio de 2021 (ambos incluidos), pasaría la siguiente cadena de filtro.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
Puede ver los operadores de filtro de OData relacionados en el sitio web azure-data-tables en la sección Escribir filtros.
Cuando se pasa el parámetro request.args al método query_entity de la clase TableServiceHelper, crea una cadena de filtrado para cada valor de propiedad que no sea NULL. A continuación, crea una cadena de filtrado combinada combinando todos los valores con una cláusula "and". Esta cadena de filtrado combinada se pasa al método query_entities en el objeto TableClient y solo se devuelven las filas que coincidan con la cadena de filtrado. Puede usar un método similar en el código para construir cadenas de filtrado adecuadas según sea necesario para la aplicación.
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)))
Inserción de datos mediante un objeto TableEntity
La manera más sencilla de agregar datos a una tabla es mediante el uso de un objeto TableEntity. En este ejemplo, los datos se asignan desde un objeto del modelo de entrada a un objeto TableEntity. Las propiedades del objeto de entrada que representan el nombre de la estación meteorológica y la fecha y hora de observación se asignan a las propiedades PartitionKey y RowKey respectivamente, que juntas forman una clave única para la fila de la tabla. A continuación, las propiedades adicionales del objeto del modelo de entrada se asignan a las propiedades del diccionario en el objeto TableEntity. Por último, se usa el método create_entity del objeto TableClient para insertar los datos en la tabla.
Modifique la función insert_entity de la aplicación de ejemplo para que contenga el código siguiente.
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
Actualizar/insertar (upsert) datos mediante un objeto TableEntity
Si intenta insertar una fila en una tabla con una combinación de clave de partición y clave de fila que ya existe en esa tabla, recibirá un error. Por este motivo, a menudo es preferible usar upsert_entity en lugar del método create_entity al agregar filas a una tabla. Si la combinación de clave de partición y clave de fila especificada ya existe en la tabla, el método upsert_entity actualiza la fila existente. De lo contrario, se agrega la fila a la tabla.
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
Insertar o actualizar/insertar (upsert) datos con propiedades variables
Una de las ventajas de usar Azure Cosmos DB for Table es que, si un objeto que se carga en una tabla contiene nuevas propiedades, esas propiedades se agregan automáticamente a la tabla y los valores almacenados en Azure Cosmos DB. No es necesario ejecutar instrucciones DDL como ALTER TABLE para agregar columnas como en una base de datos tradicional.
Este modelo proporciona flexibilidad a la aplicación cuando se trabaja con orígenes de datos que pueden agregar o modificar qué datos se deben capturar a lo largo del tiempo o cuando distintas entradas proporcionan datos diferentes a la aplicación. En la aplicación de ejemplo, podemos simular una estación meteorológica que envía no solo los datos meteorológicos básicos, sino también algunos valores adicionales. Cuando un objeto con estas nuevas propiedades se almacena en la tabla por primera vez, las propiedades correspondientes (columnas) se agregan automáticamente a la tabla.
Para insertar o actualizar un objeto de este tipo mediante la API para Table, asigne las propiedades del objeto ampliable a un objeto TableEntity y use los métodos create_entity o upsert_entity en el objeto TableClient según corresponda.
En la aplicación de ejemplo, la función upsert_entity también puede implementar la función de insertar o actualizar datos con propiedades de variable.
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
Actualización de una entidad
Las entidades se pueden actualizar llamando al método update_entity en el objeto TableClient.
En la aplicación de ejemplo, este objeto se pasa al método upsert_entity de la clase TableClient. Actualiza ese objeto de entidad y usa el método upsert_entity para guardar las actualizaciones en la base de datos.
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
Eliminación de una entidad
Para quitar una entidad de una tabla, llame al método delete_entity del objeto TableClient con la clave de partición y la clave de fila del objeto.
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 - Ejecución del código
Ejecute la aplicación de ejemplo para interactuar con Azure Cosmos DB for Table. Por ejemplo, a partir de la carpeta 2-completed-app, con los requisitos instalados, puede usar:
python3 run.py webapp
Consulte el archivo README.md en la raíz del repositorio de ejemplo para obtener más información sobre cómo ejecutar la aplicación de ejemplo.
La primera vez que ejecute la aplicación, no habrá datos porque la tabla está vacía. Use cualquiera de los botones de la parte superior de la aplicación para agregar datos a la tabla.
Al seleccionar el botón Insert using Table Entity (Insertar mediante TableEntity), se abre un cuadro de diálogo que le permite insertar o actualizar/insertar (upsert) una fila nueva mediante un objeto TableEntity.
Al seleccionar el botón Insert using Expandable Data, se abre un cuadro de diálogo que le permite insertar un objeto con propiedades personalizadas, lo que muestra cómo Azure Cosmos DB for Table agrega automáticamente propiedades (columnas) a la tabla cuando es necesario. Use el botón Add Custom Field (Agregar campo personalizado) para agregar una o varias propiedades nuevas y demostrar esta funcionalidad.
Use el botón Insertar datos de ejemplo para cargar algunos datos de ejemplo en la tabla de Azure Cosmos DB.
Para la carpeta de ejemplo 1-starter-app, deberá completar al menos el código de la función
submit_transactionpara que la inserción de datos de ejemplo funcione.Los datos de ejemplo se cargan desde un archivo sample_data.json. La variable .env
project_root_pathindica a la aplicación dónde encontrar este archivo. Por ejemplo, si ejecuta la aplicación desde la carpeta 1-starter-app o 2-completed-app, establezcaproject_root_pathen "" (en blanco).
Seleccione el elemento Filter Results (Filtrar resultados) en el menú superior para ir a la página Filter Results (Filtrar resultados). En esta página, rellene los criterios de filtrado para mostrar cómo se puede crear y pasar una cláusula de filtro a Azure Cosmos DB for Table.
Limpieza de recursos
Cuando haya terminado con la aplicación de ejemplo, debe quitar todos los recursos de Azure relacionados con este artículo de la cuenta de Azure. Para quitar todos los recursos, elimine el grupo de recursos.
Se puede eliminar un grupo de recursos mediante Azure Portal haciendo lo siguiente.
| Instrucciones | Instantánea |
|---|---|
| Para ir al grupo de recursos, en la barra de búsqueda, escriba el nombre del grupo de recursos. A continuación, en la pestaña Grupos de recursos, seleccione el nombre del grupo de recursos. | 
|
| Seleccione Eliminar grupo de recursos en la barra de herramientas de la parte superior de la página del grupo de recursos. | 
|
Aparecerá un cuadro de diálogo a la derecha de la pantalla en el que se le pedirá que confirme la eliminación del grupo de recursos.
|
|
Pasos siguientes
En esta guía de inicio rápido, ha obtenido información sobre cómo crear una cuenta de Azure Cosmos DB, crear una tabla mediante el Explorador de datos y ejecutar una aplicación. Ahora ya puede consultar los datos mediante la API para Table.