Introducción a Azure Table Storage y a Table API de Azure Cosmos DB mediante PythonGet started with Azure Table storage and the Azure Cosmos DB Table API using Python

Sugerencia

El contenido de este artículo se aplica a Azure Table Storage y a Table API de Azure Cosmos DB.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. La instancia de Table API de Azure Cosmos DB es una oferta premium que ofrece tablas con rendimiento optimizado, distribución global e índices secundarios automáticos.The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

Azure Table Storage y Azure Cosmos DB son servicios que almacenan datos NoSQL estructurados en la nube y proporcionan un almacén de claves y atributos con un diseño sin esquema.Azure Table storage and Azure Cosmos DB are services that store structured NoSQL data in the cloud, providing a key/attribute store with a schemaless design. Dado que tanto Table Storage como Azure Cosmos DB carecen de esquema, es fácil adaptar los datos a medida que evolucionan las necesidades de la aplicación.Because Table storage and Azure Cosmos DB are schemaless, it's easy to adapt your data as the needs of your application evolve. El acceso a los datos tanto de Table Storage como de Table API es rápido y rentable para muchos tipos de aplicaciones y, por lo general, el costo es normalmente menor que con el SQL tradicional en volúmenes similares de datos.Access to Table storage and Table API data is fast and cost-effective for many types of applications, and is typically lower in cost than traditional SQL for similar volumes of data.

Tanto Table Storage como Azure Cosmos DB se pueden usar para almacenar conjuntos de datos flexibles, como datos de usuarios para aplicaciones web, libretas de direcciones, información de dispositivos u otros tipos de metadatos que el servicio requiera.You can use Table storage or Azure Cosmos DB to store flexible datasets like user data for web applications, address books, device information, or other types of metadata your service requires. Una tabla puede almacenar un número cualquiera de entidades y una cuenta de almacenamiento puede incluir un número cualquiera de tablas, hasta alcanzar el límite de capacidad de este tipo de cuenta.You can store any number of entities in a table, and a storage account may contain any number of tables, up to the capacity limit of the storage account.

Acerca de este ejemploAbout this sample

En este ejemplo se muestra cómo usar el SDK de Table de Azure Cosmos DB para Python en algunos escenarios habituales de Azure Table Storage.This sample shows you how to use the Azure Cosmos DB Table SDK for Python in common Azure Table storage scenarios. El nombre del SDK indica que es para su uso con Azure Cosmos DB, pero funciona con Azure Cosmos DB y con Azure Table Storage, cada servicio solo tiene un único punto de conexión.The name of the SDK indicates it is for use with Azure Cosmos DB, but it works with both Azure Cosmos DB and Azure Tables storage, each service just has a unique endpoint. Estos escenarios se describen mediante ejemplos de Python que muestran cómo:These scenarios are explored using Python examples that illustrate how to:

  • Crear y eliminar tablasCreate and delete tables
  • Insertar y consultar entidadesInsert and query entities
  • Modificar entidadesModify entities

Se recomienda que consulte la referencia de la API del SDK de Azure Cosmos DB para Python mientras trabaja con los escenarios de este ejemplo.While working through the scenarios in this sample, you may want to refer to the Azure Cosmos DB SDK for Python API reference.

PrerequisitesPrerequisites

Necesitará lo siguiente para completar este ejemplo correctamente:You need the following to complete this sample successfully:

Creación de una cuenta de servicio de AzureCreate an Azure service account

Puede trabajar con tablas mediante Azure Table Storage o Azure Cosmos DB.You can work with tables using Azure Table storage or Azure Cosmos DB. Para más información acerca de las diferencias entre los servicios, consulte Ofertas de Table.To learn more about the differences between the services, see Table offerings. Debe crear una cuenta para el servicio que se va a utilizar.You'll need to create an account for the service you're going to use.

Creación de una cuenta de Azure StorageCreate an Azure storage account

La manera más sencilla de crear una cuenta de almacenamiento de Azure es mediante Azure Portal.The easiest way to create an Azure storage account is by using the Azure portal. Para obtener más información, consulte Crear una cuenta de almacenamiento.To learn more, see Create a storage account.

