Guida introduttiva: Libreria client di Azure Cosmos DB per Apache Gremlin per .NET

Si applica a: ✅ Apache Gremlin

Importante

Si sta cercando una soluzione di database per scenari su larga scala con un contratto di servizio di disponibilità 99.999%, scalabilità automatica immediata e failover automatico in più aree? Prendere in considerazione Azure Cosmos DB per NoSQL.

Si vuole implementare un grafico OLAP (Online Analytical Processing) o eseguire la migrazione di un'applicazione Apache Gremlin esistente? Considera Graph in Microsoft Fabric.

Introduzione alla libreria client di Azure Cosmos DB per Apache Gremlin per .NET per archiviare, gestire ed eseguire query sui dati non strutturati. Seguire la procedura descritta in questa guida per creare un nuovo account, installare una libreria client .NET, connettersi all'account, eseguire operazioni comuni ed eseguire query sui dati di esempio finali.

Codice sorgente della libreria | Pacchetto (NuGet)

Prerequisiti

Una sottoscrizione di Azure
- Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Versione più recente dell'interfaccia della riga di comando di Azure in Azure Cloud Shell.
- Se si preferisce eseguire i comandi CLI di riferimento in locale, accedere all'interfaccia della riga di comando di Azure usando il comando az login.

.NET SDK 9.0 o versione successiva

Configurazione

Prima di tutto, configurare l'account e l'ambiente di sviluppo per questa guida. Questa sezione illustra il processo di creazione di un account, il recupero delle credenziali e la preparazione dell'ambiente di sviluppo.

Crea un account

Per iniziare, creare un'API per l'account Apache Gremlin. Dopo aver creato l'account, creare il database e le risorse del grafo.

Interfaccia della riga di comando di Azure
Portale di Azure

Se non si ha già un gruppo di risorse di destinazione, usare il az group create comando per creare un nuovo gruppo di risorse nella sottoscrizione.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Usare il az cosmosdb create comando per creare un nuovo account Azure Cosmos DB per Apache Gremlin con le impostazioni predefinite.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableGremlin"

Creare un nuovo database chiamato az cosmosdb gremlin database create utilizzando cosmicworks.

az cosmosdb gremlin database create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Usare il az cosmosdb gremlin graph create comando per creare un nuovo grafo denominato products.

az cosmosdb gremlin graph create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category"

Accedere al portale di Azure (https://portal.azure.com).
Immettere Azure Cosmos DB nella barra di ricerca globale.
In Servizi selezionare Azure Cosmos DB.
Nel riquadro Azure Cosmos DB selezionare Crea e quindi Azure Cosmos DB per Apache Gremlin nella scheda Altri .

Nel riquadro Dati principali configurare le opzioni seguenti, quindi selezionare Rivedi e crea:

	valore
Tipo di carico di lavoro	Apprendimento
Abbonamento	Selezionare la sottoscrizione di Azure
Gruppo di risorse	Creare un nuovo gruppo di risorse o selezionarne uno esistente
Account Name:	Specificare un nome univoco globale
Zone di disponibilità	Disabilitare
Ubicazione	Selezionare un'area di Azure supportata per la sottoscrizione

Suggerimento

È possibile lasciare qualsiasi opzione non specificata ai valori predefiniti. È anche possibile configurare l'account per limitare la velocità effettiva totale dell'account a 1.000 unità richiesta al secondo (UR/sec) o abilitare il livello gratuito per ridurre al minimo i costi.

Nel riquadro Rivedi e crea attendere il completamento della convalida dell'account e quindi selezionare Crea.
Il portale passa automaticamente al riquadro Distribuzione. Attendere il completamento della distribuzione.
Al termine della distribuzione, selezionare Vai alla risorsa per passare alla nuova API per l'account Apache Gremlin.
Nel menu delle risorse selezionare l'opzione Esplora dati .
In Esplora dati selezionare + Nuovo grafico.

Nella finestra di dialogo Aggiungi grafico configurare le opzioni seguenti e quindi selezionare OK:

	valore
Banca dati	Crea nuovo
Nome del database	`cosmicworks`
Nome grafico	`products`
Chiave di partizione	`/category`

Suggerimento

È possibile lasciare qualsiasi opzione non specificata ai valori predefiniti.

Ottenere le credenziali

Ottenere ora la password per la libreria client da usare per creare una connessione all'account creato di recente.

Interfaccia della riga di comando di Azure
Portale di Azure

Usare az cosmosdb show per ottenere l'host per l'account.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{host:name}"

Registrare il valore della host proprietà dall'output dei comandi precedenti. Questo valore della proprietà è l'host usato più avanti in questa guida per connettersi all'account con la libreria.

Usare az cosmosdb keys list per ottenere le chiavi per l'account.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Registrare il valore della primaryMasterKey proprietà dall'output dei comandi precedenti. Il valore di questa proprietà è la chiave usata più avanti in questa guida per connettersi all'account con la libreria.

Preparare l'ambiente di sviluppo

Configurare quindi l'ambiente di sviluppo con un nuovo progetto e la libreria client. Questo passaggio è l'ultimo prerequisito necessario prima di passare al resto di questa guida.

Iniziare in una cartella vuota.
Creare una nuova applicazione console .NET
```
dotnet new console
```
Importare il Gremlin.Net pacchetto da NuGet.
```
dotnet add package Gremlin.Net
```
Costruisci il progetto.
```
dotnet build
```

Modello a oggetti

	Descrizione
`GremlinClient`	Rappresenta il client utilizzato per connettersi e interagire con il server Gremlin
`GraphTraversalSource`	Usato per costruire ed eseguire attraversamenti Gremlin

Autenticare il client

Per iniziare, autenticare il client usando le credenziali raccolte in precedenza in questa guida.

Aprire il file Program.cs nell'ambiente di sviluppo integrato (IDE).
Eliminare qualsiasi contenuto esistente all'interno del file.
Aggiungere direttive using per gli spazi dei nomi seguenti:
- Gremlin.Net.Driver
- Gremlin.Net.Structure.IO.GraphSON
```
using Gremlin.Net.Driver;
using Gremlin.Net.Structure.IO.GraphSON;
```
Creare variabili stringa per le credenziali raccolte in precedenza in questa guida. Nomina le variabili hostname e primaryKey.
```
string hostname = "<host>";
string primaryKey = "<key>";
```

Creare un GremlinServer oggetto usando le credenziali e le variabili di configurazione create nei passaggi precedenti. Assegnare alla variabile il nome server.

GremlinServer server = new(
    $"{hostname}.gremlin.cosmos.azure.com",
    443,
    enableSsl: true,
    username: "/dbs/cosmicworks/colls/products",
    password: primaryKey
);

Ora, crea un GremlinClient utilizzando la variabile server e la configurazione GraphSON2MessageSerializer.
```
GremlinClient client = new(
    server,
    new GraphSON2MessageSerializer()
);
```

Immettere dati

Inserire quindi i nuovi dati dei vertici e dei bordi nel grafico. Prima di creare i nuovi dati, cancellare il grafico di tutti i dati esistenti.

Eseguire la g.V().drop() query per cancellare tutti i vertici e i bordi dal grafico.
```
await client.SubmitAsync("g.V().drop()");
```

Creare una query Gremlin che aggiunge un vertice.

string insertVertexQuery = """
    g.addV('product')
        .property('id', prop_id)
        .property('name', prop_name)
        .property('category', prop_category)
        .property('quantity', prop_quantity)
        .property('price', prop_price)
        .property('clearance', prop_clearance)
""";

Aggiungere un vertice per un singolo prodotto.

await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
{
    ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    ["prop_name"] = "Yamba Surfboard",
    ["prop_category"] = "gear-surf-surfboards",
    ["prop_quantity"] = 12,
    ["prop_price"] = 850.00,
    ["prop_clearance"] = false
});

