Azure Cosmos DB: Creare un database a grafo con Java e il portale di AzureAzure Cosmos DB: Create a graph database using Java and the Azure portal

Azure Cosmos DB è il servizio di database multimodello distribuito a livello globale di Microsoft.Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. Questo servizio consente di creare rapidamente database di documenti, tabelle e a grafo e di eseguire query su di essi.Using Azure Cosmos DB, you can quickly create and query managed document, table, and graph databases.

Questa guida introduttiva crea un database a grafo semplice usando gli strumenti del portale di Azure per Azure Cosmos DB.This quickstart creates a simple graph database using the Azure portal tools for Azure Cosmos DB. Illustra anche come creare rapidamente un'app console Java usando un database a grafo con il driver OSS Gremlin Java.This quickstart also shows you how to quickly create a Java console app using a graph database using the OSS Gremlin Java driver. Le istruzioni di questa guida introduttiva possono essere eseguite in qualsiasi sistema operativo in grado di eseguire Java.The instructions in this quickstart can be followed on any operating system that is capable of running Java. Questa guida consente di acquisire familiarità con la creazione e la modifica di grafi nell'interfaccia utente o a livello di codice, in base alle proprie preferenze.This quickstart familiarizes you with creating and modifying graphs in either the UI or programmatically, whichever is your preference.

PrerequisitiPrerequisites

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.

Eseguire anche queste operazioni:In addition:

  • Java Development Kit (JDK) 1.7+Java Development Kit (JDK) 1.7+
    • In Ubuntu eseguire apt-get install default-jdk per installare JDK.On Ubuntu, run apt-get install default-jdk to install the JDK.
    • Assicurarsi di impostare la variabile di ambiente JAVA_HOME in modo che faccia riferimento alla cartella di installazione di JDK.Be sure to set the JAVA_HOME environment variable to point to the folder where the JDK is installed.
  • Scaricare e installare un archivio binario MavenDownload and install a Maven binary archive
    • In Ubuntu è possibile eseguire apt-get install maven per installare Maven.On Ubuntu, you can run apt-get install maven to install Maven.
  • GitGit
    • In Ubuntu è possibile eseguire sudo apt-get install git per installare Git.On Ubuntu, you can run sudo apt-get install git to install Git.

Creare un account di databaseCreate a database account

Prima di potere creare un database a grafo, è necessario creare un account database Gremlin (grafo) con Azure Cosmos DB.Before you can create a graph database, you need to create a Gremlin (Graph) database account with Azure Cosmos DB.

  1. In una nuova finestra del browser accedere al portale di Azure.In a new browser window, sign in to the Azure portal.

  2. Fare clic su Nuovo > Database > Azure Cosmos DB.Click New > Databases > Azure Cosmos DB.

    Riquadro "Database" nel portale di Azure

  3. Nella pagina Nuovo account immettere le impostazioni per il nuovo account Azure Cosmos DB.In the New account page, enter the settings for the new Azure Cosmos DB account.

    ImpostazioneSetting Valore consigliatoSuggested value DescrizioneDescription
    IDID Immettere un nome univocoEnter a unique name Immettere un nome univoco per identificare l'account Azure Cosmos DB.Enter a unique name to identify this Azure Cosmos DB account. Poiché alI'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco ma facilmente identificabile.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique but identifiable ID.

    L'ID può contenere solo lettere minuscole, numeri e il segno meno (-) e deve avere una lunghezza compresa tra 3 e 50 caratteri.The ID can contain only lowercase letters, numbers, and the hyphen (-) character, and it must contain 3 to 50 characters.
    APIAPI Gremlin (graph)Gremlin (graph) L'API determina il tipo di account da creare.The API determines the type of account to create. Azure Cosmos DB offre quattro API per soddisfare le esigenze dell'applicazione, Gremlin (grafo), MongoDB, SQL (DocumentDB) e Tabella (chiave-valore), per ognuna delle quali è attualmente necessario un account separato.Azure Cosmos DB provides four APIs to suits the needs of your application: Gremlin (graph), MongoDB, SQL (DocumentDB), and Table (key-value), each which currently require a separate account.

    Selezionare Gremlin (grafo) perché in questa esercitazione si crea un grafo disponibile per query con sintassi Gremlin.Select Gremlin (graph) because in this quickstart you are creating a graph that is queryable using Gremlin syntax.

    Altre informazioni sull'API GraphLearn more about the Graph API
    SottoscrizioneSubscription Sottoscrizione in usoYour subscription Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos DB.Select Azure subscription that you want to use for this Azure Cosmos DB account.
    Gruppo di risorseResource group Immettere lo stesso nome univoco specificato sopra in IDEnter the same unique name as provided above in ID Immettere il nome di un nuovo gruppo di risorse per l'account.Enter a new resource-group name for your account. Per semplicità si può usare lo stesso nome usato come ID.For simplicity, you can use the same name as your ID.
    PercorsoLocation Selezionare l'area più vicina agli utentiSelect the region closest to your users Selezionare la posizione geografica in cui ospitare l'account Azure Cosmos DB.Select geographic location in which 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 the data.
    Abilita ridondanza geograficaEnable geo-redundancy Lasciare vuotoLeave blank Consente di creare una versione replicata del database in una seconda area abbinata.This creates a replicated version of your database in a second (paired) region. Lasciare vuoto.Leave this blank.
    Aggiungi al dashboardPin to dashboard SelezionareSelect Selezionare questa casella per aggiungere il nuovo account di database al dashboard del portale e accedervi più facilmente.Select this box so that your new database account is added to your portal dashboard for easy access.

    Fare quindi clic su Crea.Then click Create.

    Pannello Nuovo account per Azure Cosmos DB

  4. La creazione dell'account richiede alcuni minuti,The account creation takes a few minutes. durante i quali nel portale viene visualizzato il riquadro Distribuzione di Azure Cosmos DB.During account creation the portal displays the Deploying Azure Cosmos DB tile.

    Riquadro Notifiche del portale di Azure

    Al termine della creazione dell'account verrà visualizzata la pagina L'account Azure Cosmos DB è stato creato.Once the account is created, the Congratulations! Your Azure Cosmos DB account was created page is displayed.

