Azure Cosmos DB: Sviluppare con l'API Graph in .NETAzure Cosmos DB: Develop with the Graph API in .NET

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 creare ed eseguire rapidamente query su database di documenti, coppie chiave-valore e grafi, sfruttando in ognuno dei casi i vantaggi offerti dalle funzionalità di scalabilità orizzontale e distribuzione globale alla base di Azure Cosmos DB.You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Questa esercitazione illustra come creare un account Azure Cosmos DB usando il portale di Azure e come creare un contenitore e un database di grafi.This tutorial demonstrates how to create an Azure Cosmos DB account using the Azure portal and how to create a graph database and container. L'applicazione crea quindi una social network semplice con quattro utenti usando l'API Graph (anteprima), quindi attraversa ed esegue query sul grafo usando Gremlin.The application then creates a simple social network with four people using the Graph API (preview), then traverses and queries the graph using Gremlin.

Questa esercitazione illustra le attività seguenti:This tutorial covers the following tasks:

  • Creare un account Azure Cosmos DBCreate an Azure Cosmos DB account
  • Creare un contenitore e un database di grafiCreate a graph database and container
  • Serializzare vertici e archi negli oggetti .NETSerialize vertices and edges to .NET objects
  • Aggiungere vertici e archiAdd vertices and edges
  • Eseguire query sul grafo usando GremlinQuery the graph using Gremlin

Grafi in Azure Cosmos DBGraphs in Azure Cosmos DB

È possibile usare Azure Cosmos DB per creare, aggiornare ed eseguire query di grafi usando la libreria Microsoft.Azure.Graphs.You can use Azure Cosmos DB to create, update, and query graphs using the Microsoft.Azure.Graphs library. La libreria Microsoft.Azure.Graph offre un metodo di estensione singolo CreateGremlinQuery<T> oltre alla classe DocumentClient per eseguire query Gremlin.The Microsoft.Azure.Graph library provides a single extension method CreateGremlinQuery<T> on top of the DocumentClient class to execute Gremlin queries.

Il linguaggio di programmazione funzionale Gremlin supporta operazioni di scrittura (DML) e le operazioni di query e attraversamento.Gremlin is a functional programming language that supports write operations (DML) and query and traversal operations. Questo articolo descrive alcuni esempi per iniziare a usare Gremlin.We cover a few examples in this article to get your started with Gremlin. Vedere Query di Gremlin per una procedura dettagliata delle funzionalità Gremlin disponibili in Azure Cosmos DB.See Gremlin queries for a detailed walkthrough of Gremlin capabilities available in Azure Cosmos DB.

PrerequisitiPrerequisites

Assicurarsi di disporre di quanto segue:Please make sure you have the following:

Creare un account di databaseCreate database account

Si inizia creando un account Azure Cosmos DB nel portale di Azure.Let's start by creating an Azure Cosmos DB account in the Azure portal.

Suggerimento

  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 cinque API per soddisfare le esigenze dell'applicazione, ovvero SQL (database di documenti) Gremlin (grafo), MongoDB, SQL (database di documenti), Tabella di Azure e Cassandra, per ognuna delle quali è attualmente necessario un account separato.Azure Cosmos DB provides five APIs to suits the needs of your application: SQL (document database), Gremlin (graph database), MongoDB (document database), Azure Table, and Cassandra, 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 la creazione dell'account il portale visualizza il riquadro Deploying Azure Cosmos DB (Distribuzione di Azure Cosmos DB) a destra, quindi potrebbe essere necessario scorrere a destra del dashboard per visualizzare il riquadro.During account creation the portal displays the Deploying Azure Cosmos DB tile on the right side, you may need to scroll right on your dashboard to see the tile. È presente anche un indicatore di stato nella parte superiore della schermata.There is also a progress bar displayed near the top of the screen. È possibile esaminare lo stato di avanzamento nelle due aree.You can watch either area for progress.

    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.

