Azure Cosmos DB: Creare un'applicazione .NET tramite l'API di tabella

Azure Cosmos DB è il servizio di database multimodello distribuito a livello globale di Microsoft. È 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 guida di avvio rapido mostra come creare un account Azure Cosmos DB e come creare una tabella nell'account tramite il portale di Azure. Si scriverà quindi il codice per inserire, aggiornare ed eliminare le entità, oltre che eseguire alcune query usando il nuovo pacchetto Windows Azure Storage Premium Table disponibile su NuGet. Questa libreria include le stesse classi e firme di metodi disponibili nella versione pubblica di Azure Storage SDK, ma permette anche di connettersi agli account Azure Cosmos DB tramite l'API di tabella (anteprima).

Prerequisiti

Se Visual Studio 2017 non è ancora installato, è possibile scaricare e usare la versione gratuita 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

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

    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 Azure Cosmos DB nel riquadro Tutte le risorse

Aggiungere una tabella

È ora possibile usare Esplora dati per creare una tabella e aggiungere dati al database.

  1. Nel menu di navigazione del portale di Azure fare clic su Esplora dati (anteprima).
  2. Nel pannello Esplora dati fare clic su Nuova tabella e quindi compilare i campi della pagina con le informazioni seguenti.

    Esplora dati nel portale di Azure

    Impostazione Valore consigliato Descrizione
    ID tabella sample-table ID della nuova tabella. I nomi delle tabelle presentano gli stessi requisiti relativi ai caratteri degli ID di database. I nomi dei database devono avere una lunghezza compresa tra 1 e 255 caratteri e non possono contenere / \ # ? o spazi finali.
    Capacità di archiviazione 10 GB Lasciare il valore predefinito. Indica la capacità di archiviazione del database.
    Velocità effettiva 400 UR/s Lasciare il valore predefinito. È possibile aumentare la velocità effettiva in un secondo momento se si vuole ridurre la latenza.
  3. Dopo aver compilato il modulo, fare clic su OK.

Aggiungere dati di esempio

È ora possibile aggiungere dati alla nuova tabella usando Esplora dati (anteprima).

  1. In Esplora dati espandere sample-table, fare clic su Entità e quindi su Aggiungi entità.

    Creare nuove entità in Esplora dati nel portale di Azure

  2. Aggiungere ora i dati alle caselle dei valori di PartitionKey e RowKey e quindi fare clic su Aggiunti entità.

    Configurare la chiave di partizione e la chiave di riga per una nuova entità

    È ora possibile aggiungere altre entità alla tabella, modificare le entità o eseguire query sui dati in Esplora dati. Esplora dati è anche lo strumento in cui è possibile ridimensionare la velocità effettiva e aggiungere stored procedure, funzioni definite dall'utente e trigger alla tabella.

Clonare l'applicazione di esempio

A questo punto è possibile clonare un'app Table da GitHub, impostare la stringa di connessione ed eseguirla. Come si noterà, è facile usare i dati a livello di codice.

  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.git
    
  3. Aprire quindi il file della soluzione in Visual Studio.

Esaminare il codice

Ecco una breve analisi di ciò che accade nell'app. Aprire il file Program.cs. Come si noterà, queste righe di codice creano le risorse di Azure Cosmos DB.

  • Viene inizializzato CloudTableClient.

    CloudStorageAccount storageAccount = CloudStorageAccount.Parse(connectionString); 
    CloudTableClient tableClient = storageAccount.CreateCloudTableClient();
    
  • Se non esiste, viene creata una nuova tabella.

    CloudTable table = tableClient.GetTableReference("people");
    table.CreateIfNotExists();
    
  • Viene creato un nuovo contenitore di tabelle. Si noterà che questo codice è molto simile al normale SDK di archiviazione tabelle di Azure.

    CustomerEntity item = new CustomerEntity()
                {
                    PartitionKey = Guid.NewGuid().ToString(),
                    RowKey = Guid.NewGuid().ToString(),
                    Email = $"{GetRandomString(6)}@contoso.com",
                    PhoneNumber = "425-555-0102",
                    Bio = GetRandomString(1000)
                };
    

Aggiornare la stringa di connessione

Verranno ora aggiornate le informazioni sulla stringa di connessione, in modo che l'app possa comunicare con Azure Cosmos DB.

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

  2. Nel portale di Azure nel menu di spostamento a sinistra di Azure Cosmos DB scegliere Stringa di connessione. Nel nuovo riquadro fare quindi clic sul pulsante Copia per la stringa di connessione.

    Visualizzare e copiare l'endpoint e la chiave dell'account nel riquadro Stringa di connessione

  3. Incollare il valore nel file app.config come il valore di PremiumStorageConnectionString.

    <add key="PremiumStorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=MYSTORAGEACCOUNT;AccountKey=AUTHKEY;TableEndpoint=https://COSMOSDB.documents.azure.com" />

    È possibile lasciare inalterato StandardStorageConnectionString.

L'app è stata aggiornata con tutte le informazioni necessarie per comunicare con Azure Cosmos DB.

Eseguire l'app Web

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

  2. Nella casella Sfoglia di NuGet digitare WindowsAzure.Storage-PremiumTable.

  3. Selezionare la casella Includi versione preliminare.

  4. Dai risultati installare la libreria WindowsAzure.Storage-PremiumTable. Viene installato il pacchetto dell'API di tabella di Azure Cosmos DB di anteprima, insieme a tutte le dipendenze. Si noti che si tratta di un pacchetto NuGet diverso rispetto al pacchetto di Archiviazione di Azure usato dall'archiviazione tabelle di Azure.

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

    La finestra della console mostra i dati aggiunti, recuperati, sottoposti a query, sostituiti ed eliminati dalla tabella. Al termine dello script, premere qualsiasi tasto per chiudere la finestra della console.

    Output della console della guida rapida

  6. Per visualizzare le nuove entità in Esplora dati, è sufficiente impostare come commento le righe 188-208 nel file program.cs, in modo che non vengano eliminate, quindi eseguire di nuovo l'esempio.

    È ora possibile tornare a Esplora dati, fare clic su Aggiorna, espandere la tabella people, fare clic su Entità e infine usare i nuovi dati.

    Nuove entità in Esplora dati

Esaminare i contratti di servizio nel portale di Azure

Ora che l'app è operativa, è opportuno garantire la continuità aziendale e controllare l'accesso degli utenti per garantire disponibilità elevata. Per esaminare la disponibilità, la latenza, la velocità effettiva e la coerenza della raccolta, si può usare il portale di Azure.

Ogni grafo associato ai contratti di servizio per Azure Cosmos DB fornisce una linea che mostra la quota necessaria per soddisfare il contratto di servizio e l'utilizzo effettivo. Queste informazioni offrono una panoramica chiara sulle prestazioni del database. Nel portale sono anche incluse altre metriche, ad esempio per quanto riguarda l'uso dello spazio di archiviazione e il numero di richieste al minuto.

  • Nel riquadro a sinistra del portale di Azure, in Monitoraggio, selezionare Metriche.

    App elenco attività con dati di esempio

Pulire le risorse

Se non si intende continuare a usare l'app, eliminare tutte le risorse create tramite questa guida di avvio rapido nel portale di Azure eseguendo questi passaggi:

  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 guida di avvio rapido si è appreso come creare un account Azure Cosmos DB, come creare una tabella con Esplora dati e come eseguire un'app. È ora possibile eseguire query sui dati tramite l'API di tabella.