Aggiungere un grafoAdd a graph

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

  1. Fare clic su Esplora dati > New Graph (Nuovo grafo).Click Data Explorer > New Graph.

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

    Pagina Esplora dati, Add Graph (Aggiungi grafico) nel portale di Azure

  2. Nella pagina Add Graph (Aggiungi grafo) immettere le impostazioni per il nuovo grafo.In the Add graph page, enter the settings for the new graph.

    ImpostazioneSetting Valore consigliatoSuggested value DescrizioneDescription
    ID databaseDatabase ID sample-databasesample-database Immettere sample-database come nome del nuovo database.Enter sample-database 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 be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    ID grafoGraph ID sample-graphsample-graph Immettere sample-graph come nome della nuova raccolta.Enter sample-graph as the name for your new collection. I nomi dei grafi presentano gli stessi requisiti relativi ai caratteri degli ID di database.Graph names have the same character requirements as database IDs.
    Capacità di archiviazioneStorage Capacity Fissa (10 GB)Fixed (10 GB) Impostare il valore su Fissa (10 GB).Change the value to Fixed (10 GB). Questo valore indica la capacità di archiviazione del database.This value is the storage capacity of the database.
    Velocità effettivaThroughput 400 UR/s400 RUs Modificare la velocità effettiva in 400 unità di 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.
    Chiave di partizionePartition key Lasciare vuotoLeave blank Per le finalità di questa esercitazione introduttiva, lasciare vuoto il valore relativo alla chiave di partizione.For the purpose of this quickstart, leave the partition key blank.
  3. Dopo aver compilato il modulo, fare clic su OK.Once the form is filled out, click OK.

Clonare l'applicazione di esempioClone the sample application

Si può ora passare a usare il codice.Now let's switch to working with code. È possibile clonare ora un'app API Graph da GitHub, impostare la stringa di connessione ed eseguirla.Let's clone a Graph API 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 una finestra del terminale Git, ad esempio git bash, ed eseguire il comando cd per passare a una 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 a folder to install the sample app.

    cd "C:\git-samples"
    
  2. 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-graph-java-getting-started.git
    

Esaminare il codiceReview the code

Questo passaggio è facoltativo.This step is optional. Per scoprire in che modo le risorse del database vengono create nel codice, è possibile esaminare i frammenti di codice seguenti.If you're interested in learning how the database resources are created in the code, you can review the following snippets. I frammenti di codice derivano tutti dal file Program.java che si trova nella cartella C:\git-samples\azure-cosmos-db-graph-java-getting-started\src\GetStarted.The snippets are all taken from the Program.java file in the C:\git-samples\azure-cosmos-db-graph-java-getting-started\src\GetStarted folder. In alternativa, è possibile passare ad Aggiornare la stringa di connessione.Otherwise, you can skip ahead to Update your connection string.

  • Viene inizializzato Client di Gremlin dalla configurazione in src/remote.yaml.The Gremlin Client is initialized from the configuration in src/remote.yaml.

    cluster = Cluster.build(new File("src/remote.yaml")).create();
    ...
    client = cluster.connect();
    
  • Viene eseguita una serie di passaggi di Gremlin tramite il metodo client.submit.A series of Gremlin steps are executed using the client.submit method.

    ResultSet results = client.submit(gremlin);
    
    CompletableFuture<List<Result>> completableFutureResults = results.all();
    List<Result> resultList = completableFutureResults.get();
    
    for (Result result : resultList) {
        System.out.println(result.toString());
    }
    