Configurare la soluzione di Visual StudioSet up your Visual Studio solution

  1. Aprire Visual Studio nel computer.Open Visual Studio on your computer.
  2. Scegliere Nuovo dal menu File e quindi selezionare Progetto.On the File menu, select New, and then choose Project.
  3. Nella finestra di dialogo Nuovo progetto selezionare Modelli / Visual C# / App console (.NET Framework), assegnare un nome al progetto e quindi fare clic su OK.In the New Project dialog, select Templates / Visual C# / Console App (.NET Framework), name your project, and then click OK.
  4. In Esplora soluzioni fare clic con il pulsante destro del mouse sulla nuova applicazione console, disponibile nella soluzione di Visual Studio, quindi scegliere Gestisci pacchetti NuGet.In the Solution Explorer, right click on your new console application, which is under your Visual Studio solution, and then click Manage NuGet Packages...
  5. Nella scheda NuGet fare clic su Sfogliae digitare Microsoft.Azure.Graphs nella casella di ricerca e selezionare Includi versione preliminare.In the NuGet tab, click Browse, and type Microsoft.Azure.Graphs in the search box, and check the Include prerelease versions.
  6. Nei risultati trovare Microsoft.Azure.Graphs e fare clic su Installa.Within the results, find Microsoft.Azure.Graphs and click Install.

    Se viene visualizzato un messaggio sulla verifica delle modifiche alla soluzione, fare clic su OK.If you get a message about reviewing changes to the solution, click OK. Se viene visualizzato un messaggio sull'accettazione della licenza, fare clic su Accetto.If you get a message about license acceptance, click I accept.

    La libreriaMicrosoft.Azure.Graphs fornisce un metodo di estensione singolo CreateGremlinQuery<T> per l'esecuzione di operazioni Gremlin.The Microsoft.Azure.Graphs library provides a single extension method CreateGremlinQuery<T> for executing Gremlin operations. Il linguaggio di programmazione funzionale Gremlin supporta operazioni di scrittura (DML) e le operazioni di query e attraversamento.Gremlin is a functional programming language that supports write operations (DML) and query and traversal operations. Questo articolo descrive alcuni esempi per iniziare a usare Gremlin.We cover a few examples in this article to get your started with Gremlin. Query Gremlin include una procedura dettagliata delle funzionalità di Gremlin in Azure Cosmos DB.Gremlin queries has a detailed walkthrough of Gremlin capabilities in Azure Cosmos DB.

Connessione dell'appConnect your app

Aggiungere queste due costanti e la variabile client nell'applicazione.Add these two constants and your client variable in your application.

string endpoint = ConfigurationManager.AppSettings["Endpoint"]; 
string authKey = ConfigurationManager.AppSettings["AuthKey"]; 

Tornare al portale di Azure per recuperare la chiave primaria e l'URL dell'endpoint.Next, head back to the Azure portal to retrieve your endpoint URL and primary key. L'URL e la chiave primaria dell'endpoint sono necessari all'applicazione per conoscere la destinazione della connessione e ad Azure Cosmos DB per considerare attendibile la connessione dell'applicazione.The endpoint URL and primary key are necessary for your application to understand where to connect to, and for Azure Cosmos DB to trust your application's connection.

Nel portale di Azure passare all'account Azure Cosmos DB, fare clic su Chiavi, quindi su Chiavi di lettura/scrittura.In the Azure portal, navigate to your Azure Cosmos DB account, click Keys, and then click Read-write Keys.

Copiare l'URI dal portale e incollarlo su Endpoint nella proprietà dell'endpoint.Copy the URI from the portal and paste it over Endpoint in the endpoint property above. Copiare quindi la CHIAVE PRIMARIA dal portale e incollarla nella proprietà AuthKey precedente.Then copy the PRIMARY KEY from the portal and paste it into the AuthKey property above.

Screenshot del portale di Azure usato nell'esercitazione per creare un'applicazione C#.

Creare un'istanza di DocumentClientInstantiate the DocumentClient

Creare quindi una nuova istanza di DocumentClient.Next, create a new instance of the DocumentClient.

DocumentClient client = new DocumentClient(new Uri(endpoint), authKey); 

Creare un databaseCreate a database

