Introduzione all'archiviazione tabelle di Azure e all'API Tabelle di Azure Cosmos DB con PythonGet started with Azure Table storage and the Azure Cosmos DB Table API using Python

Suggerimento

Il contenuto di questo articolo è applicabile al servizio di archiviazione tabelle di Azure e all'API Tabelle di Azure Cosmos DB.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. L'API Tabelle di Azure Cosmos DB è un'offerta Premium per il servizio di archiviazione tabelle, che include tabelle con ottimizzazione per la velocità effettiva, distribuzione globale e indici secondari automatici.The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

L'archiviazione tabelle di Azure e Azure Cosmos DB sono servizi che archiviano dati NoSQL strutturati nel cloud, mettendo a disposizione un archivio di chiavi/attributi senza schema.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. Poiché l'archiviazione tabelle e Azure Cosmos DB sono senza schema, è facile adattare i dati con il variare delle esigenze dell'applicazione.Because Table storage and Azure Cosmos DB are schemaless, it's easy to adapt your data as the needs of your application evolve. L'accesso ai dati dell'archiviazione tabelle e dell'API Tabelle è rapido ed economico per molti tipi di applicazioni e presenta costi generalmente più bassi rispetto alle soluzioni SQL tradizionali per volumi di dati simili.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.

È possibile usare l'archiviazione tabelle o Azure Cosmos DB per archiviare set di dati flessibili, ad esempio i dati utente per le applicazioni Web, le rubriche, le informazioni sui dispositivi o altri tipi di metadati richiesti dal servizio.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. In una tabella possono essere archiviate il numero desiderato di tabelle e un account di archiviazione può contenere un numero qualsiasi di tabelle, fino a che non viene raggiunto il limite di capacità dell'account di archiviazione.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.

Informazioni sull'esempioAbout this sample

Questo esempio illustra come usare Azure Cosmos DB Table SDK per Python all'interno di scenari comuni di archiviazione tabelle di Azure.This sample shows you how to use the Azure Cosmos DB Table SDK for Python in common Azure Table storage scenarios. Il nome dell'SDK indica che è destinato all'uso con Azure Cosmos DB. L'SDK funziona tuttavia sia con Azure Cosmos DB sia con l'archiviazione tabelle di Azure, ma ogni servizio ha un endpoint univoco.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. Questi scenari vengono esaminati tramite esempi Python che illustrano come:These scenarios are explored using Python examples that illustrate how to:

  • Creare ed eliminare tabelleCreate and delete tables
  • Inserire ed eseguire query sulle entitàInsert and query entities
  • Modificare entitàModify entities

Mentre si lavora agli scenari di questo esempio, è possibile vedere le informazioni di riferimento sull'API Azure Cosmos DB SDK per Python.While working through the scenarios in this sample, you may want to refer to the Azure Cosmos DB SDK for Python API reference.

PrerequisitiPrerequisites

Per completare correttamente l'esempio sono necessari gli elementi seguenti:You need the following to complete this sample successfully:

Creare un account del servizio di AzureCreate an Azure service account

È possibile usare tabelle con l'archiviazione tabelle di Azure o con Azure Cosmos DB.You can work with tables using Azure Table storage or Azure Cosmos DB. Per altre informazioni sulle differenze tra i servizi, vedere Offerte per tabelle.To learn more about the differences between the services, see Table offerings. Sarà necessario creare un account per il servizio che si intende usare.You'll need to create an account for the service you're going to use.

Creare un account di archiviazione di AzureCreate an Azure storage account

Il modo più semplice per creare un account di archiviazione di Azure consiste nell'usare il portale di Azure.The easiest way to create an Azure storage account is by using the Azure portal. Per altre informazioni, vedere Creare un account di archiviazione.To learn more, see Create a storage account.

È possibile anche creare un account di archiviazione di Azure usando Azure PowerShell o l'interfaccia della riga di comando di Azure.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Se si preferisce non creare un account di archiviazione in questa fase, è anche possibile usare l'emulatore di archiviazione di Azure per eseguire e testare il codice in un ambiente locale.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. Per altre informazioni, vedere Usare l'emulatore di archiviazione di Azure per sviluppo e test.For more information, see Use the Azure storage emulator for development and testing.

