Azure Cosmos DB: Creare un'applicazione Python usando l'account API SQL di Azure Cosmos DBAzure Cosmos DB: Build a Python application using Azure Cosmos DB SQL API account

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. Questo servizio consente di creare rapidamente database di documenti, chiave/valore e a grafo e di eseguire query su di essi.You can quickly create and query documents, key/value, and graph databases. Tutte queste operazioni traggono vantaggio dalla distribuzione e scalabilità di Azure Cosmos DB.All of these operations benefit from the distribution and scale of Azure Cosmos DB.

Questa guida introduttiva illustra come creare un account dell'API SQL di Azure Cosmos DB, un database di documenti e un contenitore usando il portale di Azure.This quickstart demonstrates how to create an Azure Cosmos DB SQL API account, document database, and container using the Azure portal. Quindi, si creerà ed eseguirà un'app console creata con Python SDK per API SQL.You then build and run a console app built with the Python SDK for SQL API. Questa guida introduttiva usa la versione 3.0 del [Python SDK]. (https://pypi.org/project/azure-cosmos)This quickstart uses version 3.0 of the [Python SDK].(https://pypi.org/project/azure-cosmos)

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. È possibile provare Microsoft Azure Cosmos DB senza una sottoscrizione di Azure, gratuitamente e senza impegno.You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. In alternativa, è possibile usare l'Emulatore di Azure Cosmos DB con l'URI https://localhost:8081.Or, you can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. La chiave primaria viene fornita in Autenticazione delle richieste.The Primary Key is provided in Authenticating requests.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. È possibile provare Microsoft Azure Cosmos DB senza una sottoscrizione di Azure, gratuitamente e senza impegno.You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. In alternativa, è possibile usare l'Emulatore di Azure Cosmos DB con l'URI https://localhost:8081.Or, you can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. La chiave primaria viene fornita in Autenticazione delle richieste.The Primary Key is provided in Authenticating requests.

PrerequisitiPrerequisites

Creare un account di databaseCreate a database 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 una raccoltaAdd a collection

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

  1. Fare clic su Esplora dati > Nuova raccolta.Click Data Explorer > New Collection.

    A destra verrà visualizzata l'area Aggiungi raccolta. Per vederla potrebbe essere necessario scorrere verso destra.The Add Collection area is displayed on the far right, you may need to scroll right to see it.

    Esplora dati nel portale di Azure, riquadro Aggiungi raccolta

  2. Nella pagina Aggiungi raccolta immettere le impostazioni per la nuova raccolta.In the Add collection page, enter the settings for the new collection.

    ImpostazioneSetting Valore consigliatoSuggested value DESCRIZIONEDescription
    ID databaseDatabase id AttivitàTasks Immettere Tasks come nome del nuovo database.Enter Tasks 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.
    ID raccoltaCollection 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 <Your partition key> Immettere una chiave di partizione, ad esempio /userid.Enter a partition key such as /userid.
    Velocità effettivaThroughput 400 UR400 RU 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.

    Oltre alle impostazioni precedenti, è possibile aggiungere Chiavi univoche per la raccolta.In addition to the preceding settings, you can optionally add Unique keys for the collection. In questo esempio il campo viene lasciato vuoto.Let's leave the field empty in this example. Le chiavi univoche consentono agli sviluppatori di aggiungere un livello di integrità dei dati nel database.Unique keys provide developers with the ability to add a layer of data integrity to the database. Se si definiscono criteri di chiave univoca durante la creazione di una raccolta, si ha la sicurezza che uno o più valori siano univoci per ogni chiave di partizione.By creating a unique key policy while creating a collection, you ensure the uniqueness of one or more values per partition key. Per altre informazioni, vedere l'articolo Chiavi univoche in Azure Cosmos DB.To learn more, refer to the Unique keys in Azure Cosmos DB article.

    Fare clic su OK.Click OK.

    In Esplora dati verranno visualizzati il nuovo database e la nuova raccolta.Data Explorer displays the new database and collection.

    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 raccolta usando Esplora dati.You can now add data to your new collection using Data Explorer.

  1. In Esplora dati il nuovo database viene visualizzato nel riquadro Raccolte.In Data Explorer, the new database appears in the Collections pane. Espandere il database Tasks, espandere la raccolta Items, fare clic su Documenti e quindi su Nuovo documento.Expand the Tasks database, expand the Items collection, click Documents, and then click New Documents.

    Creare nuovi documenti in Esplora dati nel portale di Azure

  2. Aggiungere ora un documento alla raccolta con la struttura seguente.Now add a document to the collection with the following structure.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Dopo avere aggiunto il codice JSON alla scheda Documenti, fare clic su Salva.Once you've added the json to the Documents tab, click Save.

    Copiare i dati JSON e fare clic su Salva in Esplora dati nel portale di Azure

  4. Creare e salvare un altro documento inserendo un valore univoco per la proprietà id e modificando le altre proprietà come si preferisce.Create and save one more document where you insert a unique value for the id property, and change the other properties as you see fit. I nuovi documenti possono avere la struttura desiderata, perché Azure Cosmos DB non impone alcuno schema per i dati.Your new documents can have any structure you want as 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.

Clonare l'applicazione di esempioClone the sample application

Clonare ora un'app per le API SQL da GitHub, impostare la stringa di connessione ed eseguirla.Now let's clone a SQL API app from GitHub, set the connection string, and run it.

  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-db-python-getting-started.git
    

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.

  1. Nell'account Azure Cosmos DB nel portale di Azure nel riquadro di spostamento a sinistra fare clic su Chiavi.In the Azure portal, in your Azure Cosmos DB account, in the left navigation click Keys. Usare i pulsanti di copia sul lato destro dello schermo per copiare URI e Chiave primaria nel file CosmosGetStarted.py nel passaggio seguente.You'll use the copy buttons on the right side of the screen to copy the URI and Primary Key into the CosmosGetStarted.py file in the next step.

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

  2. Aprire il file CosmosGetStarted.py in C:\git-samples\azure-cosmos-db-python-getting-started in Visual Studio Code.Open the CosmosGetStarted.py file in C:\git-samples\azure-cosmos-db-python-getting-started in Visual Studio Code.

  3. Copiare il valore di URI dal portale (usando il pulsante di copia) e impostarlo come valore della chiave di endpoint in CosmosGetStarted.py.Copy your URI value from the portal (using the copy button) and make it the value of the endpoint key in CosmosGetStarted.py.

    'ENDPOINT': 'https://FILLME.documents.azure.com',

  4. Copiare quindi il valore di CHIAVE PRIMARIA dal portale e impostarlo come valore di config.PRIMARYKEY in CosmosGetStarted.py.Then copy your PRIMARY KEY value from the portal and make it the value of the config.PRIMARYKEY in CosmosGetStarted.py. 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.

    'PRIMARYKEY': 'FILLME',

  5. Salvare il file.CosmosGetStarted.pySave the CosmosGetStarted.py file.

Esaminare il codiceReview the code

Questo passaggio è facoltativo.This step is optional. È possibile ottenere informazioni sulle risorse di database create in codice oppure passare direttamente a Aggiornare la stringa di connessione.Learn about the database resources created in code, or skip ahead to Update your connection string.

Si noti che, se si ha familiarità con la versione precedente di Python SDK, ci si potrebbe aspettare di vedere termini come "raccolta" e "documento".Note, if you are familiar with the previous version of the Python SDK, you may be used to seeing the terms "collection" and "document." Poiché Azure Cosmos DB supporta più modelli di API, nella versione 3.0+ di Python SDK vengono usati i termini generici "contenitore", che può essere una raccolta, un grafo o una tabella, ed "elemento" per descrivere il contenuto del contenitore.Because Azure Cosmos DB supports multiple API models, version 3.0+ of the Python SDK uses the generic terms "container,", which may be a collection, graph, or table and "item" to describe the content of the container.

Tutti i frammenti di codice seguenti sono tratti dal file CosmosGetStarted.py.The following snippets are all taken from the CosmosGetStarted.py file.

  • Viene inizializzato CosmosClient.The CosmosClient is initialized. Assicurarsi di aggiornare i valori di "Endpoint" e "chiave master" come descritto nella sezione Aggiornare la stringa di connessione.Make sure to update the "Endpoint" and "master key" values as described in the Update your connection string section.

    # Initialize the Cosmos client
    client = cosmos_client.CosmosClient(url_connection=config['ENDPOINT'], auth={'masterKey': config['MASTERKEY']})
    
  • Viene creato un nuovo database.A new database is created.

    # Create a database
    db = client.CreateDatabase({ 'id': config['DATABASE'] })
    
  • Viene creata una nuova raccolta.A new collection is created.

    # Create collection options
    options = {
        'offerThroughput': 400
    }
    
    # Create a container
    container = client.CreateContainer(db['_self'], container_definition, options)
    
  • Alcuni elementi vengono aggiunti al contenitore.Some items are added to the container.

    # Create and add some items to the container
    item1 = client.CreateItem(container['_self'], {
        'serverId': 'server1',
        'Web Site': 0,
        'Cloud Service': 0,
        'Virtual Machine': 0,
        'message': 'Hello World from Server 1!'
        }
    )
    
    item2 = client.CreateItem(container['_self'], {
        'serverId': 'server2',
        'Web Site': 1,
        'Cloud Service': 0,
        'Virtual Machine': 0,
        'message': 'Hello World from Server 2!'
        }
    )
    
  • Viene eseguita una query con SQLA query is performed using SQL

    query = {'query': 'SELECT * FROM server s'}
    
    options = {}
    options['enableCrossPartitionQuery'] = True
    options['maxItemCount'] = 2
    
    result_iterable = client.QueryItems(container['_self'], query, options)
    for item in iter(result_iterable):
        print(item['message'])
    

Esecuzione dell'appRun the app

  1. In Visual Studio Code selezionare Visualizza>Riquadro comandi.In Visual Studio Code, select View>Command Palette.

  2. Al prompt immettere Python: Select Interpreter e quindi selezionare la versione di Python da usare.At the prompt, enter Python: Select Interpreter and then select the version of Python to use.

    Il piè di pagina in Visual Studio Code viene aggiornato per indicare l'interprete selezionato.The Footer in Visual Studio Code is updated to indicate the interpreter selected.

  3. Selezionare Visualizza > Terminale integrato per aprire il terminale integrato di Visual Studio Code.Select View > Integrated Terminal to open the Visual Studio Code integrated terminal.

  4. Nella finestra del terminale integrato, verificare di essere nella cartella azure-cosmos-db-python-getting-started.In the integrated terminal window, ensure you are in the azure-cosmos-db-python-getting-started folder. In caso contrario, eseguire il comando seguente per passare alla cartella di esempio.If not, run the following command to switch to the sample folder.

    cd "C:\git-samples\azure-cosmos-db-python-getting-started"`
    
  5. Eseguire il seguente comando per installare il pacchetto azure-cosmos.Run the following command to install the azure-cosmos package.

    pip3 install azure-cosmos
    

    Se si riceve un errore di accesso negato durante il tentativo di installazione azure-cosmos, sarà necessario eseguire VS Code come amministratore.If you get an error about access being denied when attempting to install azure-cosmos, you'll need to run VS Code as an administrator.

  6. Eseguire il comando seguente per eseguire l'esempio e creare e archiviare nuovi documenti in Azure Cosmos DB.Run the following command to run the sample and create and store new documents in Azure Cosmos dB.

    python CosmosGetStarted.py
    
  7. Per verificare che i nuovi elementi siano stati creati e salvati, nel portale di Azure selezionare Esplora dati, espandere coll, espandere Documenti e quindi selezionare il documento server1.To confirm the new items were created and saved, in the Azure portal, select Data Explorer, expand coll, expand Documents, and then select the server1 document. Il contenuto del documento server1 corrisponde al contenuto restituito nella finestra del terminale integrato.The server1 document contents match the content returned in the integrated terminal window.

    Visualizzare i nuovi documenti nel portale di Azure

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

La velocità effettiva, lo spazio di archiviazione, la disponibilità, la latenza e la coerenza delle risorse nell'account vengono monitorati nel portale di Azure.The throughput, storage, availability, latency, and consistency of the resources in your account are monitored in the Azure portal. Di seguito vengono illustrate brevemente queste metriche.Let's take a quick look at these metrics.

  1. Fare clic su Metriche nel menu di spostamento.Click Metrics in the navigation menu.

    Metriche nel portale di Azure

  2. Fare clic su ogni scheda per conoscere le metriche offerte da Azure Cosmos DB.Click through each of the tabs so you're aware of the metrics Azure Cosmos DB provides.

    Ogni grafico associato ai contratti di servizio per Azure Cosmos DB contiene una linea che indica le eventuali violazioni dei contratti di servizio.Each chart that's associated with the Azure Cosmos DB Service Level Agreements (SLAs) provides a line that shows if any of the SLAs have been violated. Con questo gruppo di metriche, Azure Cosmos DB garantisce trasparenza nel monitoraggio dei contratti di servizio.Azure Cosmos DB makes monitoring your SLAs transparent with this suite of metrics.

    Gruppo di metriche di Azure Cosmos DB

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 selezionare Gruppi di risorse all'estrema sinistra e quindi selezionare il gruppo di risorse creato.In the Azure portal, select Resource groups on the far left, and then select the resource group you created.

    Se il menu a sinistra è compresso, fare clic sulIf the left menu is collapsed, click pulsante Espandi per espanderlo.to expand it.

    Metriche nel portale di Azure

  2. Nella nuova finestra selezionare il gruppo di risorse e quindi fare clic su Elimina gruppo di risorse.In the new window select the resource group, and then click Delete resource group.

    Metriche nel portale di Azure

  3. Nella nuova finestra digitare il nome del gruppo di risorse da eliminare e quindi fare clic su Elimina.In the new window, type the name of the resource group to delete, and then click Delete.

Passaggi successiviNext steps

In questa guida di avvio rapido si è appreso come creare un account Azure Cosmos DB, come creare una raccolta con Esplora dati e come eseguire un'app.In this quickstart, you've learned how to create an Azure Cosmos DB account, create a collection using the Data Explorer, and run an app. È ora possibile importare dati aggiuntivi nell'account Cosmos DB.You can now import additional data to your Cosmos DB account.