Komma igång med Azure Table Storage och Azure Cosmos DB Table-API:et med hjälp av PythonGet started with Azure Table storage and the Azure Cosmos DB Table API using Python

Tips

Innehållet i den här artikeln gäller för Azure-tabellagring och Azure Cosmos DB tabell-API.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. Azure Cosmos DB tabell-API är en förhandsversion av en premiumprodukt för tabellagring som erbjuder tabeller för optimerat dataflöde, global distribution och automatiska sekundära index.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 och Azure Cosmos DB är tjänster som lagrar strukturerade NoSQL-data i molnet, vilket ger ett nyckel-attributarkiv med en schema lös design.The Azure Table storage and the Azure Cosmos DB are services that store structured NoSQL data in the cloud, providing a key/attribute store with a schemaless design. Eftersom Table Storage och Azure Cosmos DB är schemalösa kan du enkelt anpassa dina data baserat på hur ditt program utvecklas.Because Table storage and Azure Cosmos DB are schemaless, it's easy to adapt your data as the needs of your application evolve. Åtkomst till tabellerna Storage och table API data är snabb och kostnads effektiv för många typer av program och är vanligt vis lägre än traditionell SQL för liknande data volymer.Access to the 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.

Du kan använda Table Storage eller Azure Cosmos DB för att lagra flexibla data uppsättningar som användar data för webb program, adress böcker, enhets information eller andra typer av metadata som din tjänst kräver.You can use the Table storage or the 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. Du kan lagra valfritt antal enheter i en tabell, och ett lagringskonto kan innehålla valfritt antal tabeller, upp till lagringskontots kapacitetsgräns.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.

Om det här exempletAbout this sample

Det här exemplet beskriver hur du använder Azure Cosmos DB Table SDK för Python i vanliga Azure Table Storage-scenarier.This sample shows you how to use the Azure Cosmos DB Table SDK for Python in common Azure Table storage scenarios. SDK-paketets namn indikerar att det ska användas med Azure Cosmos DB, men det fungerar med både Azure Cosmos DB och Azure Table Storage. Enda skillnaden är att tjänsterna har unika slutpunkter.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. De olika scenarierna utforskas med hjälp av Python-baserade exempel som beskriver hur du:These scenarios are explored using Python examples that illustrate how to:

  • Skapar och tar bort tabellerCreate and delete tables
  • Infogar och kör frågor mot entiteterInsert and query entities
  • Ändrar entiteterModify entities

Vi rekommenderar att du använder referensen för Azure Cosmos DB SDK för Python API när du går igenom scenarierna i det här exemplet.While working through the scenarios in this sample, you may want to refer to the Azure Cosmos DB SDK for Python API reference.

FörutsättningarPrerequisites

Du behöver följande för att kunna följa med i det här exemplet:You need the following to complete this sample successfully:

Skapa ett Azure-tjänstkontoCreate an Azure service account

Du kan arbeta med tabeller med hjälp av Azure Table Storage eller Azure Cosmos DB.You can work with tables using the Azure Table storage or the Azure Cosmos DB. Mer information om skillnaderna mellan tabell erbjudanden i dessa två tjänster finns i artikeln tabell erbjudanden .To learn more about the differences between table offerings in these two services, see the Table offerings article. Du måste skapa ett konto för den tjänst som du ska använda.You'll need to create an account for the service you're going to use. I följande avsnitt visas hur du skapar både Azure Table Storage och det Azure Cosmos DB kontot, men du kan bara använda en av dem.The following sections show how to create both Azure Table storage and the Azure Cosmos DB account, however you can just use one of them.

Skapa ett Azure Storage-kontoCreate an Azure storage account

Det enklaste sättet att skapa ett Azure Storage-konto är genom att använda Azure Portal.The easiest way to create an Azure storage account is by using the Azure portal. Läs mer i Skapa ett lagringskonto.To learn more, see Create a storage account.

