Guida introduttiva: Compilare un'app Web .NET usando l'account API SQL in Azure Cosmos DBQuickstart: Build a .NET web app using SQL API account in Azure Cosmos DB

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 usare Cosmos DB per creare ed eseguire rapidamente query su chiavi/valori, database di documenti e database a grafo che sfruttano i vantaggi delle funzionalità di distribuzione globale e scalabilità orizzontale alla base di Azure Cosmos DB.You can use Azure Cosmos DB to quickly create and query key/value databases, document databases, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Questa guida di avvio rapido illustra come usare il portale di Azure per creare un account API SQL di Azure Cosmos DB, creare un database e una raccolta di documenti e aggiungere dati alla raccolta.This quickstart demonstrates how to use the Azure portal to create an Azure Cosmos DB SQL API account, create a document database and collection, and add data to the collection. Si userà quindi un'app Web SQL .NET SDK per aggiungere altri dati alla raccolta.You then use a SQL .NET SDK web app to add more data to the collection.

In questa guida di avvio rapido si usa Esplora dati nel portale di Azure per creare il database e la raccolta.In this quickstart, you use Data Explorer in the Azure portal to create the database and collection. È anche possibile creare il database e la raccolta con il codice di esempio .NET.You can also create the database and collection by using the .NET sample code. Per altre informazioni, vedere Esaminare il codice .NET.To learn more, see Review the .NET code.

PrerequisitiPrerequisites

Visual Studio 2019 con il flusso di lavoro di sviluppo di Azure installatoVisual Studio 2019 with the Azure development workflow installed

Una sottoscrizione di Azure o un account di prova gratuito di Azure Cosmos DBAn Azure subscription or free Azure Cosmos DB trial account

Creare un account Azure Cosmos DBCreate an Azure Cosmos DB account

  1. Accedere al portale di Azure.Sign in to the Azure portal.

  2. Selezionare Crea una risorsa > Database > Azure Cosmos DB.Select Create a resource > Databases > Azure Cosmos DB.

    Riquadro Database nel portale di Azure

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

    ImpostazioneSetting ValoreValue DESCRIZIONEDescription
    SottoscrizioneSubscription Nome della sottoscrizioneSubscription name Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Gruppo di risorseResource Group Nome del gruppo di risorseResource group name Selezionare un gruppo di risorse oppure fare clic su Crea nuovo, quindi immettere un nome univoco per il nuovo gruppo di risorse.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nome accountAccount Name Immettere un nome univocoEnter a unique name Immettere un nome per identificare l'account Azure Cosmos.Enter a name to identify your Azure Cosmos account. Poiché all'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    L'ID può contenere solo lettere minuscole, numeri e il carattere trattino (-).The ID can only contain lowercase letters, numbers, and the hyphen (-) character. Deve avere una lunghezza compresa tra 3 e 31 caratteri.It must be between 3-31 characters in length.
    APIAPI Core (SQL)Core (SQL) 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) e MongoDB per dati dei documenti, Gremlin per i dati dei grafici, Tabelle di Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Attualmente, è necessario creare un account separato per ogni API.Currently, you must create a separate account for each API.

    Selezionare Core (SQL) per creare un database di documenti e una query con la sintassi SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    Altre informazioni sull'API SQL.Learn more about the SQL 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 is closest to your users to give them the fastest access to the data.

    Pagina del nuovo account per Azure Cosmos DB

  4. Selezionare Rivedi e crea.Select Review + create. È possibile ignorare le sezioni Rete e Tag.You can skip the Network and Tags sections.

  5. Esaminare le impostazioni dell'account e quindi selezionare Crea.Review the account settings, and then select Create. La creazione dell'account richiede alcuni minuti.It takes a few minutes to create the account. Attendere che la pagina del portale visualizzi La distribuzione è stata completata.Wait for the portal page to display Your deployment is complete.

    Riquadro Notifiche del portale di Azure

  6. Selezionare Vai alla risorsa per passare alla pagina dell'account Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    Pagina dell'account Azure Cosmos DB

Aggiungere un database e una raccoltaAdd a database and a collection