Creare un account per l'API di tabella di Azure Cosmos DBCreate an Azure Cosmos DB Table API account

Per istruzioni per la creazione di un account per l'API Tabella di Azure Cosmos DB, vedere Creare un account di database.For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Installare Azure Cosmos DB Table SDK per PythonInstall the Azure Cosmos DB Table SDK for Python

Dopo aver creato un account di archiviazione, il passaggio successivo consiste nell'installare Microsoft Azure Cosmos DB Table SDK per Python.After you've created a Storage account, your next step is to install the Microsoft Azure Cosmos DB Table SDK for Python. Per informazioni dettagliate sull'installazione dell'SDK, vedere il file README.rst nel repository di Cosmos DB Table SDK per Python su GitHub.For details on installing the SDK, refer to the README.rst file in the Cosmos DB Table SDK for Python repository on GitHub.

Importare le classi TableService ed EntityImport the TableService and Entity classes

Per usare le entità nel servizio tabelle di Azure in Python, è necessario usare le classi TableService ed Entity.To work with entities in the Azure Table service in Python, you use the TableService and Entity classes. Aggiungere il codice seguente nella parte iniziale del file Python per importare entrambi gli elementi: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

Connettersi al servizio tabelle di AzureConnect to Azure Table service

Per connettersi al servizio Tabella di archiviazione di Azure, creare un oggetto TableService e passare il nome dell'account di archiviazione e la chiave dell'account.To connect to Azure Storage Table service, create a TableService object, and pass in your Storage account name and account key. Sostituire myaccount e mykey con il nome e la chiave dell'account.Replace myaccount and mykey with your account name and key.

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

Connettersi ad Azure Cosmos DBConnect to Azure Cosmos DB

Per connettersi ad Azure Cosmos DB, copiare la stringa di connessione primaria dal portale di Azure e creare un oggetto TableService usando la stringa di connessione copiata: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;')

Creare una tabellaCreate a table

Chiamare create_table per creare la tabella.Call create_table to create the table.

table_service.create_table('tasktable')

Aggiungere un'entità a una tabellaAdd an entity to a table

Per aggiungere un'entità, creare prima un oggetto che la rappresenta e quindi passare l'oggetto al metodo 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. L'oggetto entità può essere un dizionario o un oggetto di tipo Entity e definisce i nomi e i valori delle proprietà dell'entità.The entity object can be a dictionary or an object of type Entity, and defines your entity's property names and values. Ogni entità deve includere le proprietà PartitionKey e RowKey necessarie, oltre a tutte le altre proprietà definite per l'entità.Every entity must include the required PartitionKey and RowKey properties, in addition to any other properties you define for the entity.

Questo esempio crea un oggetto dizionario che rappresenta un'entità e quindi lo passa al metodo insert_entity per aggiungerlo alla tabella: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)

Questo esempio crea un oggetto Entity e quindi lo passa al metodo insert_entity per aggiungerlo alla tabella: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 e RowKeyPartitionKey and RowKey

È necessario specificare entrambe le proprietà PartitionKey e RowKey per ogni entità.You must specify both a PartitionKey and a RowKey property for every entity. Si tratta degli identificatori univoci delle entità, che insieme formano la chiave primaria di un'entità.These are the unique identifiers of your entities, as together they form the primary key of an entity. È possibile eseguire query usando questi valori in modo molto più rapido rispetto a quanto è possibile fare su qualsiasi altra proprietà dell'entità, perché solo queste proprietà sono indicizzate.You can query using these values much faster than you can query any other entity properties because only these properties are indexed.

Il servizio tabelle usa PartitionKey per distribuire in modo intelligente le entità della tabella nei nodi di archiviazione.The Table service uses PartitionKey to intelligently distribute table entities across storage nodes. Le entità con la stessa proprietà PartitionKey vengono archiviate nello stesso nodo.Entities that have the same PartitionKey are stored on the same node. RowKey è l'ID univoco dell'entità all'interno della partizione a cui appartiene.RowKey is the unique ID of the entity within the partition it belongs to.