Aggiungere altri due vertici per due prodotti aggiuntivi.

await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
{
    ["prop_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
    ["prop_name"] = "Montau Turtle Surfboard",
    ["prop_category"] = "gear-surf-surfboards",
    ["prop_quantity"] = 5,
    ["prop_price"] = 600.00,
    ["prop_clearance"] = true
});

await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
{
    ["prop_id"] = "cccccccc-2222-3333-4444-dddddddddddd",
    ["prop_name"] = "Noosa Surfboard",
    ["prop_category"] = "gear-surf-surfboards",
    ["prop_quantity"] = 31,
    ["prop_price"] = 1100.00,
    ["prop_clearance"] = false
});

Creare un'altra query Gremlin che aggiunge un arco.

string insertEdgeQuery = """
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
""";

Aggiungere due bordi.

await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
    ["prop_target_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
});

await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
    ["prop_target_id"] = "cccccccc-2222-3333-4444-dddddddddddd"
});

Leggere dati

Leggere quindi i dati inseriti in precedenza nel grafico.

Creare una query per leggere un vertice usando l'identificatore univoco e il valore della chiave di partizione.
```
string readVertexQuery = "g.V([prop_partition_key, prop_id])";
```

Leggere quindi un vertice specificando i parametri obbligatori.

ResultSet<Dictionary<string, object>> readResults = await client.SubmitAsync<Dictionary<string, object>>(readVertexQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
});

Dictionary<string, object> matchedItem = readResults.Single();

Dati di query

Usare infine una query per trovare tutti i dati corrispondenti a un attraversamento o un filtro specifico nel grafico.

Creare una query che trova tutti i vertici che escono da un vertice specifico.

string findVerticesQuery = """
    g.V().hasLabel('product')
        .has('category', prop_partition_key)
        .has('name', prop_name)
        .outE('replaces').inV()
""";

Eseguire la query che specifica il Montau Turtle Surfboard prodotto.

ResultSet<Dictionary<string, object>> findResults = await client.SubmitAsync<Dictionary<string, object>>(findVerticesQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_name"] = "Montau Turtle Surfboard"
});

Scorrere i risultati della query.

foreach (Dictionary<string, object> result in findResults)
{
    // Do something here with each result
}

Eseguire il codice

Eseguire l'applicazione appena creata usando un terminale nella directory dell'applicazione.

dotnet run

Pulire le risorse

Quando l'account non è più necessario, rimuovere l'account dalla sottoscrizione di Azure eliminando la risorsa.

Interfaccia della riga di comando di Azure
Portale di Azure

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-30