Azure Cosmos DB: sviluppare con l'API Table in .NETAzure Cosmos DB: Develop with the Table API in .NET

Azure Cosmos DB è il servizio di database di Microsoft multimodello distribuito a livello globale.Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. È possibile creare ed eseguire rapidamente query su database di documenti, coppie chiave-valore e grafi, sfruttando in ognuno dei casi i vantaggi offerti dalle funzionalità di scalabilità orizzontale e distribuzione globale alla base di Azure Cosmos DB.You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Questa esercitazione illustra le attività seguenti:This tutorial covers the following tasks:

  • Creare un account Azure Cosmos DBCreate an Azure Cosmos DB account
  • Abilitare la funzionalità nel file app.configEnable functionality in the app.config file
  • Creare una tabella tramite l'API TableCreate a table using the Table API
  • Aggiungere un'entità a una tabellaAdd an entity to a table
  • Inserire un batch di entitàInsert a batch of entities
  • Recuperare una singola entitàRetrieve a single entity
  • Eseguire query su entità tramite indici secondari automaticiQuery entities using automatic secondary indexes
  • Sostituire un'entitàReplace an entity
  • Eliminare un'entitàDelete an entity
  • Eliminare una tabellaDelete a table

Tabelle in Azure Cosmos DBTables in Azure Cosmos DB

Azure Cosmos DB mette a disposizione l'API Table per le applicazioni che necessitano di un archivio di coppie chiave-valore con una struttura senza schema.Azure Cosmos DB provides the Table API for applications that need a key-value store with a schema-less design. Sia l'API Table di Azure Cosmos DB che l'archiviazione tabelle di Azure supportano ora gli stessi SDK e le stesse API REST.Both Azure Cosmos DB Table API and Azure Table storage now support the same SDKs and REST APIs. È possibile usare Azure Cosmos DB per creare tabelle con requisiti di velocità effettiva elevata.You can use Azure Cosmos DB to create tables with high throughput requirements.

Questa esercitazione è rivolta agli sviluppatori che hanno acquisito familiarità con l'SDK di Archiviazione tabelle di Azure e che intendono usare le funzionalità Premium disponibili con Azure Cosmos DB.This tutorial is for developers who are familiar with the Azure Table storage SDK, and would like to use the premium features available with Azure Cosmos DB. È basata su Introduzione all'archiviazione tabelle di Azure con .NET e illustra come sfruttare le funzionalità aggiuntive, come gli indici secondari, la velocità effettiva con provisioning e il multihosting.It is based on Get Started with Azure Table storage using .NET and shows how to take advantage of additional capabilities like secondary indexes, provisioned throughput, and multi-homing. Questa esercitazione illustra come usare il portale di Azure per creare un account Azure Cosmos DB e quindi come compilare e distribuire un'applicazione API di tabella.This tutorial describes how to use the Azure portal to create an Azure Cosmos DB account, and then build and deploy a Table API application. Verranno esaminati anche esempi .NET per la creazione e l'eliminazione di una tabella, l'inserimento, l'aggiornamento, l'eliminazione e l'esecuzione di query per i dati delle tabelle.We also walk through .NET examples for creating and deleting a table, and inserting, updating, deleting, and querying table data.

Se attualmente si usa l'archiviazione tabelle di Azure, passando all'API Table di Azure Cosmos DB è possibile ottenere i vantaggi seguenti:If you currently use Azure Table storage, you gain the following benefits with Azure Cosmos DB Table API:

Questa esercitazione illustra l'API Table di Azure Cosmos DB tramite .NET SDK.This tutorial covers Azure Cosmos DB Table API using the .NET SDK. È possibile scaricare Azure Storage Preview SDK da NuGet.You can download the Azure Storage Preview SDK from NuGet.

Per altre informazioni sulle attività complesse di archiviazione tabelle di Azure, vedere:To learn more about complex Azure Table storage tasks, see:

Informazioni sull'esercitazioneAbout this tutorial

