Guida introduttiva: Creare un'app dell'API Tabella con .NET SDK e Azure Cosmos DBQuickstart: Build a Table API app with .NET SDK and Azure Cosmos DB

Questa guida introduttiva descrive come usare .NET e l'API Tabelle di Azure Cosmos DB per creare un'app clonando un esempio di GitHub.This quickstart shows how to use .NET and the Azure Cosmos DB Table API to build an app by cloning an example from GitHub. La guida introduttiva illustra anche come creare un account Azure Cosmos DB e come usare Esplora dati per creare tabelle e entità nel portale di Azure basato sul Web.This quickstart also shows you how to create an Azure Cosmos DB account and how to use Data Explorer to create tables and entities in the web-based Azure portal.

PrerequisitiPrerequisites

Se Visual Studio 2019 non è ancora installato, è possibile scaricare e usare l'edizione gratuita Visual Studio 2019 Community Edition.If you don’t already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 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

  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 riquadro di spostamento sinistro selezionare Crea una risorsa.In the left navigation pane, select Create a resource. Selezionare Database e quindi Azure Cosmos DB.Select Databases and then select Azure Cosmos DB.

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

  3. Nella pagina Crea account Azure Cosmos DB immettere le impostazioni per il nuovo account Azure Cosmos DB:On the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account:

    ImpostazioneSetting ValoreValue DESCRIZIONEDescription
    SottoscrizioneSubscription Sottoscrizione in usoYour subscription Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Gruppo di risorseResource Group Creare un nuovo gruppo di risorseCreate new

    Immettere quindi lo stesso nome univoco specificato in IDThen enter the same unique name as provided in ID
    Selezionare Crea nuovo.Select Create new. Immettere quindi il nome di un nuovo gruppo di risorse per l'account.Then enter a new resource group name for your account. Per semplicità, usare lo stesso nome usato come ID.For simplicity, use the same name as your ID.
    Nome accountAccount Name Immettere un nome univocoEnter a unique name Immettere un nome univoco per identificare l'account Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account.

    L'ID può contenere solo lettere minuscole, numeri e il carattere trattino (-).The ID can use only lowercase letters, numbers, and the hyphen (-) character. Deve essere composto da un numero di caratteri compreso tra 3 e 31.It must be between 3 and 31 characters long.
    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: Core (SQL) per i database di documenti, Gremlin per i database a grafo, MongoDB per i database di documenti, Tabella di Azure e Cassandra.Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, Azure Table, and Cassandra. Attualmente, è necessario creare un account separato per ogni API.Currently, you must create a separate account for each API.

    Selezionare Tabella di Azure perché in questo argomento di avvio rapido si crea una tabella che funziona con l'API Tabella.Select Azure Table because in this quickstart you're creating a table that works with the Table API.

    Altre informazioni sull'API Tabella.Learn more about the Table API.
    LocalitàLocation Selezionare l'area più vicina agli utentiSelect the region closest to your users Selezionare una posizione geografica in cui ospitare l'account Azure Cosmos DB.Select a geographic location 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 data.

    È possibile lasciare i valori predefiniti (Disabilita) per le opzioni Ridondanza geografica e Scritture in più aree per evitare ulteriori addebiti di UR.You can leave the Geo-Redundancy and Multi-region Writes options at their default values (Disable) to avoid additional RU charges. È possibile ignorare le sezioni Rete e Tag.You can skip the Network and Tags sections.

  4. Selezionare Rivedi+Crea.Select Review+Create. Dopo aver completato la convalida, selezionare Crea per creare l'account.After the validation is complete, select Create to create the account.

    Pagina del nuovo account per Azure Cosmos DB

  5. La creazione dell'account richiede alcuni minuti.It takes a few minutes to create the account. Verrà visualizzato il messaggio La distribuzione è in corso.You'll see a message that states Your deployment is underway. Attendere il completamento della distribuzione e quindi selezionare Vai alla risorsa.Wait for the deployment to finish and then select Go to resource.

    Riquadro Notifiche del portale di Azure

Aggiungere una tabellaAdd a table

È ora possibile usare lo strumento Esplora dati nel portale di Azure per creare un database e una tabella.You can now use the Data Explorer tool in the Azure portal to create a database and table.

  1. Selezionare su Esplora dati > Nuova tabella.Select Data Explorer > New Table.

    Viene visualizzata l'area Add Table (Aggiungi tabella) all'estrema destra. Per vederla potrebbe essere necessario scorrere la schermata.The Add Table area is displayed on the far right, you may need to scroll right to see it.

    Esplora dati nel portale di Azure

  2. Nella pagina Add Table (Aggiungi tabella) immettere le impostazioni per la nuova tabella.In the Add Table page, enter the settings for the new table.

    ImpostazioneSetting Valore consigliatoSuggested value DESCRIZIONEDescription
    ID tabellaTable Id sample-tablesample-table ID della nuova tabella.The ID for your new table. I nomi delle tabelle presentano gli stessi requisiti relativi ai caratteri degli ID di database.Table names have the same character requirements as database ids. I nomi dei database devono avere una lunghezza compresa tra 1 e 255 caratteri e non possono contenere / \ # ? o spazi finali.Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    Velocità effettivaThroughput 400 UR/s400 RUs Modificare la velocità effettiva in 400 unità richiesta al secondo (UR/sec).Change the throughput to 400 request units per second (RU/s). Se si vuole ridurre la latenza, è possibile aumentare la velocità effettiva in un secondo momento.If you want to reduce latency, you can scale up the throughput later.
  3. Selezionare OK.Select OK.

  4. In Esplora dati verranno visualizzati il nuovo database e la nuova tabella.Data Explorer displays the new database and table.

    Esplora dati nel portale di Azure, con il nuovo database e la nuova raccolta