También se puede crear una cuenta de Azure Storage mediante Azure PowerShell o la CLI de Azure.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Si no desea crear una cuenta de almacenamiento en este momento, también puede utilizar el emulador de Almacenamiento de Azure para ejecutar y probar el código en un entorno local.If you prefer not to create a storage account at this time, you can also use the Azure storage emulator to run and test your code in a local environment. Para más información, consulte Uso del emulador de Azure Storage para desarrollo y pruebas.For more information, see Use the Azure storage emulator for development and testing.

Creación de una cuenta de Table API de Azure Cosmos DBCreate an Azure Cosmos DB Table API account

Para obtener instrucciones sobre cómo crear una cuenta de Table API de Azure Cosmos DB, consulte Creación de una cuenta de base de datos.For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Instalación del SDK de Table de Azure Cosmos DB para PythonInstall the Azure Cosmos DB Table SDK for Python

Cuando haya creado una cuenta de Storage, el paso siguiente consiste en instalar el SDK de Table de Azure Cosmos DB para Python.After you've created a Storage account, your next step is to install the Microsoft Azure Cosmos DB Table SDK for Python. Para obtener más información sobre la instalación del SDK, consulte el archivo README.rst del SDK de Table de Cosmos DB para el repositorio de Python en GitHub.For details on installing the SDK, refer to the README.rst file in the Cosmos DB Table SDK for Python repository on GitHub.

Importación de las clases Entity y TableServiceImport the TableService and Entity classes

Para trabajar con entidades en Azure Table service de Python, use las clases TableService y Entity.To work with entities in the Azure Table service in Python, you use the TableService and Entity classes. Agregue este código cerca de la parte superior del archivo de Python para importar ambos:Add this code near the top your Python file to import both:

from azure.cosmosdb.table.tableservice import TableService
from azure.cosmosdb.table.models import Entity

Conexión a Azure Table serviceConnect to Azure Table service

Para conectarse a Azure Storage Table service, cree un objeto TableService y pase la clave de cuenta y el nombre de la cuenta de Storage.To connect to Azure Storage Table service, create a TableService object, and pass in your Storage account name and account key. Reemplace myaccount y mykey por el nombre y la clave de la de cuenta.Replace myaccount and mykey with your account name and key.

table_service = TableService(account_name='myaccount', account_key='mykey')

Conexión a Azure Cosmos DBConnect to Azure Cosmos DB

Para conectarse a Azure Cosmos DB, copie la cadena de conexión principal de Azure Portal y cree un objeto TableService con la cadena de conexión que ha copiado:To connect to Azure Cosmos DB, copy your primary connection string from the Azure portal, and create a TableService object using your copied connection string:

table_service = TableService(connection_string='DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;TableEndpoint=myendpoint;')

Creación de una tablaCreate a table

Llame a create_table para crear la tabla.Call create_table to create the table.

table_service.create_table('tasktable')

Adición de una entidad a una tablaAdd an entity to a table

Para agregar una entidad, primero cree un objeto que represente la entidad y, luego, pase el objeto al método TableService.insert_entity.To add an entity, you first create an object that represents your entity, then pass the object to the TableService.insert_entity method. El objeto de la entidad puede ser un diccionario o un objeto de tipo Entity y define los nombres y los valores de propiedad de la entidad.The entity object can be a dictionary or an object of type Entity, and defines your entity's property names and values. Cada entidad debe incluir las propiedades PartitionKey y RowKey necesarias, además de cualquier otra propiedad que se defina para la entidad.Every entity must include the required PartitionKey and RowKey properties, in addition to any other properties you define for the entity.

En este ejemplo se crea un objeto de diccionario que representa una entidad y, a continuación, lo pasa al método insert_entity para agregarlo a la tabla:This example creates a dictionary object representing an entity, then passes it to the insert_entity method to add it to the table:

task = {'PartitionKey': 'tasksSeattle', 'RowKey': '001',
        'description': 'Take out the trash', 'priority': 200}