Du kan även skapa ett Azure-lagringskonto med hjälp av Azure PowerShell eller Azure CLI.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Om du föredrar att inte skapa ett lagringskonto just nu så kan du också använda Azure-lagringsemulatorn för att köra och testa din kod i en lokal miljö.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. Mer information finns i använda Azure Storage-emulatorn för utveckling och testning.For more information, see Use the Azure storage emulator for development and testing.

Skapa ett Azure Cosmos DB Table API-kontoCreate an Azure Cosmos DB Table API account

Anvisningar om hur du skapar ett Azure Cosmos DB Tabell-API konto finns i skapa ett databas konto.For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Installera Azure Cosmos DB Table SDK för PythonInstall the Azure Cosmos DB Table SDK for Python

När du har skapat ett lagringskonto är nästa steg att installera Microsoft Azure Cosmos DB Table SDK för Python.After you've created a Storage account, your next step is to install the Microsoft Azure Cosmos DB Table SDK for Python. Mer information om hur du installerar SDK-paketet finns i filen README.rst i databasen för Cosmos DB Table SDK för Python på GitHub.For details on installing the SDK, refer to the README.rst file in the Cosmos DB Table SDK for Python repository on GitHub.

Importera TableService- och Entity-klassernaImport the TableService and Entity classes

När du arbetar med entiteter i Azure Table-tjänsten i Python använder du klasserna TableService och Entity.To work with entities in the Azure Table service in Python, you use the TableService and Entity classes. Importera båda klasserna genom att lägga till följande kod överst i Python-filen: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

Ansluta till Azure Table StorageConnect to Azure Table service

Du ansluter till tjänsten Table Storage i Azure Storage genom att skapa ett TableService-objekt som innehåller namnet på ditt lagringskonto och din kontonyckel.To connect to Azure Storage Table service, create a TableService object, and pass in your Storage account name and account key. Ersätt myaccount och mykey med kontonamnet och nyckeln.Replace myaccount and mykey with your account name and key.

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

Ansluta till Azure Cosmos DBConnect to Azure Cosmos DB

Du ansluter till Azure Cosmos DB genom att kopiera den primära anslutningssträngen från Azure-portalen och skapar sedan ett TableService-objekt genom att använda den kopierade anslutningssträngen: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;')

Skapa en tabellCreate a table

Skapa tabellen genom att anropa create_table.Call create_table to create the table.

table_service.create_table('tasktable')

Lägga till en entitet i en tabellAdd an entity to a table

Du lägger till en entitet genom att först skapa ett objekt som representerar entiteten. Därefter skickar du objektet till metoden 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. Entitetsobjektet kan vara en ordlista eller ett objekt av typen Entity och definierar entitetens egenskapsnamn och värden.The entity object can be a dictionary or an object of type Entity, and defines your entity's property names and values. Varje entitet måste innehålla de obligatoriska PartitionKey- och RowKey-egenskaperna, utöver andra egenskaper som du definierar för entiteten.Every entity must include the required PartitionKey and RowKey properties, in addition to any other properties you define for the entity.

I det här exemplet skapas ett ordlisteobjekt som representerar en entitet. Objektet skickas sedan till metoden insert_entity som lägger till det i tabellen: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)

I det här exemplet skapas ett Entity-objekt. Objektet skickas sedan till metoden insert_entity som lägger till det i tabellen: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 och RowKeyPartitionKey and RowKey

Du måste ange både en PartitionKey- och en RowKey-egenskap för varje entitet.You must specify both a PartitionKey and a RowKey property for every entity. Dessa är entiteternas unika identifierare eftersom de tillsammans bildar primärnyckeln för en entitet.These are the unique identifiers of your entities, as together they form the primary key of an entity. Du kan fråga mycket snabbare med dessa värden än du kan fråga andra entitetsegenskaper eftersom endast dessa egenskaper indexeras.You can query using these values much faster than you can query any other entity properties because only these properties are indexed.

Table Storage använder tabellen PartitionKey för att effektivt distribuera tabellentiteter mellan lagringsnoder.The Table service uses PartitionKey to intelligently distribute table entities across storage nodes. Entiteter som har samma PartitionKey lagras på samma nod.Entities that have the same PartitionKey are stored on the same node. RowKey är det unika ID:t för entiteten i den partition som egenskapen hör till.RowKey is the unique ID of the entity within the partition it belongs to.