Questa esercitazione è rivolta agli sviluppatori con familiarità con l'SDK di archiviazione tabelle di Azure e che intendono usare le funzionalità Premium disponibili usando Azure Cosmos DB.This tutorial is for developers who are familiar with the Azure Table storage SDK, and would like to use the premium features available using Azure Cosmos DB. È basata su Introduzione all'archiviazione tabelle di Azure con .NET e illustra come sfruttare le funzionalità aggiuntive, come gli indici secondari, la velocità effettiva con provisioning e il multihosting.It is based on Get Started with Azure Table storage using .NET and shows how to take advantage of additional capabilities like secondary indexes, provisioned throughput, and multi-homing. Verrà illustrato come usare il portale di Azure per creare un account Azure Cosmos DB e quindi come compilare e distribuire un'applicazione di tabelle.We cover how to use the Azure portal to create an Azure Cosmos DB account, and then build and deploy a Table application. Verranno esaminati anche esempi .NET per la creazione e l'eliminazione di una tabella, l'inserimento, l'aggiornamento, l'eliminazione e l'esecuzione di query per i dati delle tabelle.We also walk through .NET examples for creating and deleting a table, and inserting, updating, deleting, and querying table data.

Se Visual Studio 2017 non è ancora installato, è possibile scaricare e usare la versione gratuita di Visual Studio 2017 Community Edition.If you don't already have Visual Studio 2017 installed, you can download and use the free Visual Studio 2017 Community Edition. Durante l'installazione di Visual Studio abilitare Sviluppo di Azure.Make sure that you enable Azure development during the Visual Studio setup.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.If you don't have an Azure subscription, create a free account before you begin.

Creare un account di databaseCreate a database account

Si inizia creando un account Azure Cosmos DB nel portale di Azure.Let's start by creating an Azure Cosmos DB account in the Azure portal.

Importante

Per lavorare con gli SDK dell'API di tabella disponibili a livello generale, è necessario creare un nuovo account dell'API di tabella.You need to create a new Table API account to work with the generally available Table API SDKs. Gli account dell'API di tabella creati durante l'anteprima non sono supportati dagli SDK disponibili a livello generale.Table API accounts created during preview are not supported by the generally available SDKs.

  1. In una nuova finestra del browser accedere al portale di Azure.In a new browser window, sign in to the Azure portal.
  2. Nel menu a sinistra fare clic su Nuovo, quindi su Database e in Azure Cosmos DB fare clic su Crea.In the left menu, click New, click Databases, and then under Azure Cosmos DB, click Create.

    Screenshot del portale di Azure in cui sono evidenziati Altri servizi e Azure Cosmos DB

  3. Nella pagina Nuovo account immettere le impostazioni per il nuovo account Azure Cosmos DB.In the New account page, enter the settings for the new Azure Cosmos DB account.

    ImpostazioneSetting Valore consigliatoSuggested value DescrizioneDescription
    IDID Immettere un nome univocoEnter a unique name Immettere un nome univoco per identificare l'account Azure Cosmos DB.Enter a unique name to identify this Azure Cosmos DB account. Poiché alI'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco ma facilmente identificabile.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique but identifiable ID.

    L'ID può contenere solo lettere minuscole, numeri e il segno meno (-) e deve avere una lunghezza compresa tra 3 e 50 caratteri.The ID can contain only lowercase letters, numbers, and the hyphen (-) character, and it must contain 3 to 50 characters.
    APIAPI tabella di AzureAzure Table L'API determina il tipo di account da creare.The API determines the type of account to create. Azure Cosmos DB offre cinque API per soddisfare le esigenze dell'applicazione, ovvero SQL (database di documenti) Gremlin (grafo), MongoDB, SQL (database di documenti), Tabella di Azure e Cassandra, per ognuna delle quali è attualmente necessario un account separato.Azure Cosmos DB provides five APIs to suits the needs of your application: SQL (document database), Gremlin (graph database), MongoDB (document database), Azure Table, and Cassandra, each which currently require a separate account.

    Selezionare Tabella di Azure perché in questa guida rapida si crea una tabella che funziona con l'API di tabella.Select Azure Table because in this quickstart you are creating a table that works with the Table API.

    Altre informazioni sull'API di tabellaLearn more about the Table API
    SottoscrizioneSubscription Immettere lo stesso nome univoco specificato sopra in IDEnter the same unique name as provided above in ID Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos DB.Select Azure subscription that you want to use for this Azure Cosmos DB account.
    Gruppo di risorseResource Group Stesso valore di IDThe same value as ID Immettere il nome di un nuovo gruppo di risorse per l'account.Enter a new resource-group name for your account. Per semplicità si può usare lo stesso nome usato come ID.For simplicity, you can use the same name as your ID.
    PercorsoLocation Selezionare l'area più vicina agli utentiSelect the region closest to your users Selezionare la posizione geografica in cui ospitare l'account Azure Cosmos DB.Select geographic location in which to host your Azure Cosmos DB account. Usare la località più vicina agli utenti per offrire loro la massima velocità di accesso ai dati.Use the location that's closest to your users to give them the fastest access to the data.
    Abilita ridondanza geograficaEnable geo-redundancy Lasciare vuotoLeave blank Consente di creare una versione replicata del database in una seconda area abbinata.This creates a replicated version of your database in a second (paired) region. Lasciare vuoto.Leave this blank.
    Aggiungi al dashboardPin to dashboard SelezionareSelect Selezionare questa casella per aggiungere il nuovo account di database al dashboard del portale e accedervi più facilmente.Select this box so that your new database account is added to your portal dashboard for easy access.

    Fare quindi clic su Crea.Then click Create.

    Screenshot del pannello Nuovo Azure Cosmos DB

  4. La creazione dell'account richiede alcuni minuti,The account creation takes a few minutes. durante i quali nel portale viene visualizzato il riquadro Distribuzione di Azure Cosmos DB.During account creation the portal displays the Deploying Azure Cosmos DB tile.

    Riquadro Notifiche del portale di Azure

    Al termine della creazione dell'account verrà visualizzata la pagina L'account Azure Cosmos DB è stato creato.Once the account is created, the Congratulations! Your Azure Cosmos DB account was created page is displayed.

