Azure Cosmos DB: sviluppare con l'API Table in .NET

Azure Cosmos DB è il servizio di database di Microsoft multimodello distribuito a livello globale. È 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.

Questa esercitazione illustra le attività seguenti:

  • Creare un account Azure Cosmos DB
  • Abilitare la funzionalità nel file app.config
  • Creare una tabella usando l'API Table (anteprima)
  • Aggiungere un'entità a una tabella
  • Inserire un batch di entità
  • Recuperare una singola entità
  • Eseguire query su entità tramite indici secondari automatici
  • Sostituire un'entità
  • Eliminare un'entità
  • Eliminare una tabella

Tabelle in Azure Cosmos DB

Azure Cosmos DB fornisce l'API Table (anteprima) per le applicazioni che necessitano di un archivio di coppie chiave-valore con una struttura senza schema. È possibile usare gli SDK e le API REST di archiviazione tabelle di Azure insieme ad Azure Cosmos DB. È possibile usare Azure Cosmos DB per creare tabelle con requisiti di velocità effettiva elevata. Azure Cosmos DB supporta le tabelle ottimizzate per la velocità effettiva, chiamate in modo informale "tabelle Premium", attualmente disponibili in anteprima pubblica.

È possibile continuare a usare l'archiviazione tabelle di Azure per le tabelle con requisiti di archiviazione elevati e di velocità effettiva inferiori. Azure Cosmos DB introdurrà il supporto per le tabelle ottimizzate per l'archiviazione in uno dei prossimi aggiornamenti e gli account di archiviazione tabelle di Azure nuovi ed esistenti verranno aggiornati facilmente ad Azure Cosmos DB.

Se attualmente si usa l'archiviazione tabelle di Azure, è possibile ottenere i vantaggi seguenti con "tabella Premium" in anteprima:

Nella fase di anteprima Azure Cosmos DB supporta l'API Table usando .NET SDK. È possibile scaricare Azure Storage Preview SDK da NuGet, che include le stesse classi e firme di metodi disponibili in Azure Storage SDK, ma che permette anche di connettersi agli account Azure Cosmos DB tramite l'API Table.

Per altre informazioni sulle attività complesse di archiviazione tabelle di Azure, vedere:

Informazioni sull'esercitazione

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. È 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. 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. 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.

Se Visual Studio 2017 non è ancora installato, è possibile scaricare e usare la versione gratuita di Visual Studio 2017 Community Edition. Durante l'installazione di Visual Studio abilitare Sviluppo di Azure.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Creare un account di database

Si inizia creando un account Azure Cosmos DB nel portale di Azure.

Suggerimento
  1. In una nuova finestra accedere al portale di Azure.
  2. Nel menu a sinistra fare clic su Nuovo, scegliere Database e quindi Azure Cosmos DB.

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

  3. Nel pannello Nuovo account specificare la configurazione desiderata per l'account Azure Cosmos DB.

    Con Azure Cosmos DB è possibile scegliere uno dei quattro modelli di programmazione: Gremlin (graph), MongoDB, SQL (DocumentDB) e Table (key-value).

    In questa guida introduttiva eseguiremo la programmazione in base all'API di tabella, per cui occorrerà scegliere Table (key-value) nella compilazione del modulo. Tuttavia, se si dispone di dati grafo per un'app social media, dati documento di un'app di catalogo o dati migrati da un'app MongoDB, tenere presente che Azure Cosmos DB può fornire una piattaforma di servizi di database distribuiti a livello globale e a disponibilità elevata per tutte le applicazioni cruciali.

    Compilare il pannello Nuovo account usando le informazioni riportate nello screenshot come guida. Scegliere valori univoci per l'impostazione del proprio account in modo che i valori immessi non corrispondano esattamente a quelli dello screenshot.

    Screenshot del pannello Nuovo Azure Cosmos DB

    Impostazione Valore consigliato Descrizione
    ID Valore univoco Nome univoco scelto per identificare l'account Azure Cosmos DB. Poiché alI'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco ma facilmente identificabile. L'ID può contenere solo lettere minuscole, numeri e il carattere '-' e deve avere una lunghezza compresa tra 3 e 50 caratteri.
    API Table (key-value) Eseguiremo la programmazione in base all'API di tabella più avanti in questo articolo.
    Sottoscrizione Sottoscrizione in uso Sottoscrizione di Azure da usare per l'account Azure Cosmos DB.
    Gruppo di risorse Stesso valore di ID Nome del nuovo gruppo di risorse per l'account. Per semplicità si può usare lo stesso nome usato come ID.
    Località Area più vicina ai propri utenti Posizione geografica in cui ospitare l'account Azure Cosmos DB. Scegliere la posizione più vicina ai propri utenti per fornire loro l'accesso più rapido possibile ai dati.
  4. Fare clic su Crea per creare l'account.

  5. Sulla barra degli strumenti fare clic su Notifiche per monitorare il processo di distribuzione.

    Notifica di distribuzione avviata

  6. Al termine della distribuzione aprire il nuovo account dal riquadro Tutte le risorse.

    Account DocumentDB nel riquadro Tutte le risorse