table_service.insert_entity('tasktable', task)

En este ejemplo, se crea el objeto Entity y, a continuación, este se pasa al método insert_entity para agregarlo a la tabla:This example creates an Entity object, then passes it to the insert_entity method to add it to the table:

task = Entity()
task.PartitionKey = 'tasksSeattle'
task.RowKey = '002'
task.description = 'Wash the car'
task.priority = 100
table_service.insert_entity('tasktable', task)

PartitionKey y RowKeyPartitionKey and RowKey

Para cada entidad debe especificar una propiedad PartitionKey y RowKey.You must specify both a PartitionKey and a RowKey property for every entity. Estos son los identificadores únicos de las entidades y juntos forman la clave principal de una entidad.These are the unique identifiers of your entities, as together they form the primary key of an entity. Puede realizar consultas mediante estos valores de forma mucho más rápida que si consulta cualquier otra propiedad de la entidad ya que estas propiedades son las únicas que se indexan.You can query using these values much faster than you can query any other entity properties because only these properties are indexed.

Table service usa PartitionKey para distribuir de forma inteligente las entidades de tabla entre los nodos de almacenamiento.The Table service uses PartitionKey to intelligently distribute table entities across storage nodes. Las entidades con la misma PartitionKey se almacenan en el mismo nodo.Entities that have the same PartitionKey are stored on the same node. RowKey es el identificador exclusivo de la entidad de la partición a la que pertenece.RowKey is the unique ID of the entity within the partition it belongs to.

Actualización de una entidadUpdate an entity

Para actualizar todos los valores de propiedad de una entidad, llame al método update_entity.To update all of an entity's property values, call the update_entity method. Este ejemplo muestra cómo reemplazar una entidad existente con una versión actualizada:This example shows how to replace an existing entity with an updated version:

task = {'PartitionKey': 'tasksSeattle', 'RowKey': '001',
        'description': 'Take out the garbage', 'priority': 250}
table_service.update_entity('tasktable', task)

Si la entidad que se está actualizando no existe, la operación de actualización generará un error.If the entity that is being updated doesn't already exist, then the update operation will fail. Si desea almacenar una entidad independientemente de si existe o no, use insert_or_replace_entity.If you want to store an entity whether it exists or not, use insert_or_replace_entity. En el siguiente ejemplo, la primera llamada reemplazará la entidad existente.In the following example, the first call will replace the existing entity. La segunda llamada insertará una nueva entidad, debido a que en la tabla no existe ninguna entidad con PartitionKey y RowKey especificados.The second call will insert a new entity, since no entity with the specified PartitionKey and RowKey exists in the table.

# Replace the entity created earlier
task = {'PartitionKey': 'tasksSeattle', 'RowKey': '001',
        'description': 'Take out the garbage again', 'priority': 250}
table_service.insert_or_replace_entity('tasktable', task)

# Insert a new entity
task = {'PartitionKey': 'tasksSeattle', 'RowKey': '003',
        'description': 'Buy detergent', 'priority': 300}
table_service.insert_or_replace_entity('tasktable', task)

Sugerencia

El método update_entity reemplaza todas las propiedades y los valores de una entidad existente y también se puede usar para quitar las propiedades de otra de ellas.The update_entity method replaces all properties and values of an existing entity, which you can also use to remove properties from an existing entity. Puede usar el método merge_entity para actualizar una entidad existente con valores de propiedad nuevos o modificados sin reemplazar completamente la entidad.You can use the merge_entity method to update an existing entity with new or modified property values without completely replacing the entity.

Modificación de varias entidadesModify multiple entities

Para garantizar el procesamiento atómico de una solicitud por parte de Table service, puede enviar varias operaciones en un lote.To ensure the atomic processing of a request by the Table service, you can submit multiple operations together in a batch. En primer lugar, use la clase TableBatch para agregar varias operaciones a un único lote.First, use the TableBatch class to add multiple operations to a single batch. A continuación, llame a TableService.commit_batch para enviar las operaciones de una operación atómica.Next, call TableService.commit_batch to submit the operations in an atomic operation. Todas las entidades que desea modificar del lote deben estar en la misma partición.All entities to be modified in batch must be in the same partition.