Clonare l'applicazione di esempioClone the sample application

A questo punto è possibile clonare un'app Table da GitHub, impostare la stringa di connessione ed eseguirla.Now let's clone a Table app from github, set the connection string, and run it. Come si noterà, è facile usare i dati a livello di codice.You'll see how easy it is to work with data programmatically.

  1. Aprire una finestra del terminale Git, ad esempio git bash, ed eseguire il comando cd per passare a una cartella in cui installare l'app di esempio.Open a git terminal window, such as git bash, and use the cd command to change to a folder to install the sample app.

    cd "C:\git-samples"
    
  2. Eseguire il comando seguente per clonare l'archivio di esempio.Run the following command to clone the sample repository. Questo comando crea una copia dell'app di esempio nel computer in uso.This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/storage-table-dotnet-getting-started.git
    
  3. Aprire quindi il file della soluzione in Visual Studio.Then open the solution file in Visual Studio.

Aggiornare la stringa di connessioneUpdate your connection string

Tornare ora al portale di Azure per recuperare le informazioni sulla stringa di connessione e copiarle nell'app.Now go back to the Azure portal to get your connection string information and copy it into the app. Questo consente all'app di comunicare con il database ospitato.This enables your app to communicate with your hosted database.

  1. Nel portale di Azure fare clic su Stringa di connessione.In the Azure portal, click Connection String.

    Usare i pulsanti di copia sul lato destro della schermata per copiare la STRINGA DI CONNESSIONE PRIMARIA.Use the copy buttons on the right side of the screen to copy the PRIMARY CONNECTION STRING.

    Visualizzare e copiare la STRINGA DI CONNESSIONE nel riquadro Stringa di connessione

  2. In Visual Studio aprire il file app.config.In Visual Studio, open the app.config file.

  3. Rimuovere il commento di StorageConnectionString alla riga 8 e impostare come commento StorageConnectionString alla riga 7, in quanto questa esercitazione non usa l'emulatore di archiviazione.Uncomment the StorageConnectionString on line 8 and comment out the StorageConnectionString on line 7 as this tutorial does not use the Storage Emulator. Ora le righe 7 e 8 dovrebbero essere simili a quanto segue:Line 7 and 8 should now look like this:

    <!--key="StorageConnectionString" value="UseDevelopmentStorage=true;" />-->
    <add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=[AccountName];AccountKey=[AccountKey]" />
    
  4. Incollare la STRINGA DI CONNESSIONE PRIMARIA dal portale nel valore StorageConnectionString alla riga 8.Paste the PRIMARY CONNECTION STRING from the portal into the StorageConnectionString value on line 8. Incollare la stringa tra virgolette.Paste the string inside the quotes.

    Importante

    Se l'endpoint usa documents.azure.com, ovvero si dispone di un account di anteprima, è necessario creare un nuovo account dell'API di tabella per lavorare con l'SDK dell'API di tabella disponibile a livello generale.If your Endpoint uses documents.azure.com, that means you have a preview account, and you need to create a new Table API account to work with the generally available Table API SDK.

    Ora la riga 8 dovrebbe essere simile a quanto segue:Line 8 should now look similar to:

    <add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=txZACN9f...==;TableEndpoint=https://<account name>.table.cosmosdb.azure.com;" />
    
  5. Salvare il file app.config.Save the app.config file.