Clonare l'applicazione di esempio

A questo punto è possibile clonare un'app Table da GitHub, impostare la stringa di connessione ed eseguirla.

  1. Aprire una finestra del terminale Git, ad esempio Git Bash ed eseguire il comando cd per passare a una directory di lavoro.

  2. Eseguire il comando seguente per clonare l'archivio di esempio.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-table-dotnet-getting-started
    
  3. Aprire quindi il file della soluzione in Visual Studio.

Aggiornare la stringa di connessione

Tornare ora al portale di Azure per recuperare le informazioni sulla stringa di connessione e copiarle nell'app.

  1. Nell'account Azure Cosmos DB nel portale di Azure fare clic su Chiavi nel riquadro di spostamento a sinistra e quindi su Chiavi di lettura/scrittura. Usare i pulsanti di copia sul lato destro dello schermo per copiare la stringa di connessione nel file app.config nel passaggio seguente.

  2. In Visual Studio aprire il file app.config.

  3. Copiare il valore di URI dal portale usando il pulsante di copia e impostarlo come valore della chiave dell'account in app.config. Usare il nome dell'account creato in precedenza per il nome dell'account in app.config.

<add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=account-name;AccountKey=account-key;TableEndpoint=https://account-name.documents.azure.com" />
Nota

Per usare questa app con archiviazione tabelle di Azure standard, è necessario modificare la stringa di connessione in app.config file. Usare il nome dell'account come nome dell'account Table e la chiave come chiave primaria di Archiviazione di Azure.
<add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=account-name;AccountKey=account-key;EndpointSuffix=core.windows.net" />

Compilare e distribuire l'app

  1. In Visual Studio fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e scegliere Gestisci pacchetti NuGet.

  2. Nella casella Sfoglia di NuGet digitare WindowsAzure.Storage-PremiumTable. Selezionare Includi versione preliminare.

  3. Dai risultati installare WindowsAzure.Storage-PremiumTable e scegliere la compilazione di anteprima 0.0.1-preview. Questa azione consente di installare il pacchetto di archiviazione tabelle di Azure e tutte le dipendenze.

  4. Premere CTRL + F5 per eseguire l'applicazione.

È ora possibile tornare a Esplora dati ed esaminare, eseguire query, modificare e lavorare con i dati di tabella.

Nota

Per usare questa app con un emulatore Azure Cosmos DB, è sufficiente modificare la stringa di connessione in app.config file. Usare il valore seguente per l'emulatore.
<add key="StorageConnectionString" value=DefaultEndpointsProtocol=https;AccountName=localhost;AccountKey=<insertkey>==;TableEndpoint=https://localhost -->

Funzionalità di Azure Cosmos DB

Azure Cosmos DB supporta numerose funzionalità non disponibili nell'API di archiviazione tabelle di Azure. La nuova funzionalità può essere abilitata tramite i valori di configurazione di appSettings seguenti. Non sono stati introdotti nuovi overload o firme nell'SDK di Archiviazione in anteprima. È quindi possibile connettersi alle tabelle sia Standard sia Premium e usare gli altri servizi di Archiviazione di Azure, come BLOB e code.