A questo punto creare un database di Azure Cosmos DB usando il metodo CreateDatabaseAsync o CreateDatabaseIfNotExistsAsync della classe DocumentClient da DocumentDB .NET SDK.Now, create an Azure Cosmos DB database by using the CreateDatabaseAsync method or CreateDatabaseIfNotExistsAsync method of the DocumentClient class from the DocumentDB .NET SDK.

Database database = await client.CreateDatabaseIfNotExistsAsync(new Database { Id = "graphdb" }); 

Creare un grafoCreate a graph

Creare quindi un contenitore di grafi usando il metodo CreateDocumentCollectionAsync o CreateDocumentCollectionIfNotExistsAsync della classe DocumentClient.Next, create a graph container by using the using the CreateDocumentCollectionAsync method or CreateDocumentCollectionIfNotExistsAsync method of the DocumentClient class. Una raccolta è un contenitore di entità di grafi.A collection is a container of graph entities.

DocumentCollection graph = await client.CreateDocumentCollectionIfNotExistsAsync( 
    UriFactory.CreateDatabaseUri("graphdb"), 
    new DocumentCollection { Id = "graphcollz" }, 
    new RequestOptions { OfferThroughput = 1000 }); 

Serializzare vertici e archi negli oggetti .NETSerialize vertices and edges to .NET objects

Azure Cosmos DB usa il formato wire GraphSON, che definisce uno schema JSON per vertici, archi e proprietà.Azure Cosmos DB uses the GraphSON wire format, which defines a JSON schema for vertices, edges, and properties. Azure Cosmos DB .NET SDK include JSON.NET come dipendenza e ciò consente di serializzare o deserializzare GraphSON negli oggetti .NET che è possibile usare nel codice.The Azure Cosmos DB .NET SDK includes JSON.NET as a dependency, and this allows us to serialize/deserialize GraphSON into .NET objects that we can work with in code.

Ad esempio, è possibile usare una social network semplice con quattro utenti.As an example, let's work with a simple social network with four people. Verrà illustrato come creare vertici Person, aggiungere relazioni Knows tra i vertici, quindi eseguire query e attraversare il grafo per individuare le relazioni "amico di amico".We look at how to create Person vertices, add Knows relationships between them, then query and traverse the graph to find "friend of friend" relationships.

Lo spazio dei nomi Microsoft.Azure.Graphs.Elements fornisce le classi Vertex, Edge, Property e VertexProperty per la deserializzazione delle risposte GraphSON a oggetti .NET ben definiti.The Microsoft.Azure.Graphs.Elements namespace provides Vertex, Edge, Property and VertexProperty classes for deserializing GraphSON responses to well-defined .NET objects.

Eseguire Gremlin usando CreateGremlinQueryRun Gremlin using CreateGremlinQuery