L'app è stata aggiornata con tutte le informazioni necessarie per comunicare con Azure Cosmos DB.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

Funzionalità di Azure Cosmos DBAzure Cosmos DB capabilities

Azure Cosmos DB supporta numerose funzionalità non disponibili nell'API di archiviazione tabelle di Azure.Azure Cosmos DB supports a number of capabilities that are not available in the Azure Table storage API.

Alcune funzionalità sono accessibili tramite nuovi overload a CreateCloudTableClient, che consente di specificare criteri di connessione e livello di coerenza.Certain functionality is accessed via new overloads to CreateCloudTableClient that enable one to specify connection policy and consistency level.

Impostazioni di connessione tabellaTable Connection Settings DESCRIZIONEDescription
Modalità di connessioneConnection Mode Azure Cosmos DB supporta due modalità di connettività.Azure Cosmos DB supports two connectivity modes. Nella modalità Gateway le richieste vengono sempre eseguite al gateway di Azure Cosmos DB, che le inoltra alle partizioni di dati corrispondenti.In Gateway mode, requests are always made to the Azure Cosmos DB gateway, which forwards it to the corresponding data partitions. Nella modalità di connettività Direct il client recupera il mapping delle tabelle alle partizioni e le richieste vengono eseguite direttamente nelle partizioni di dati.In Direct connectivity mode, the client fetches the mapping of tables to partitions, and requests are made directly against data partitions. È consigliabile usare il valore predefinito Direct.We recommend Direct, the default.
Protocollo di connessioneConnection Protocol Azure Cosmos DB supporta due protocolli di connessione: Https e Tcp.Azure Cosmos DB supports two connection protocols - Https and Tcp. Tcp è il valore predefinito e consigliato perché si tratta di un protocollo più leggero.Tcp is the default, and recommended because it is more lightweight.
Posizioni preferitePreferred Locations Elenco delimitato da virgole dei percorsi (multihosting) preferiti per le letture.Comma-separated list of preferred (multi-homing) locations for reads. Ogni account Azure Cosmos DB può essere associato a 1-30+ aree.Each Azure Cosmos DB account can be associated with 1-30+ regions. Ogni istanza del client può specificare un sottoinsieme di queste aree nell'ordine preferito per le letture a bassa latenza.Each client instance can specify a subset of these regions in the preferred order for low latency reads. Le aree devono essere denominate usando i nomi visualizzati, ad esempio, West US.The regions must be named using their display names, for example, West US. Vedere anche API multihosting.Also see Multi-homing APIs.
Livello di coerenzaConsistency Level È possibile ottenere un compromesso ottimale tra disponibilità, coerenza e latenza scegliendo tra cinque livelli di coerenza ben definiti: Strong, Session, Bounded-Staleness, ConsistentPrefix ed Eventual.You can trade off between latency, consistency, and availability by choosing between five well-defined consistency levels: Strong, Session, Bounded-Staleness, ConsistentPrefix, and Eventual. Il valore predefinito è Session.Default is Session. La scelta del livello di coerenza implica una differenza significativa a livello di prestazioni nelle installazioni con più aree.The choice of consistency level makes a significant performance difference in multi-region setups. Per i dettagli, vedere Livelli di coerenza.See Consistency levels for details.