Aggiornare un'entitàUpdate an entity

Per aggiornare tutti i valori delle proprietà di un'entità, chiamare il metodo update_entity.To update all of an entity's property values, call the update_entity method. Questo esempio mostra come sostituire un'entità esistente con una versione aggiornata: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)

Se l'entità da aggiornare non esiste già, l'operazione di aggiornamento non riuscirà.If the entity that is being updated doesn't already exist, then the update operation will fail. Se si vuole archiviare un'entità indipendentemente dal fatto che esista o meno, usare insert_or_replace_entity.If you want to store an entity whether it exists or not, use insert_or_replace_entity. Nell'esempio seguente, la prima chiamata sostituirà l'entità esistente.In the following example, the first call will replace the existing entity. La seconda chiamata inserisce una nuova entità, perché nella tabella non c'è alcuna entità con le proprietà PartitionKey e RowKey specificate.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)

Suggerimento

Il metodo update_entity sostituisce tutte le proprietà e i valori di un'entità esistente e può anche essere usato per rimuovere le proprietà da un'entità esistente.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. È possibile usare il metodo merge_entity per aggiornare un'entità esistente con i valori delle proprietà nuovi o modificati senza sostituire completamente l'entità.You can use the merge_entity method to update an existing entity with new or modified property values without completely replacing the entity.

Modificare più entitàModify multiple entities

Per garantire l'elaborazione atomica delle richieste da parte del servizio tabelle, è possibile inviare più operazioni insieme in un batch.To ensure the atomic processing of a request by the Table service, you can submit multiple operations together in a batch. Usare prima di tutto la classe TableBatch per aggiungere più operazioni a un singolo batch.First, use the TableBatch class to add multiple operations to a single batch. Chiamare quindi TableService.commit_batch per inviare le operazioni in un'operazione atomica.Next, call TableService.commit_batch to submit the operations in an atomic operation. Tutte le entità da modificare in batch devono trovarsi nella stessa partizione.All entities to be modified in batch must be in the same partition.

Questo esempio aggiunge due entità in un batch: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)

I batch possono essere usati anche con la sintassi di gestione contesto: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)

Eseguire una query su un'entitàQuery for an entity

Per eseguire una query su una tabella per un'entità, passare le relative proprietà PartitionKey e RowKey al metodo 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)

Eseguire query su un set di entitàQuery a set of entities

È possibile eseguire query per un set di entità specificando una stringa di filtro con il parametro filter.You can query for a set of entities by supplying a filter string with the filter parameter. Questo esempio trova tutte le attività di Seattle applicando un filtro a 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)

Eseguire query su un subset di proprietà di entitàQuery a subset of entity properties

È anche possibile limitare le proprietà restituite per ogni entità in una query.You can also restrict which properties are returned for each entity in a query. Questa tecnica, denominata proiezione, consente di ridurre la larghezza di banda e di migliorare le prestazioni di query, in particolare per entità o set di risultati di grandi dimensioni.This technique, called projection, reduces bandwidth and can improve query performance, especially for large entities or result sets. Usare il parametro select e passare i nomi delle proprietà da restituire al client.Use the select parameter and pass the names of the properties you want returned to the client.

La query nel codice seguente restituisce solo le descrizioni delle entità nella tabella.The query in the following code returns only the descriptions of entities in the table.

Nota

Il frammento di codice seguente funziona solo in Archiviazione di Azure.The following snippet works only against the Azure Storage. Non è supportato dall'emulatore di archiviazione.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)

Eliminare un'entitàDelete an entity

Eliminare un'entità passando le relative proprietà PartitionKey e RowKey al metodo delete_entity.Delete an entity by passing its PartitionKey and RowKey to the delete_entity method.

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

Eliminare una tabellaDelete a table

Se una tabella o una delle entità al suo interno non è più necessaria, chiamare il metodo delete_table per eliminare definitivamente la tabella da Archiviazione di Azure.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')

Passaggi successiviNext steps