En este ejemplo se agregan dos entidades juntas en un lote:This example adds two entities together in a batch:

from azure.cosmosdb.table.tablebatch import TableBatch
batch = TableBatch()
task004 = {'PartitionKey': 'tasksSeattle', 'RowKey': '004',
           'description': 'Go grocery shopping', 'priority': 400}
task005 = {'PartitionKey': 'tasksSeattle', 'RowKey': '005',
           'description': 'Clean the bathroom', 'priority': 100}
batch.insert_entity(task004)
batch.insert_entity(task005)
table_service.commit_batch('tasktable', batch)

Los lotes también pueden usarse con la sintaxis de administrador de contexto:Batches can also be used with the context manager syntax:

task006 = {'PartitionKey': 'tasksSeattle', 'RowKey': '006',
           'description': 'Go grocery shopping', 'priority': 400}
task007 = {'PartitionKey': 'tasksSeattle', 'RowKey': '007',
           'description': 'Clean the bathroom', 'priority': 100}

with table_service.batch('tasktable') as batch:
    batch.insert_entity(task006)
    batch.insert_entity(task007)

Consulta de una entidadQuery for an entity

Para consultar una entidad de una tabla, pase sus propiedades PartitionKey y RowKey al método TableService.get_entity.To query for an entity in a table, pass its PartitionKey and RowKey to the TableService.get_entity method.

task = table_service.get_entity('tasktable', 'tasksSeattle', '001')
print(task.description)
print(task.priority)

Consulta de un conjunto de entidadesQuery a set of entities

Puede consultar un conjunto de entidades proporcionando una cadena de filtro con el parámetro filter.You can query for a set of entities by supplying a filter string with the filter parameter. En este ejemplo se buscan todas las tareas en Seattle mediante la aplicación de un filtro en PartitionKey:This example finds all tasks in Seattle by applying a filter on PartitionKey:

tasks = table_service.query_entities(
    'tasktable', filter="PartitionKey eq 'tasksSeattle'")
for task in tasks:
    print(task.description)
    print(task.priority)

Consulta de un subconjunto de propiedades de las entidadesQuery a subset of entity properties

También puede restringir qué propiedades se devuelven para cada entidad en una consulta.You can also restrict which properties are returned for each entity in a query. Esta técnica, denominada proyección, reduce el ancho de banda y puede mejorar el rendimiento de las consultas, en especial en el caso de entidades o conjuntos de resultados de gran tamaño.This technique, called projection, reduces bandwidth and can improve query performance, especially for large entities or result sets. Use el parámetro select y pase los nombres de las propiedades que desea que se devuelvan al cliente.Use the select parameter and pass the names of the properties you want returned to the client.

La consulta del código siguiente devuelve solo las descripciones de las entidades de la tabla.The query in the following code returns only the descriptions of entities in the table.

Nota

El siguiente fragmento de código funciona solo con Azure Storage.The following snippet works only against the Azure Storage. Esto no es compatible con el emulador de almacenamiento.It is not supported by the storage emulator.

tasks = table_service.query_entities(
    'tasktable', filter="PartitionKey eq 'tasksSeattle'", select='description')
for task in tasks:
    print(task.description)

Eliminación de una entidadDelete an entity

Elimine una entidad pasando sus propiedades PartitionKey y RowKey al método delete_entity.Delete an entity by passing its PartitionKey and RowKey to the delete_entity method.

table_service.delete_entity('tasktable', 'tasksSeattle', '001')

Eliminar una tablaDelete a table

Si ya no necesita una tabla ni ninguna de las entidades dentro de ella, llame al método delete_table para eliminar permanentemente la tabla de Azure Storage.If you no longer need a table or any of the entities within it, call the delete_table method to permanently delete the table from Azure Storage.

table_service.delete_table('tasktable')

Pasos siguientesNext steps