L'altra funzionalità può essere abilitata tramite i valori di configurazione di appSettings seguenti.Other functionality can be enabled via the following appSettings configuration values.

ChiaveKey DESCRIZIONEDescription
TableQueryMaxItemCountTableQueryMaxItemCount Configurare il numero massimo di elementi restituiti per ogni query di tabella in un unico round trip.Configure the maximum number of items returned per table query in a single round trip. Il valore predefinito è -1, che consente ad Azure Cosmos DB di determinare in modo dinamico il valore in fase di runtime.Default is -1, which lets Azure Cosmos DB dynamically determine the value at runtime.
TableQueryEnableScanTableQueryEnableScan Se la query non può usare l'indice per tutti i filtri, eseguirla comunque tramite un'analisi.If the query cannot use the index for any filter, then run it anyway via a scan. Il valore predefinito è false.Default is false.
TableQueryMaxDegreeOfParallelismTableQueryMaxDegreeOfParallelism Il grado di parallelismo per l'esecuzione di una query tra partizioni.The degree of parallelism for execution of a cross-partition query. 0 è seriale senza prelettura, 1 è seriale con prelettura e valori più alti aumentano il grado di parallelismo.0 is serial with no pre-fetching, 1 is serial with pre-fetching, and higher values increase the rate of parallelism. Il valore predefinito è -1, che consente ad Azure Cosmos DB di determinare in modo dinamico il valore in fase di runtime.Default is -1, which lets Azure Cosmos DB dynamically determine the value at runtime.

Per cambiare il valore predefinito, aprire il file app.config da Esplora soluzioni in Visual Studio.To change the default value, open the app.config file from Solution Explorer in Visual Studio. Aggiungere il contenuto dell'elemento <appSettings> illustrato di seguito.Add the contents of the <appSettings> element shown below. Sostituire account-name con il nome dell'account di archiviazione e account-key con la chiave di accesso dell'account.Replace account-name with the name of your storage account, and account-key with your account access key.

<configuration>
    ...
    <appSettings>
      <!-- Client options -->
      <add key="CosmosDBStorageConnectionString" 
        value="DefaultEndpointsProtocol=https;AccountName=MYSTORAGEACCOUNT;AccountKey=AUTHKEY;TableEndpoint=https://account-name.table.cosmosdb.azure.com" />
      <add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=account-name;AccountKey=account-key; TableEndpoint=https://account-name.documents.azure.com" />

      <!-- Table query options -->
      <add key="TableQueryMaxItemCount" value="-1"/>
      <add key="TableQueryEnableScan" value="false"/>
      <add key="TableQueryMaxDegreeOfParallelism" value="-1"/>
      <add key="TableQueryContinuationTokenLimitInKb" value="16"/>

    </appSettings>
</configuration>

Ecco una breve panoramica delle operazioni eseguire nell'app.Let's make a quick review of what's happening in the app. Aprire il file Program.cs. Come si noterà, queste righe di codice creano le risorse di tabella.Open the Program.cs file and you will find that these lines of code create the Table resources.

Creare il client di tabellaCreate the table client

Inizializzare CloudTableClient per connettersi all'account di tabella.You initialize a CloudTableClient to connect to the table account.

CloudTableClient tableClient = storageAccount.CreateCloudTableClient();

Questo client viene inizializzato usando i valori di configurazione TableConnectionMode, TableConnectionProtocol, TableConsistencyLevel e TablePreferredLocations, se specificato nelle impostazioni dell'app.This client is initialized using the TableConnectionMode, TableConnectionProtocol, TableConsistencyLevel, and TablePreferredLocations configuration values if specified in the app settings.

Creare una tabellaCreate a table