È possibile usare Esplora dati nel portale di Azure per creare un database e una raccolta.You can use the Data Explorer in the Azure portal to create a database and collection.

  1. Scegliere Esplora dati dal menu di spostamento sinistro nella pagina dell'account Azure Cosmos DB, quindi selezionare Nuovo contenitore.Select Data Explorer from the left navigation on your Azure Cosmos DB account page, and then select New Container.

    Può essere necessario scorrere verso destra per visualizzare la finestra Aggiungi contenitore.You may need to scroll right to see the Add Container window.

    Esplora dati nel portale di Azure, riquadro Aggiungi raccolta

  2. Nel riquadro Aggiungi contenitore immettere le impostazioni per la nuova raccolta.In the Add container pane, enter the settings for the new collection.

    ImpostazioneSetting Valore consigliatoSuggested value DESCRIZIONEDescription
    ID databaseDatabase ID ToDoListToDoList Immettere ToDoList come nome del nuovo database.Enter ToDoList as the name for the new database. I nomi dei database devono avere una lunghezza compresa tra 1 e 255 caratteri e non possono contenere /, \\, #, ? o spazi finali.Database names must contain from 1 through 255 characters, and they cannot contain /, \\, #, ?, or a trailing space. Selezionare l'opzione Provision database throughput (Provisioning delle unità di elaborazione del database) che consente di condividere le unità di elaborazione del database con tra tutti i contenitori al suo interno.Check the Provision database throughput option, it allows you to share the throughput provisioned to the database across all the containers within the database. Questa opzione permette anche di risparmiare sui costi.This option also helps with cost savings.
    Velocità effettivaThroughput 400400 Lasciare la velocità effettiva a 400 unità di richiesta al secondo (UR/s).Leave the throughput at 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.
    ID contenitoreContainer ID ItemsItems Immettere Items come nome della nuova raccolta.Enter Items as the name for your new collection. Gli ID delle raccolte prevedono gli stessi requisiti relativi ai caratteri dei nomi di database.Collection IDs have the same character requirements as database names.
    Chiave di partizionePartition key /category/category L'esempio descritto in questo articolo usa /category come chiave di partizione.The sample described in this article uses /category as the partition key.

    Non aggiungere chiavi univoche per questo esempio.Don't add Unique keys for this example. Le chiavi univoche consentono di aggiungere un livello di integrità dei dati al database garantendo l'univocità di uno o più valori per ogni chiave di partizione.Unique keys let you add a layer of data integrity to the database by ensuring the uniqueness of one or more values per partition key. Per altre informazioni, vedere Chiavi univoche in Azure Cosmos DB.For more information, see Unique keys in Azure Cosmos DB.

  3. Selezionare OK.Select OK. In Esplora dati vengono visualizzati il nuovo database e il nuovo contenitore creati.The Data Explorer displays the new database and the container that you created.

Aggiungere dati al databaseAdd data to your database

Aggiungere dati al nuovo database usando Esplora dati.Add data to your new database using Data Explorer.

  1. In Esplora dati espandere il database ToDoList e quindi il contenitore Elementi.In Data Explorer, expand the ToDoList database, and expand the Items container. Selezionare Elementi e quindi Nuovo elemento.Next, select Items, and then select New Item.

    Creare nuovi documenti in Esplora dati nel portale di Azure

  2. Aggiungere la struttura seguente al documento sul lato destro del riquadro Documenti:Add the following structure to the document on the right side of the Documents pane:

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Selezionare Salva.Select Save.

    Copiare i dati JSON e selezionare Salva in Esplora dati nel portale di Azure

  4. Selezionare Nuovo documento e creare e salvare un altro documento con un id univoco ed eventuali altri valori e proprietà desiderati.Select New Document again, and create and save another document with a unique id, and any other properties and values you want. I documenti possono avere qualsiasi struttura perché Azure Cosmos DB non impone alcuno schema ai dati.Your documents can have any structure, because Azure Cosmos DB doesn't impose any schema on your data.

Eseguire query sui datiQuery your data

È possibile usare le query in Esplora dati per recuperare e filtrare i dati.You can use queries in Data Explorer to retrieve and filter your data.

  1. Nella parte superiore della scheda Documenti di Esplora dati esaminare la query predefinita SELECT * FROM c.At the top of the Documents tab in Data Explorer, review the default query SELECT * FROM c. Questa query recupera e visualizza tutti i documenti presenti nella raccolta in ordine di ID.This query retrieves and displays all documents in the collection in ID order.

    La query predefinita in Esplora dati è 'SELECT * FROM c'

  2. Per modificare la query, selezionare Modifica filtro, sostituire la query predefinita con ORDER BY c._ts DESC, quindi selezionare Applica filtro.To change the query, select Edit Filter, replace the default query with ORDER BY c._ts DESC, and then select Apply Filter.

    Modificare la query predefinita aggiungendo ORDER BY c._ts DESC e facendo clic su Applica filtro.

    La query modificata elenca i documenti in ordine decrescente in base al timestamp, quindi il secondo documento creato appare ora in cima all'elenco.The modified query displays the documents in descending order based on their time stamp, so now your second document is listed first.

    Modifica della query in ORDER BY c._ts DESC e selezione di Applica filtro.