Chiave Descrizione
TableConnectionMode Azure Cosmos DB supporta due modalità di connettività. Nella modalità Gateway le richieste vengono sempre eseguite al gateway di Azure Cosmos DB, che le inoltra alle partizioni di dati corrispondenti. Nella modalità di connettività Direct il client recupera il mapping delle tabelle alle partizioni e le richieste vengono eseguite direttamente nelle partizioni di dati. È consigliabile usare il valore predefinito Direct.
TableConnectionProtocol Azure Cosmos DB supporta due protocolli di connessione: Https e Tcp. Tcp è il valore predefinito e consigliato perché si tratta di un protocollo più leggero.
TablePreferredLocations Elenco delimitato da virgole dei percorsi (multihosting) preferiti per le letture. Ogni account Azure Cosmos DB può essere associato a 1-30+ aree. Ogni istanza del client può specificare un sottoinsieme di queste aree nell'ordine preferito per le letture a bassa latenza. Le aree devono essere denominate usando i nomi visualizzati, ad esempio, West US. Vedere anche API multihosting.
TableConsistencyLevel È 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. Il valore predefinito è Session. La scelta del livello di coerenza implica una differenza significativa a livello di prestazioni nelle installazioni con più aree. Per i dettagli, vedere Livelli di coerenza.
TableThroughput Velocità effettiva riservata per la tabella espressa in unità di richiesta (UR) al secondo. Le singole tabelle possono supportare centinaia di milioni di UR/s. Vedere Unità richiesta. Il valore predefinito è 400
TableIndexingPolicy Indicizzazione secondaria coerente e automatica di tutte le colonne all'interno di tabelle
TableQueryMaxItemCount Configurare il numero massimo di elementi restituiti per ogni query di tabella in un unico round trip. Il valore predefinito è -1, che consente ad Azure Cosmos DB di determinare in modo dinamico il valore in fase di runtime.
TableQueryEnableScan Se la query non può usare l'indice per tutti i filtri, eseguirla comunque tramite un'analisi. Il valore predefinito è false.
TableQueryMaxDegreeOfParallelism Il grado di parallelismo per l'esecuzione di una query tra partizioni. 0 è seriale senza prelettura, 1 è seriale con prelettura e valori più alti aumentano il grado di parallelismo. Il valore predefinito è -1, che consente ad Azure Cosmos DB di determinare in modo dinamico il valore in fase di runtime.

Per cambiare il valore predefinito, aprire il file app.config da Esplora soluzioni in Visual Studio. Aggiungere il contenuto dell'elemento <appSettings> illustrato di seguito. Sostituire account-name con il nome dell'account di archiviazione e account-key con la chiave di accesso dell'account.

<configuration>
    <startup> 
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.2" />
    </startup>
    <appSettings>
      <!-- Client options -->
      <add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=account-name;AccountKey=account-key; TableEndpoint=https://account-name.documents.azure.com" />
      <add key="TableConnectionMode" value="Direct"/>
      <add key="TableConnectionProtocol" value="Tcp"/>
      <add key="TablePreferredLocations" value="East US, West US, North Europe"/>
      <add key="TableConsistencyLevel" value="Eventual"/>

      <!--Table creation options -->
      <add key="TableThroughput" value="700"/>
      <add key="TableIndexingPolicy" value="{""indexingMode"": ""Consistent""}"/>

      <!-- 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. Aprire il file Program.cs. Come si noterà, queste righe di codice creano le risorse di tabella.

Creare il client di tabella

Inizializzare CloudTableClient per connettersi all'account di tabella.

CloudTableClient tableClient = storageAccount.CreateCloudTableClient();

Questo client viene inizializzato usando i valori di configurazione TableConnectionMode, TableConnectionProtocol, TableConsistencyLevel e TablePreferredLocations, se specificato nelle impostazioni dell'app.

Creare una tabella

Creare quindi una tabella usando 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. Azure Cosmos DB supporta le tabelle sia senza limitazioni sia con dimensioni fisse. Vedere Partizionamento in Azure Cosmos DB per informazioni dettagliate.

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

table.CreateIfNotExists();

Esiste una differenza importante nella creazione delle tabelle. Azure Cosmos DB riserva la velocità effettiva, a differenza del modello in base al consumo di Archiviazione di Azure per le transazioni. Il modello di prenotazione offre due vantaggi principali:

È possibile configurare la velocità effettiva predefinita configurando l'impostazione per TableThroughput in termini di UR (unità di richiesta) al secondo.

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. Altre informazioni sulle unità richiesta in Azure Cosmos DB.

Nota

Anche se l'SDK di archiviazione tabelle non supporta attualmente la modifica della velocità effettiva, è possibile modificare questo valore in qualsiasi momento tramite il portale di Azure o l'interfaccia della riga di comando di Azure.