Creare quindi una tabella usando CloudTable.Then, you create a table using CloudTable. La scalabilità delle tabelle in Azure Cosmos DB può essere indipendente in termini di archiviazione e velocità effettiva e il partizionamento viene gestito automaticamente dal servizio.Tables in Azure Cosmos DB can scale independently in terms of storage and throughput, and partitioning is handled automatically by the service. Azure Cosmos DB supporta le tabelle sia senza limitazioni sia con dimensioni fisse.Azure Cosmos DB supports both fixed size and unlimited tables. Vedere Partizionamento in Azure Cosmos DB per informazioni dettagliate.See Partitioning in Azure Cosmos DB for details.

CloudTable table = tableClient.GetTableReference("people");
400
table.CreateIfNotExists(throughput: 800);

Esiste una differenza importante nella creazione delle tabelle.There is an important difference in how tables are created. Azure Cosmos DB riserva la velocità effettiva, a differenza del modello in base al consumo di Archiviazione di Azure per le transazioni.Azure Cosmos DB reserves throughput, unlike Azure storage's consumption-based model for transactions. La velocità effettiva è dedicata/riservata. Non viene quindi mai limitata se la frequenza di richiesta è pari o inferiore alla velocità effettiva di provisioning.Your throughput is dedicated/reserved, so you never get throttled if your request rate is at or below your provisioned throughput.

È possibile configurare la velocità effettiva predefinito includendolo come un parametro di CreateIfNotExists.You can configure the default throughput by including it as a parameter of CreateIfNotExists.

La lettura di un'entità di 1 KB viene normalizzata come 1 UR e le altre operazioni vengono normalizzate in una UR a valore fisso in base al consumo di CPU, memoria e IOPS.A read of a 1-KB entity is normalized as 1 RU, and other operations are normalized to a fixed RU value based on their CPU, memory, and IOPS consumption. Altre informazioni sulle unità richiesta in Azure Cosmos DB e in particolare per gli archivi di valori chiave.Learn more about Request units in Azure Cosmos DB and specifically for key value stores.

Verranno quindi illustrate le semplici operazioni di lettura e scrittura (CRUD) usando questo SDK.Next, we walk through the simple read and write (CRUD) operations using the Azure Table storage SDK. Questa esercitazione illustra le latenze pari a singole unità di millisecondi e le query rapide fornite da Azure Cosmos DB.This tutorial demonstrates predictable low single-digit millisecond latencies and fast queries provided by Azure Cosmos DB.

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

Le entità in archiviazione tabelle di Azure si estendono dalla classe TableEntity e devono avere le proprietà PartitionKey e RowKey.Entities in Azure Table storage extend from the TableEntity class and must have PartitionKey and RowKey properties. Di seguito è riportata una definizione di esempio per un'entità cliente.Here's a sample definition for a customer entity.

public class CustomerEntity : TableEntity
{
    public CustomerEntity(string lastName, string firstName)
    {
        this.PartitionKey = lastName;
        this.RowKey = firstName;
    }

    public CustomerEntity() { }

    public string Email { get; set; }

    public string PhoneNumber { get; set; }
}

Il frammento di codice seguente illustra come inserire un'entità con l'SDK di Archiviazione di Azure.The following snippet shows how to insert an entity with the Azure storage SDK. Azure Cosmos DB è progettato per garantire una latenza ridotta su qualsiasi unità di scala, in tutto il mondo.Azure Cosmos DB is designed for guaranteed low latency at any scale, across the world.

Le scritture vengono completate in < 15 ms a p99 e ms ~ 6 a p50 per le applicazioni in esecuzione nella stessa area dell'account Azure Cosmos DB.Writes complete <15 ms at p99 and ~6 ms at p50 for applications running in the same region as the Azure Cosmos DB account. Questa durata tiene conto del fatto che le scritture vengono confermate al client solo dopo la relativa replica sincrona, il commit permanente e l'indicizzazione di tutto il contenuto.And this duration accounts for the fact that writes are acknowledged back to the client only after they are synchronously replicated, durably committed, and all content is indexed.

// Create a new customer entity.
CustomerEntity customer1 = new CustomerEntity("Harp", "Walter");
customer1.Email = "Walter@contoso.com";
customer1.PhoneNumber = "425-555-0101";

// Create the TableOperation object that inserts the customer entity.
TableOperation insertOperation = TableOperation.Insert(customer1);