Se si ha familiarità con la sintassi SQL, è possibile immettere qualsiasi query SQL supportata nella casella del predicato della query.If you're familiar with SQL syntax, you can enter any supported SQL queries in the query predicate box. È anche possibile usare Esplora dati per creare stored procedure, funzioni definite dall'utente e trigger per eseguire la logica di business sul lato server.You can also use Data Explorer to create stored procedures, UDFs, and triggers for server-side business logic.

Esplora dati consente di accedere facilmente dal portale di Azure a tutte le funzionalità di accesso ai dati a livello di codice disponibili nelle API.Data Explorer provides easy Azure portal access to all of the built-in programmatic data access features available in the APIs. Si usa il portale anche per ridimensionare la velocità effettiva, ottenere le chiavi e le stringhe di connessione ed esaminare le metriche e i contratti di servizio per l'account Azure Cosmos DB.You also use the portal to scale throughput, get keys and connection strings, and review metrics and SLAs for your Azure Cosmos DB account.

Usare l'app Web .NET per gestire i datiUse the .NET web app to manage data

Per vedere come è facile interagire con i dati di Azure Cosmos DB a livello di codice, clonare l'app Web API SQL .NET di esempio da GitHub, aggiornare la stringa di connessione ed eseguire l'app per aggiornare i dati.To see how easy it is to work with your Azure Cosmos DB data programmatically, clone the sample SQL API .NET web app from GitHub, update the connection string, and run the app to update your data.

È anche possibile creare il database e il contenitore con il codice di esempio .NET.You could also create the database and the container by using the .NET sample code. Per altre informazioni, vedere Esaminare il codice .NET.To learn more, see Review the .NET code.

Clonare l'app di esempioClone the sample app

Clonare prima di tutto un'app API SQL in C# da GitHub.First, clone a C# SQL API app from GitHub.

  1. Aprire una finestra di terminale git, ad esempio Git Bash, creare una nuova directory denominata git-samples e passare alla directory:Open a git terminal window, such as Git Bash, create a new directory named git-samples, and change to it:

    mkdir /c/git-samples/
    cd /c/git-samples/
    
  2. Eseguire questo comando per clonare il repository di esempio e creare una copia dell'app di esempio nel computer:Run the following command to clone the sample repository and create a copy of the sample app on your computer:

    git clone https://github.com/Azure-Samples/documentdb-dotnet-todo-app.git
    

Aggiornare la stringa di connessioneUpdate the connection string

  1. Trovare e aprire il file todo.sln dell'app clonata in Visual Studio.Navigate to and open the todo.sln file of your cloned app in Visual Studio.

  2. In Esplora soluzioni di Visual Studio aprire il file web.config.In Visual Studio Solution Explorer, open the web.config file.

  3. Tornare al portale di Azure per copiare le informazioni della stringa di connessione da incollare nel file web.config.Go back to the Azure portal to copy your connection string information to paste into the web.config.

    1. Selezionare Chiavi nel menu di spostamento a sinistra dell'account Azure Cosmos DB.In your Azure Cosmos DB account left navigation, select Keys.

      Visualizzazione e copia di una chiave di accesso nel portale di Azure, pannello Chiavi

    2. In Chiavi di lettura/scrittura copiare il valore URI usando il pulsante di copia a destra e incollarlo nella chiave endpoint del file web.config. Ad esempio:Under Read-write Keys, copy the URI value using the copy button at the right, and paste it into the endpoint key in the web.config. For example:

      <add key="endpoint" value="https://mysqlapicosmosdb.documents.azure.com:443/" />

    3. Copiare il valore CHIAVE PRIMARIA e incollarlo nella chiave authKey del file web.config. Ad esempio:Copy the PRIMARY KEY value and paste it into the authKey key in the web.config. For example:

      <add key="authKey" value="19ZDNJAiYL26tmnRvoez6hmtIfBGwjun50PWRjNYMC2ig8Ob9hYk7Fq1RYSv8FcIYnh1TdBISvCh7s6yyb0000==" />

  4. Assicurarsi che i valori del database e della raccolta (anche detta contenitore) nel file web.config corrispondano ai nomi creati in precedenza.Make sure the database and collection (also called container) values in the web.config match the names you created earlier.

    <add key="database" value="ToDoList"/>
    <add key="collection" value="Items"/>
    
  5. Salvare il file web.config. L'app è stata aggiornata con tutte le informazioni necessarie per comunicare con Azure Cosmos DB.Save the web.config. You've now updated your app with all the information it needs to communicate with Azure Cosmos DB.