Aggiornare la stringa di connessioneUpdate your connection information

Tornare ora al portale di Azure per recuperare la stringa di connessione e copiarla nell'app.Now go back to the Azure portal to get your connection information and copy it into the app. Queste impostazioni consentono all'app di comunicare con il database ospitato.These settings enable your app to communicate with your hosted database.

  1. Nel portale di Azure fare clic su Chiavi.In the Azure portal, click Keys.

    Copiare la prima parte del valore dell'URI.Copy the first portion of the URI value.

    Visualizzare e copiare una chiave di accesso nella pagina Chiavi del portale di Azure

  2. Aprire il file src/remote.yaml e incollare il valore su $name$ in hosts: [$name$.graphs.azure.com].Open the src/remote.yaml file and paste the value over $name$ in hosts: [$name$.graphs.azure.com].

    La riga 1 del file remote.yaml si presenta ora nel modo seguente:Line 1 of remote.yaml should now look similar to

    hosts: [test-graph.graphs.azure.com]

  3. Nel portale di Azure usare il pulsante Copia per copiare la CHIAVE PRIMARIA e incollarla su $masterKey$ in password: $masterKey$.In the Azure portal, use the copy button to copy the PRIMARY KEY and paste it over $masterKey$ in password: $masterKey$.

    La riga 4 del file remote.yaml si presenta ora nel modo seguente:Line 4 of remote.yaml should now look similar to

    password: 2Ggkr662ifxz2Mg==

  4. Modificare la riga 3 di remote.yaml daChange line 3 of remote.yaml from

    username: /dbs/$database$/colls/$collection$

    into

    username: /dbs/sample-database/colls/sample-graph

  5. Salvare il file remote.yaml.Save the remote.yaml file.

Eseguire l'app consoleRun the console app

  1. Nella finestra del terminale git eseguire il comando cd per passare alla cartella azure-cosmos-db-graph-java-getting-started.In the git terminal window, cd to the azure-cosmos-db-graph-java-getting-started folder.

    cd "C:\git-samples\azure-cosmos-db-graph-java-getting-started"
    
  2. Nella finestra del terminale Git digitare mvn package per installare i pacchetti Java necessari.In the git terminal window, type mvn package to install the required Java packages.

  3. Nella finestra del terminale Git eseguire mvn exec:java -D exec.mainClass=GetStarted.Program per avviare l'applicazione Java.In the git terminal window, run mvn exec:java -D exec.mainClass=GetStarted.Program to start your Java application.

    La finestra del terminale mostra l'aggiunta dei vertici al grafo.The terminal window displays the vertices being added to the graph. Al termine del programma tornare al portale di Azure nel browser Internet.Once the program stops, switch back to the Azure portal in your internet browser.

Verificare e aggiungere dati di esempioReview and add sample data