// Execute the insert operation.
table.Execute(insertOperation);

Inserire un batch di entitàInsert a batch of entities

L'archiviazione tabelle di Azure supporta un'API di operazioni batch che consente di combinare gli aggiornamenti, le eliminazioni e gli inserimenti nella stessa operazione batch.Azure Table storage supports a batch operation API, that lets you combine updates, deletes, and inserts in the same batch operation.

// Create the batch operation.
TableBatchOperation batchOperation = new TableBatchOperation();

// Create a customer entity and add it to the table.
CustomerEntity customer1 = new CustomerEntity("Smith", "Jeff");
customer1.Email = "Jeff@contoso.com";
customer1.PhoneNumber = "425-555-0104";

// Create another customer entity and add it to the table.
CustomerEntity customer2 = new CustomerEntity("Smith", "Ben");
customer2.Email = "Ben@contoso.com";
customer2.PhoneNumber = "425-555-0102";

// Add both customer entities to the batch insert operation.
batchOperation.Insert(customer1);
batchOperation.Insert(customer2);

// Execute the batch operation.
table.ExecuteBatch(batchOperation);

Recuperare una singola entitàRetrieve a single entity

I recuperi (GET) in Azure Cosmos DB vengono completati in < 10 ms a p99 e ~ 1 ms a p50 nella stessa area di Azure.Retrieves (GETs) in Azure Cosmos DB complete <10 ms at p99 and ~1 ms at p50 in the same Azure region. È possibile aggiungere il numero desiderato di aree al proprio account per le letture a bassa latenza e distribuire le applicazioni da leggere dall'area locale ("multihosting") impostando TablePreferredLocations.You can add as many regions to your account for low latency reads, and deploy applications to read from their local region ("multi-homed") by setting TablePreferredLocations.

È possibile recuperare una singola entità tramite il frammento seguente:You can retrieve a single entity using the following snippet:

// Create a retrieve operation that takes a customer entity.
TableOperation retrieveOperation = TableOperation.Retrieve<CustomerEntity>("Smith", "Ben");

// Execute the retrieve operation.
TableResult retrievedResult = table.Execute(retrieveOperation);

Suggerimento

Informazioni sulle API multihosting in Sviluppo con più areeLearn about multi-homing APIs at Developing with multiple regions

Eseguire query su entità tramite indici secondari automaticiQuery entities using automatic secondary indexes

È possibile eseguire query sulle tabelle usando la classe TableQuery.Tables can be queried using the TableQuery class. Azure Cosmos DB dispone di un motore di database con ottimizzazione per la scrittura che indicizza automaticamente tutte le colonne all'interno della tabella.Azure Cosmos DB has a write-optimized database engine that automatically indexes all columns within your table. L'indicizzazione in Azure Cosmos DB è indipendente dallo schema.Indexing in Azure Cosmos DB is agnostic to schema. Anche se lo schema è diverso da una riga all'altra o se lo schema cambia nel tempo, l'indicizzazione viene eseguita automaticamente.Therefore, even if your schema is different between rows, or if the schema evolves over time, it is automatically indexed. Poiché Azure Cosmos DB supporta gli indici secondari automatici, le query su qualsiasi proprietà possono usare l'indice e possono essere gestite in modo efficiente.Since Azure Cosmos DB supports automatic secondary indexes, queries against any property can use the index and be served efficiently.

CloudTable table = tableClient.GetTableReference("people");

// Filter against a property that's not partition key or row key
TableQuery<CustomerEntity> emailQuery = new TableQuery<CustomerEntity>().Where(
    TableQuery.GenerateFilterCondition("Email", QueryComparisons.Equal, "Ben@contoso.com"));

foreach (CustomerEntity entity in table.ExecuteQuery(emailQuery))
{
    Console.WriteLine("{0}, {1}\t{2}\t{3}", entity.PartitionKey, entity.RowKey,
        entity.Email, entity.PhoneNumber);
}