Verranno quindi illustrate le semplici operazioni di lettura e scrittura (CRUD) usando questo SDK. Questa esercitazione illustra le latenze pari a singole unità di millisecondi e le query rapide fornite da Azure Cosmos DB.

Aggiungere un'entità a una tabella

Le entità in archiviazione tabelle di Azure si estendono dalla classe TableEntity e devono avere le proprietà PartitionKey e RowKey. Di seguito è riportata una definizione di esempio per un'entità cliente.

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. Azure Cosmos DB è progettato per garantire una latenza ridotta su qualsiasi unità di scala, in tutto il mondo.

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. 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.

L'API Table di Azure Cosmos DB è disponibile in anteprima. A livello di disponibilità generale, le garanzia di latenza p99 sono supportate dai contratti di servizio, come per le altre API di Azure Cosmos DB.

// 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à

Archiviazione tabelle di Azure supporta un'API di operazioni batch che consente di combinare gli aggiornamenti, le eliminazioni e gli inserimenti nella stessa singola operazione batch. Azure Cosmos DB non prevede alcune limitazioni all'API batch come archiviazione tabelle di Azure. Ad esempio, è possibile eseguire più letture all'interno di un batch, più scritture nella stessa entità all'interno di un batch e non esiste il limite di 100 operazioni per ogni batch.

// 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à

I recuperi (GET) in Azure Cosmos DB vengono completati in < 10 ms a p99 e ~ 1 ms a p50 nella stessa area di Azure. È 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.

È possibile recuperare una singola entità tramite il frammento seguente:

// 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ù aree

Eseguire query su entità tramite indici secondari automatici

È possibile eseguire query sulle tabelle usando la classe TableQuery. Azure Cosmos DB dispone di un motore di database con ottimizzazione per la scrittura che indicizza automaticamente tutte le colonne all'interno della tabella. L'indicizzazione in Azure Cosmos DB è indipendente dallo schema. Anche se lo schema è diverso da una riga all'altra o se lo schema cambia nel tempo, l'indicizzazione viene eseguita automaticamente. 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.

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);
}

In anteprima Azure Cosmos DB supporta le stesse funzionalità relative alle query di archiviazione tabelle di Azure per l'API Table. Azure Cosmos DB supporta anche l'ordinamento, le aggregazioni, le query geospaziali, la gerarchia e un'ampia gamma di funzioni predefinite. La funzionalità aggiuntiva verrà fornita nell'API Table in un aggiornamento futuro del servizio. Vedere Query in Azure Cosmos DB per una panoramica di queste funzionalità.

Sostituire un'entità

Per aggiornare un'entità, recuperarla dal servizio tabelle, modificare l'oggetto entità e quindi salvare le modifiche nel servizio tabelle. Il codice seguente consente di modificare il numero di telefono di un cliente esistente.

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

Analogamente, è possibile eseguire operazioni InsertOrMerge o Merge.

Eliminare un'entità

Per eliminare facilmente un'entità dopo averla recuperata, è possibile usare lo stesso modello illustrato per aggiornare un'entità. Il codice seguente consente di recuperare ed eliminare un'entità customer.

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

Eliminare una tabella

L'esempio di codice seguente consente infine di eliminare una tabella dall'account di archiviazione. È possibile eliminare e ricreare una tabella immediatamente con Azure Cosmos DB.

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

Pulire le risorse

Se non si prevede di continuare a usare questa app, seguire questa procedura per eliminare tutte le risorse create da questa esercitazione nel portale di Azure.

  1. Scegliere Gruppi di risorse dal menu a sinistra del portale di Azure e quindi fare clic sul nome della risorsa creata.
  2. Nella pagina del gruppo di risorse fare clic su Elimina, digitare il nome della risorsa da eliminare nella casella di testo e quindi fare clic su Elimina.

Passaggi successivi

In questa esercitazione è stato illustrato come iniziare a usare Azure Cosmos DB con l'API Table e sono state eseguite le operazioni seguenti:

  • Creazione di un account Azure Cosmos DB
  • Abilitazione della funzionalità nel file app.config
  • Creazione di una tabella
  • Aggiunta di un'entità a una tabella
  • Inserimento di un batch di entità
  • Recupero di una singola entità
  • Esecuzione di query di entità tramite indici secondari automatici
  • Sostituzione di un'entità
  • Eliminazione di un'entità
  • Eliminazione di una tabella

È ora possibile passare all'esercitazione successiva per altre informazioni sull'esecuzione di query sui dati di tabelle.