Aggiungere dati di esempioAdd sample data

È ora possibile aggiungere dati alla nuova tabella usando Esplora dati.You can now add data to your new table using Data Explorer.

  1. In Esplora dati espandere sample-table, selezionare Entità e quindi Aggiungi entità.In Data Explorer, expand sample-table, select Entities, and then select Add Entity.

    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 selezionare Aggiungi entità.Now add data to the PartitionKey value box and RowKey value box, and select Add Entity.

    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.You can now add more entities to your table, edit your entities, or query your data in Data Explorer. Esplora dati è anche lo strumento in cui è possibile ridimensionare la velocità effettiva e aggiungere stored procedure, funzioni definite dall'utente e trigger alla tabella.Data Explorer is also where you can scale your throughput and add stored procedures, user-defined functions, and triggers to your table.

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 un prompt dei comandi, creare una nuova cartella denominata git-samples e quindi chiudere il prompt dei comandi.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. Aprire una finestra del terminale Git, ad esempio Git Bash, ed eseguire il comando cd per passare a una nuova 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 the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. 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/azure-cosmos-table-dotnet-core-getting-started.git
    

Aprire l'applicazione di esempio in Visual StudioOpen the sample application in Visual Studio

  1. In Visual Studio scegliere Apri dal menu File, quindi scegliere Progetto/Soluzione.In Visual Studio, from the File menu, choose Open, then choose Project/Solution.

    Aprire la soluzione

  2. Passare alla cartella in cui è stata clonata l'applicazione di esempio e aprire il file TableStorage.sln.Navigate to the folder where you cloned the sample application and open the TableStorage.sln file.

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 il pulsante di copia sul lato destro della finestra per copiare la STRINGA DI CONNESSIONE PRIMARIA.Use the copy button on the right side of the window to copy the PRIMARY CONNECTION STRING.

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

  2. Aprire il file Settings.json in Visual Studio.In Visual Studio, open the Settings.json file.

  3. Incollare il valore del campo STRINGA DI CONNESSIONE PRIMARIA dal portale nel valore StorageConnectionString.Paste the PRIMARY CONNECTION STRING from the portal into the StorageConnectionString value. Incollare la stringa tra virgolette.Paste the string inside the quotes.

    {
       "StorageConnectionString": "<Primary connection string from Azure portal>"
    }
    
  4. Premere CTRL+S per salvare il file Settings.json.Press CTRL+S to save the Settings.json 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.