Azure Cosmos DB supporta le stesse funzionalità relative alle query rispetto all'archiviazione tabelle di Azure per l'API Table.Azure Cosmos DB supports the same query functionality as Azure Table storage for the Table API. Azure Cosmos DB supporta anche l'ordinamento, le aggregazioni, le query geospaziali, la gerarchia e un'ampia gamma di funzioni predefinite.Azure Cosmos DB also supports sorting, aggregates, geospatial query, hierarchy, and a wide range of built-in functions. La funzionalità aggiuntiva verrà fornita nell'API Table in un aggiornamento futuro del servizio.The additional functionality will be provided in the Table API in a future service update. Vedere Query in Azure Cosmos DB per una panoramica di queste funzionalità.See Azure Cosmos DB query for an overview of these capabilities.

Sostituire un'entitàReplace an entity

Per aggiornare un'entità, recuperarla dal servizio tabelle, modificare l'oggetto entità e quindi salvare le modifiche nel servizio tabelle.To update an entity, retrieve it from the Table service, modify the entity object, and then save the changes back to the Table service. Il codice seguente consente di modificare il numero di telefono di un cliente esistente.The following code changes an existing customer's phone number.

TableOperation updateOperation = TableOperation.Replace(updateEntity);
table.Execute(updateOperation);

Analogamente, è possibile eseguire operazioni InsertOrMerge o Merge.Similarly, you can perform InsertOrMerge or Merge operations.

Eliminare un'entitàDelete an entity

Per eliminare facilmente un'entità dopo averla recuperata, è possibile usare lo stesso modello illustrato per aggiornare un'entità.You can easily delete an entity after you have retrieved it by using the same pattern shown for updating an entity. Il codice seguente consente di recuperare ed eliminare un'entità customer.The following code retrieves and deletes a customer entity.

TableOperation deleteOperation = TableOperation.Delete(deleteEntity);
table.Execute(deleteOperation);

Eliminare una tabellaDelete a table

L'esempio di codice seguente consente infine di eliminare una tabella dall'account di archiviazione.Finally, the following code example deletes a table from a storage account. È possibile eliminare e ricreare una tabella immediatamente con Azure Cosmos DB.You can delete and recreate a table immediately with Azure Cosmos DB.

CloudTable table = tableClient.GetTableReference("people");
table.DeleteIfExists();

Pulire le risorseClean up resources

Se non si intende continuare a usare l'app, eliminare tutte le risorse create tramite questa guida di avvio rapido eseguendo i passaggi seguenti, per evitare qualsiasi addebito:If you're not going to continue to use this app, delete all resources created by this quickstart with the following steps so you don't incur any charges:

  1. Nel portale di Azure fare clic su Gruppi di risorse all'estrema sinistra.In the Azure portal, select Resource groups on the far left.

    Metriche nel portale di Azure

  2. Nell'elenco dei gruppi di risorse selezionare il gruppo di risorse creato e quindi fare clic su Elimina gruppo di risorse.From the list of resource groups, select the resource group you created, and then click Delete resource group.

  3. Digitare il nome del gruppo di risorse da eliminare e fare clic su Elimina.Type the name of the resource group to delete, and then click Delete.

Passaggi successiviNext steps

In questa esercitazione è stato illustrato come iniziare a usare Azure Cosmos DB con l'API Table e sono state eseguite le operazioni seguenti:In this tutorial, we covered how to get started using Azure Cosmos DB with the Table API, and you've done the following:

  • Creazione di un account Azure Cosmos DBCreated an Azure Cosmos DB account
  • Abilitazione della funzionalità nel file app.configEnabled functionality in the app.config file
  • Creazione di una tabellaCreated a table
  • Aggiunta di un'entità a una tabellaAdded an entity to a table
  • Inserimento di un batch di entitàInserted a batch of entities
  • Recupero di una singola entitàRetrieved a single entity
  • Esecuzione di query di entità tramite indici secondari automaticiQueried entities using automatic secondary indexes
  • Sostituzione di un'entitàReplaced an entity
  • Eliminazione di un'entitàDeleted an entity
  • Eliminazione di una tabellaDeleted a table

È ora possibile passare all'esercitazione successiva per altre informazioni sull'esecuzione di query sui dati di tabelle.You can now proceed to the next tutorial and learn more about querying table data.