Uppdatera en entitetUpdate an entity

Du kan uppdatera alla egenskapsvärden för en entitet genom att anropa metoden update_entity.To update all of an entity's property values, call the update_entity method. Det här exemplet beskriver hur du ersätter en befintlig entitet med en uppdaterad version: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)

Uppdateringen misslyckas om entiteten som ska uppdateras inte redan finns.If the entity that is being updated doesn't already exist, then the update operation will fail. Om du vill lagra en entitet oavsett om den finns eller inte använder du insert_or_replace_entity.If you want to store an entity whether it exists or not, use insert_or_replace_entity. I följande exempel ersätter det första anropet den befintliga entiteten.In the following example, the first call will replace the existing entity. Det andra anropet infogar en ny entitet eftersom det inte finns någon entitet med angiven partitionsnyckel (PartitionKey) och radnyckel (RowKey) i tabellen.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)

Tips

Metoden update_entity ersätter alla egenskaper och värden för en befintlig entitet, och kan också användas för att ta bort egenskaper från en befintlig entitet.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. Du kan använda metoden merge_entity om du vill uppdatera en befintlig entitet med nya eller ändrade egenskapsvärden utan att helt ersätta entiteten.You can use the merge_entity method to update an existing entity with new or modified property values without completely replacing the entity.

Ändra flera entiteterModify multiple entities

Du kan skicka flera åtgärder tillsammans i en batch för att säkerställa atomisk bearbetning av en begäran i Table Storage.To ensure the atomic processing of a request by the Table service, you can submit multiple operations together in a batch. Börja med att lägga till flera åtgärder i en batch med hjälp av klassen TableBatch.First, use the TableBatch class to add multiple operations to a single batch. Skicka sedan åtgärderna i en atomisk åtgärd genom att anropa TableService.commit_batch.Next, call TableService.commit_batch to submit the operations in an atomic operation. Alla entiteter som ska ändras tillsammans i en batch måste finnas i samma partition.All entities to be modified in batch must be in the same partition.

I det här exemplet läggs två entiteter till i en 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)

Batchar kan också användas med kontexthanterarsyntaxen: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)

Fråga efter en entitetQuery for an entity

Du kan hämta en entitet i en tabell genom att skicka entitetens PartitionKey och RowKey till metoden 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)

Fråga efter en uppsättning entiteterQuery a set of entities

Du kan hämta en uppsättning entiteter genom att ange en filtersträng med parametern filter.You can query for a set of entities by supplying a filter string with the filter parameter. Det här exemplet hämtar alla aktiviteter i Seattle genom att tillämpa ett filter på 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)

Fråga en deluppsättning entitetsegenskaperQuery a subset of entity properties

Du kan också begränsa vilka egenskaper som returneras för varje entitet i en fråga.You can also restrict which properties are returned for each entity in a query. Den här tekniken, kallad projektion, minskar bandbredden och kan förbättra frågeprestanda, i synnerhet för stora entiteter eller resultatuppsättningar.This technique, called projection, reduces bandwidth and can improve query performance, especially for large entities or result sets. Använd parametern select och ange namnen på egenskaperna som ska returneras till klienten.Use the select parameter and pass the names of the properties you want returned to the client.

Frågan i följande kod returnerar bara beskrivningarna av entiteter i tabellen.The query in the following code returns only the descriptions of entities in the table.

Anteckning

Följande kodfragment fungerar bara mot Azure Storage.The following snippet works only against the Azure Storage. Det kan inte användas med lagringsemulatorn.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)

Ta bort en entitetDelete an entity

Du kan ta bort en entitet genom att ange entitetens PartitionKey och RowKey i metoden delete_entity.Delete an entity by passing its PartitionKey and RowKey to the delete_entity method.

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

Ta bort en tabellDelete a table

Om du inte längre behöver en tabell eller någon av entiteterna i den kan du ta bort tabellen permanent från Azure Storage genom att anropa metoden delete_table.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')

Nästa stegNext steps