Compilare e distribuire l'appBuild and deploy the app

  1. In Visual Studio fare clic con il pulsante destro del mouse sul progetto CosmosTableSamples in Esplora soluzioni e quindi scegliere Gestisci pacchetti NuGet.In Visual Studio, right-click on the CosmosTableSamples project in Solution Explorer and then click Manage NuGet Packages.

    Manage NuGet Packages

  2. Nella casella Sfoglia di NuGet digitare Microsoft.Azure.Cosmos.Table.In the NuGet Browse box, type Microsoft.Azure.Cosmos.Table. Verrà trovata la libreria client per l'API Tabelle di Cosmos DB.This will find the Cosmos DB Table API client library. Si noti che questa libreria è attualmente disponibile per .NET Framework e .NET Standard.Note that this library is currently available for .NET Framework and .NET Standard.

    Scheda Sfoglia di NuGet

  3. Fare clic su Installa per installare la libreria Microsoft.Azure.Cosmos.Table.Click Install to install the Microsoft.Azure.Cosmos.Table library. Vengono installati il pacchetto dell'API Tabelle di Azure Cosmos DB e tutte le dipendenze.This installs the Azure Cosmos DB Table API package and all dependencies.

  4. Quando si esegue l'intera app, i dati di esempio vengono inseriti nell'entità tabella ed eliminati al termine, in modo da non visualizzare i dati inseriti se si esegue l'intero esempio.When you run the entire app, sample data is inserted into the table entity and deleted at the end so you won’t see any data inserted if you run the whole sample. È tuttavia possibile inserire alcuni punti di interruzione per visualizzare i dati.However you can insert some breakpoints to view the data. Aprire il file BasicSamples.cs e fare clic con il pulsante destro del mouse sulla riga 52, scegliere Punto di interruzione, quindi selezionare Inserisci punto di interruzione.Open BasicSamples.cs file and right-click on line 52, select Breakpoint, then select Insert Breakpoint. Inserire un altro punto di interruzione alla riga 55.Insert another breakpoint on line 55.

    Aggiunta di un punto di interruzione

  5. Premere F5 per eseguire l'applicazione.Press F5 to run the application. La finestra della console mostra il nome del nuovo database della tabella (in questo caso, demoa13b1) in Azure Cosmos DB.The console window displays the name of the new table database (in this case, demoa13b1) in Azure Cosmos DB.

    Output console

    Quando si raggiunge il primo punto di interruzione, tornare a Esplora dati nel portale di Azure.When you hit the first breakpoint, go back to Data Explorer in the Azure portal. Fare clic sul pulsante Aggiorna, espandere la tabella demo* e fare clic su Entità.Click the Refresh button, expand the demo* table, and click Entities. La scheda Entità a destra illustra la nuova entità che è stata aggiunta per Walter Harp.The Entities tab on the right shows the new entity that was added for Walter Harp. Si noti che il numero di telefono per la nuova entità è 425-555-0101.Note that the phone number for the new entity is 425-555-0101.

    Nuova entità

    Se viene visualizzato un errore che indica che non è stato trovato il file Settings.json durante l'esecuzione del progetto, è possibile risolvere il problema aggiungendo la voce XML seguente alle impostazioni del progetto.If you receive an error that says Settings.json file can’t be found when running the project, you can resolve it by adding the following XML entry to the project settings. Fare clic con il pulsante destro del mouse su CosmosTableSamples, scegliere il comando di modifica di CosmosTableSamples.csproj e aggiungere l'elemento itemGroup seguente:Right click on CosmosTableSamples, select Edit CosmosTableSamples.csproj and add the following itemGroup:

      <ItemGroup>
        <None Update="Settings.json">
          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
      </ItemGroup>
    
  6. Chiudere la scheda Entità in Esplora dati.Close the Entities tab in Data Explorer.

  7. Premere F5 per eseguire l'app fino al punto di interruzione successivo.Press F5 to run the app to the next breakpoint.

    Quando si raggiunge il punto di interruzione, passare al portale di Azure, fare clic di nuovo su Entità per aprire la scheda Entità e notare che il numero di telefono è stato aggiornato a 425-555-0105.When you hit the breakpoint, switch back to the Azure portal, click Entities again to open the Entities tab, and note that the phone number has been updated to 425-555-0105.

  8. Premere F5 per eseguire l'app.Press F5 to run the app.

    L'app aggiunge le entità da usare in un'app di esempio avanzata attualmente non supportata dall'API Tabelle.The app adds entities for use in an advanced sample app that the Table API currently does not support. L'app elimina quindi la tabella creata dall'app di esempio.The app then deletes the table created by the sample app.

  9. Nella finestra della console premere INVIO per terminare l'esecuzione dell'app.In the console window, press Enter to end the execution of the app.

Esaminare i contratti di servizio nel portale di AzureReview SLAs in the Azure portal

Il portale di Azure consente di monitorare la velocità effettiva, lo spazio di archiviazione, la disponibilità, la latenza e la coerenza dell'account Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. I grafici per le metriche associate a un contratto di servizio di Azure Cosmos DB indicano il valore previsto dal contratto di servizio rispetto alle prestazioni effettive.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Questo gruppo di metriche garantisce la trasparenza nel monitoraggio dei contratti di servizio.This suite of metrics makes monitoring your SLAs transparent.

Per esaminare le metriche e i contratti di servizio:To review metrics and SLAs:

  1. Selezionare Metriche nel menu di spostamento dell'account Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Selezionare una scheda, ad esempio Latenza, e quindi un intervallo di tempo sulla destra.Select a tab such as Latency, and select a timeframe on the right. Confrontare le righe relative ai valori effettivi e ai valori del contratto di servizio nei grafici.Compare the Actual and SLA lines on the charts.

    Gruppo di metriche di Azure Cosmos DB

  3. Esaminare le metriche nelle altre schede.Review the metrics on the other tabs.

Pulire le risorseClean up resources

Dopo aver completato le operazioni con l'app Web e l'account Azure Cosmos DB, è possibile eliminare le risorse di Azure create in modo da non incorrere in altri costi.When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Per eliminare le risorse:To delete the resources:

  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. Se il menu sinistro è compresso, selezionare il pulsante Espandi per espanderlo.If the left menu is collapsed, select Expand button to expand it.

  2. Selezionare il gruppo di risorse creato in questa guida di avvio rapido.Select the resource group you created for this quickstart.

    Selezionare il gruppo di risorse da eliminare

  3. Nella nuova finestra selezionare Elimina gruppo di risorse.In the new window, select Delete resource group.

    Eliminare il gruppo di risorse.

  4. Nella finestra successiva immettere il nome del gruppo di risorse da eliminare e quindi selezionare Elimina.In the next window, enter the name of the resource group to delete, and then select Delete.

Passaggi successiviNext steps

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.In this quickstart, you've learned how to create an Azure Cosmos DB account, create a table using the Data Explorer, and run an app. È ora possibile eseguire query sui dati tramite l'API di tabella.Now you can query your data using the Table API.