È ora possibile tornare a Esplora dati e visualizzare i vertici aggiunti al grafo, quindi aggiungere altri punti dati.You can now go back to Data Explorer and see the vertices added to the graph, and add additional data points.

  1. Fare clic su Esplora dati, espandere sample-graph, fare clic su Grafo e quindi su Applica filtro.Click Data Explorer, expand sample-graph, click Graph, and then click Apply Filter.

    Creare nuovi documenti in Esplora dati nel portale di Azure

  2. Nell'elenco Risultati verificare i nuovi utenti aggiunti al grafo.In the Results list, notice the new users added to the graph. Selezionare ben. Come si può notare, è connesso a robin.Select ben and notice that he's connected to robin. È possibile spostare i vertici intorno mediante trascinamento della selezione, applicare lo zoom mediante lo scorrimento della rotellina del mouse ed espandere le dimensioni del grafo usando la doppia freccia.You can move the vertices around by dragging and dropping, zoom in and out by scrolling the wheel of your mouse, and expand the size of the graph with the double-arrow.

    Nuovi vertici nel grafo in Esplora dati nel portale di Azure

  3. Vengono ora aggiunti alcuni nuovi utenti.Let's add a few new users. Fare clic sul pulsante New Vertex (Nuovo vertice) per aggiungere dati al grafo.Click the New Vertex button to add data to your graph.

    Creare nuovi documenti in Esplora dati nel portale di Azure

  4. Immettere un'etichetta di persona.Enter a label of person.

  5. Fare clic su Add property (Aggiungi proprietà) per aggiungere ognuna delle proprietà seguenti.Click Add property to add each of the following properties. Si noti che è possibile creare proprietà univoche per ogni persona del grafo.Notice that you can create unique properties for each person in your graph. È necessaria solo la chiave id.Only the id key is required.

    keykey valuevalue NoteNotes
    idid ashleyashley Identificatore univoco per il vertice.The unique identifier for the vertex. Se non si specifica alcun ID, ne verrà generato automaticamente uno.If you don't specify an id, one is generated for you.
    gendergender femalefemale
    techtech javajava

    Nota

    In questa esercitazione introduttiva viene creata una raccolta non partizionata.In this quickstart we create a non-partitioned collection. Se tuttavia si crea una raccolta partizionata specificando una chiave di partizione durante la creazione della raccolta, sarà necessario includere la chiave di partizione come chiave in ogni nuovo vertice.However, if you create a partitioned collection by specifying a partition key during the collection creation, then you need to include the partition key as a key in each new vertex.

  6. Fare clic su OK.Click OK. Potrebbe essere necessario espandere la schermata per vedere il pulsante OK nella parte inferiore dello schermo.You may need to expand your screen to see OK on the bottom of the screen.

  7. Fare di nuovo clic su New Vertex (Nuovo vertice) e aggiungere un altro nuovo utente.Click New Vertex again and add an additional new user.

  8. Immettere un'etichetta di persona.Enter a label of person.

  9. Fare clic su Add property (Aggiungi proprietà) per aggiungere ognuna delle proprietà seguenti:Click Add property to add each of the following properties:

    keykey valuevalue NoteNotes
    idid rakeshrakesh Identificatore univoco per il vertice.The unique identifier for the vertex. Se non si specifica alcun ID, ne verrà generato automaticamente uno.If you don't specify an id, one is generated for you.
    gendergender malemale
    schoolschool MITMIT
  10. Fare clic su OK.Click OK.

  11. Fare clic su Applica filtro con il filtro g.V() predefinito per visualizzare tutti i valori del grafo.Click Apply Filter with the default g.V() filter to display all the values in the graph. Tutti gli utenti sono ora visualizzati nell'elenco Risultati.All of the users now show in the Results list.

    Quando si aggiungono altri dati, è possibile usare i filtri per limitare i risultati visualizzati.As you add more data, you can use filters to limit your results. Per impostazione predefinita, Esplora dati usa g.V() per recuperare tutti i vertici di un grafo.By default, Data Explorer uses g.V() to retrieve all vertices in a graph. È possibile modificarlo in un'altra query di grafo, ad esempio g.V().count(), per restituire un conteggio di tutti i vertici del grafo in formato JSON.You can change it to a different graph query, such as g.V().count(), to return a count of all the vertices in the graph in JSON format. Se è stato modificato il filtro, reimpostarlo su g.V() e fare clic su Applica filtro per visualizzare di nuovo tutti i risultati.If you changed the filter, change the filter back to g.V() and click Apply Filter to display all the results again.

  12. È ora possibile connettere rakesh e ashley.Now we can connect rakesh and ashley. Assicurarsi che il valore ashley sia selezionato nell'elenco Risultati, quindi fare clic sul pulsante di modifica accanto a Destinazioni in basso a destra.Ensure ashley in selected in the Results list, then click the edit button next to Targets on lower right side. Potrebbe essere necessario allargare la finestra per visualizzare l'area Proprietà.You may need to widen your window to see the Properties area.

    Cambiare la destinazione di un vertice in un grafo

  13. Nella casella Destinazione digitare rakesh e nella casella Edge label (Etichetta arco) digitare knows, quindi selezionare la casella di controllo.In the Target box type rakesh, and in the Edge label box type knows, and then click the check.

    Aggiungere una connessione tra ashley e rakesh in Esplora dati

  14. Selezionare ora rakesh dall'elenco Risultati. Come si può notare ashley e rakesh sono connessi.Now select rakesh from the results list and see that ashley and rakesh are connected.

    Due vertici connessi in Esplora dati

    È stata completata la parte della creazione di risorse di questa esercitazione. È possibile continuare a aggiungere vertici al grafo, modificare quelli esistenti o modificare le query.That completes the resource creation part of this tutorial.You can continue to add vertexes to your graph, modify the existing vertexes, or change the queries. Vengono ora esaminate le metriche di Azure Cosmos DB e quindi pulite le risorse.Now let's review the metrics Azure Cosmos DB provides, and then clean up the resources.

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. Selezionare Gruppi di risorse e fare clic su Elimina gruppo di risorse.Select Resource groups and then click Delete resource group.

    Metriche nel portale di Azure

  2. Digitare il nome del gruppo di risorse da eliminare e fare clic su Elimina.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 un grafo con Esplora dati e come eseguire un'app.In this quickstart, you've learned how to create an Azure Cosmos DB account, create a graph using the Data Explorer, and run an app. È ora possibile creare query più complesse e implementare la potente logica di attraversamento dei grafi usando Gremlin.You can now build more complex queries and implement powerful graph traversal logic using Gremlin.