Eseguire l'app WebRun the web app

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

  2. Nella casella Sfoglia di NuGet digitare DocumentDB.In the NuGet Browse box, type DocumentDB.

  3. Nei risultati installare la versione 2.2.3 della libreria Microsoft.Azure.DocumentDB, se non è già stata installata.From the results, install the 2.2.3 version of Microsoft.Azure.DocumentDB library if not already installed. Verrà installato il pacchetto Microsoft.Azure.DocumentDB insieme a tutte le dipendenze.This installs the Microsoft.Azure.DocumentDB package and all dependencies.

    Se Gestione pacchetti NuGet visualizza un messaggio per indicare che mancano alcuni pacchetti nella soluzione, selezionare Ripristina per installarli da origini interne.If the NuGet Package Manager displays a message that some packages are missing from the solution, select Restore to install them from internal sources.

  4. Premere Ctrl+F5 per eseguire l'app nel browser.Select Ctrl+F5 to run the app in your browser.

  5. Selezionare Crea nuovo nell'app to-do e creare alcune nuove attività.Select Create New in the to-do app, and create a few new tasks.

    App elenco attività con dati di esempio

È possibile tornare a Esplora dati nel portale di Azure per visualizzare, modificare e usare questi nuovi dati, nonché eseguire query su di essi.You can go back to Data Explorer in the Azure portal to see, query, modify, and work with your new data.

Esaminare il codice .NETReview the .NET code

Questo passaggio è facoltativo.This step is optional. In questo argomento di avvio rapido sono stati creati un database e un contenitore nel portale di Azure e sono stati aggiunti dati di esempio usando l'esempio di .NET.In this quickstart, you created a database and a container in the Azure portal and added sample data by using the .NET sample. Tuttavia, è anche possibile creare il database e il contenitore usando l'esempio di .NET.However, you can also create the database and the container by using the .NET sample. Esaminare i frammenti di codice seguenti per scoprire come vengono create le risorse del database nel codice.Review the following snippets if you're interested in how database resources are created in the code. Tutti i frammenti di codice sono tratti dal file DocumentDBRepository.cs del progetto todo.The snippets are all taken from the DocumentDBRepository.cs file in the todo project.

  • Questo codice inizializza l'elemento DocumentClient:This code initializes the DocumentClient:

    client = new DocumentClient(new Uri(ConfigurationManager.AppSettings["endpoint"]), ConfigurationManager.AppSettings["authKey"]);
    
  • Questo codice crea il nuovo database con il metodo CreateDatabaseAsync:This code creates the new database by using the CreateDatabaseAsync method:

    await client.CreateDatabaseAsync(new Database { Id = DatabaseId });
    
  • Il codice seguente crea la nuova raccolta con il metodo CreateDocumentCollectionAsync:The following code creates the new collection by using the CreateDocumentCollectionAsync method:

    private static async Task CreateCollectionIfNotExistsAsync(string partitionkey)
    {
       try
       {       
        await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri(DatabaseId, CollectionId), new RequestOptions { PartitionKey = new PartitionKey(partitionkey) });
       }
        catch (DocumentClientException e)
        {
           if (e.StatusCode == System.Net.HttpStatusCode.NotFound)
            {
                await client.CreateDocumentCollectionAsync(
                  UriFactory.CreateDatabaseUri(DatabaseId),
                   new DocumentCollection
                    {
                      Id = CollectionId,
                      PartitionKey = new PartitionKeyDefinition
                       {
                           Paths = new System.Collections.ObjectModel.Collection<string>(new List<string>() { partitionkey })
                        }
                    },
                      new RequestOptions { OfferThroughput = 400 });
            }
            else
            {
                throw;
            }
        }
    }
    

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.

    Metriche nel portale di Azure

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

    Metriche nel portale di Azure

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

Passaggi successiviNext steps

In questo argomento di avvio rapido si è appreso come creare un account Azure Cosmos DB, come creare un database e un contenitore con Esplora dati e come eseguire un'app Web .NET per aggiornare i dati.In this quickstart, you learned how to create an Azure Cosmos DB account, create a database and container using the Data Explorer, and run a .NET web app to update your data. È ora possibile importare dati aggiuntivi nell'account Azure Cosmos DB.You can now import additional data to your Azure Cosmos DB account.