Gremlin, come SQL, supporta le operazioni di lettura, scrittura e le query.Gremlin, like SQL, supports read, write, and query operations. Ad esempio, il frammento seguente illustra come creare vertici e archi, eseguire alcune query di esempio usando CreateGremlinQuery<T> e iterare in modo asincrono questi risultati usando ExecuteNextAsync e 'HasMoreResults.For example, the following snippet shows how to create vertices, edges, perform some sample queries using CreateGremlinQuery<T>, and asynchronously iterate through these results using ExecuteNextAsync and `HasMoreResults.

Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
{
    { "Cleanup",        "g.V().drop()" },
    { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44)" },
    { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39)" },
    { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller')" },
    { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield')" },
    { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
    { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
    { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
    { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
    { "CountVertices",  "g.V().count()" },
    { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
    { "Project",        "g.V().hasLabel('person').values('firstName')" },
    { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
    { "Traverse",       "g.V('thomas').outE('knows').inV().hasLabel('person')" },
    { "Traverse 2x",    "g.V('thomas').outE('knows').inV().hasLabel('person').outE('knows').inV().hasLabel('person')" },
    { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
    { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
    { "CountEdges",     "g.E().count()" },
    { "DropVertex",     "g.V('thomas').drop()" },
};

foreach (KeyValuePair<string, string> gremlinQuery in gremlinQueries)
{
    Console.WriteLine($"Running {gremlinQuery.Key}: {gremlinQuery.Value}");

    // The CreateGremlinQuery method extensions allow you to execute Gremlin queries and iterate
    // results asychronously
    IDocumentQuery<dynamic> query = client.CreateGremlinQuery<dynamic>(graph, gremlinQuery.Value);
    while (query.HasMoreResults)
    {
        foreach (dynamic result in await query.ExecuteNextAsync())
        {
            Console.WriteLine($"\t {JsonConvert.SerializeObject(result)}");
        }
    }

    Console.WriteLine();
}

Aggiungere vertici e archiAdd vertices and edges

Verranno esaminati in maggiore dettaglio i comandi Gremlin illustrati nella sezione precedente.Let's look at the Gremlin statements shown in the preceding section more detail. Prima si aggiungono vertici usando il metodo addV Gremlin.First we some vertices using Gremlin's addV method. Ad esempio, il frammento seguente crea un vertice "Thomas Andersen" di tipo "Person", con proprietà per il nome, il cognome e l'età.For example, the following snippet creates a "Thomas Andersen" vertex of type "Person", with properties for first name, last name, and age.

// Create a vertex
IDocumentQuery<Vertex> createVertexQuery = client.CreateGremlinQuery<Vertex>(
    graphCollection, 
    "g.addV('person').property('firstName', 'Thomas')");

while (createVertexQuery.HasMoreResults)
{
    Vertex thomas = (await create.ExecuteNextAsync<Vertex>()).First();
}

Creare quindi alcuni archi tra i vertici usando il metodo addE Gremlin.Then we create some edges between these vertices using Gremlin's addE method.

// Add a "knows" edge
IDocumentQuery<Edge> createEdgeQuery = client.CreateGremlinQuery<Edge>(
    graphCollection, 
    "g.V('thomas').addE('knows').to(g.V('mary'))");

while (create.HasMoreResults)
{
    Edge thomasKnowsMaryEdge = (await create.ExecuteNextAsync<Edge>()).First();
}

È possibile aggiornare un vertice esistente usando il comando properties Gremlin.We can update an existing vertex by using properties step in Gremlin. Non verrà esaminata la chiamata per eseguire la query tramite HasMoreResults e ExecuteNextAsync negli altri esempi.We skip the call to execute the query via HasMoreResults and ExecuteNextAsync for the rest of the examples.

// Update a vertex
client.CreateGremlinQuery<Vertex>(
    graphCollection, 
    "g.V('thomas').property('age', 45)");

È possibile trascinare gli archi e i vertici usando il comando drop Gremlin.You can drop edges and vertices using Gremlin's drop step. Ecco un frammento di codice che illustra come eliminare un vertice e un arco.Here's a snippet that shows how to delete a vertex and an edge. Si noti che l'eliminazione di un vertice implica l'eliminazione a catena degli archi associati.Note that dropping a vertex performs a cascading delete of the associated edges.

// Drop an edge
client.CreateGremlinQuery(graphCollection, "g.E('thomasKnowsRobin').drop()");

// Drop a vertex
client.CreateGremlinQuery(graphCollection, "g.V('robin').drop()");

Eseguire una query sul grafoQuery the graph

È possibile anche eseguire operazioni di query e attraversamento usando Gremlin.You can perform queries and traversals also using Gremlin. Ad esempio, il frammento seguente illustra come contare il numero di vertici nel grafo:For example, the following snippet shows how to count the number of vertices in the graph:

// Run a query to count vertices
IDocumentQuery<int> countQuery = client.CreateGremlinQuery<int>(graphCollection, "g.V().count()");

È possibile eseguire filtri usando i comandi has e hasLabel Gremlin e combinarli usando and, or e not per creare filtri più complessi:You can perform filters using Gremlin's has and hasLabel steps, and combine them using and, or, and not to build more complex filters:

// Run a query with filter
IDocumentQuery<Vertex> personsByAge = client.CreateGremlinQuery<Vertex>(
  graphCollection, 
  "g.V().hasLabel('person').has('age', gt(40))");

È possibile proiettare determinate proprietà nei risultati della query usando il comando values:You can project certain properties in the query results using the values step:

// Run a query with projection
IDocumentQuery<string> firstNames = client.CreateGremlinQuery<string>(
  graphCollection, 
  $"g.V().hasLabel('person').values('firstName')");

Finora sono stati esaminati solo gli operatori di query che è possibile usare in qualsiasi database.So far, we've only seen query operators that work in any database. I grafi sono veloci ed efficienti per le operazioni di attraversamento quando è necessario passare agli archi e ai vertici correlati.Graphs are fast and efficient for traversal operations when you need to navigate to related edges and vertices. Verranno ora individuati tutti gli amici di Thomas.Let's find all friends of Thomas. Questa operazione viene eseguita usando il comando outE di Gremlin per individuare tutti gli archi in uscita da Thomas, quindi attraversando i vertici in ingresso da tali archi usando il comando inV di Gremlin:We do this by using Gremlin's outE step to find all the out-edges from Thomas, then traversing to the in-vertices from those edges using Gremlin's inV step:

// Run a traversal (find friends of Thomas)
IDocumentQuery<Vertex> friendsOfThomas = client.CreateGremlinQuery<Vertex>(
  graphCollection,
  "g.V('thomas').outE('knows').inV().hasLabel('person')");

La query successiva esegue due passaggi per trovare tutti "gli amici di amici" di Thomas chiamando outE e inV due volte.The next query performs two hops to find all of Thomas' "friends of friends", by calling outE and inV two times.

// Run a traversal (find friends of friends of Thomas)
IDocumentQuery<Vertex> friendsOfFriendsOfThomas = client.CreateGremlinQuery<Vertex>(
  graphCollection,
  "g.V('thomas').outE('knows').inV().hasLabel('person').outE('knows').inV().hasLabel('person')");

È possibile creare query più complesse e implementare la potente logica di attraversamento di grafi usando Gremlin, incluse la combinazione di espressioni di filtro, l'esecuzione di cicli con il comando loop e l'implementazione dello spostamento condizionale usando il comando choose.You can build more complex queries and implement powerful graph traversal logic using Gremlin, including mixing filter expressions, performing looping using the loop step, and implementing conditional navigation using the choose step. Altre informazioni sulle operazioni che è possibile eseguire con il supporto per Gremlin.Learn more about what you can do with Gremlin support!

L'esercitazione di Azure Cosmos DB è stata completata.That's it, this Azure Cosmos DB tutorial is complete!

Pulire le risorseClean up resources

Se non si prevede di continuare a usare questa app, seguire questa procedura per eliminare tutte le risorse create da questa esercitazione nel portale di Azure.If you're not going to continue to use this app, use the following steps to delete all resources created by this tutorial in the Azure portal.

  1. Scegliere Gruppi di risorse dal menu a sinistra del portale di Azure e quindi fare clic sul nome della risorsa creata.From the left-hand menu in the Azure portal, click Resource groups and then click the name of the resource you created.
  2. Nella pagina del gruppo di risorse fare clic su Elimina, digitare il nome della risorsa da eliminare nella casella di testo e quindi fare clic su Elimina.On your resource group page, click Delete, type the name of the resource to delete in the text box, and then click Delete.

Passaggi successiviNext steps

In questa esercitazione sono state eseguite le operazioni seguenti:In this tutorial, you've done the following:

  • Creazione di un account Azure Cosmos DBCreated an Azure Cosmos DB account
  • Creazione di un contenitore e un database di grafiCreated a graph database and container
  • Serializzazione di vertici e archi negli oggetti .NETSerialized vertices and edges to .NET objects
  • Aggiunta di vertici e archiAdded vertices and edges
  • Esecuzione di query sul grafo usando GremlinQueried the graph using Gremlin

È ora possibile creare query più complesse e implementare la potente logica di attraversamento di grafi usando Gremlin.You can now build more complex queries and implement powerful graph traversal logic using Gremlin.