Avvio rapido: Libreria client di Azure Cosmos DB for Apache Gremlin per Node.js

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.

Inizia a utilizzare la libreria client di Azure Cosmos DB per Apache Gremlin per Node.js per archiviare, gestire e interrogare i dati non strutturati. Seguire la procedura descritta in questa guida per creare un nuovo account, installare una libreria client Node.js, connettersi all'account, eseguire operazioni comuni ed eseguire query sui dati di esempio finali.

Codice sorgente della libreria | Pacchetto (npm)

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.

Node.js 22 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"

Crea un nuovo database con nome 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	Attività di apprendimento
Abbonamento	Selezionare la sottoscrizione di Azure
Gruppo di risorse	Creare un nuovo gruppo di risorse o selezionare un gruppo di risorse 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 impostata sui 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 impostata sui 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 recuperare l'host dell'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. Il valore di questa proprietà è l'host che utilizzerai più avanti in questa guida per connetterti all'account tramite 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.
Inizializzare un nuovo modulo.
```
npm init es6 --yes
```
Installare il gremlin pacchetto da Node Package Manager (npm).
```
npm install --save gremlin
```
Creare il file index.js .

Iniziare in una cartella vuota.
Inizializzare un nuovo modulo.
```
npm init es6 --yes
```
Installare il typescript pacchetto da Node Package Manager (npm).
```
npm install --save-dev typescript
```
Installare il tsx pacchetto da npm.
```
npm install --save-dev tsx
```
Installare il gremlin pacchetto da npm.
```
npm install --save gremlin
```
Installare il @types/node pacchetto da npm.
```
npm install --save-dev @types/node
```
Installare il @types/gremlin pacchetto da npm.
```
npm install --save-dev @types/gremlin
```

Inizializzare il progetto TypeScript usando il compilatore (tsc).

npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext

Creare il file index.ts .

Modello a oggetti

	Descrizione
`DriverRemoteConnection`	Rappresenta la connessione al 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 index.js nell'ambiente di sviluppo integrato (IDE).

Importare il gremlin pacchetto e i tipi richiesti:

import gremlin from 'gremlin';
const { Client, auth } = gremlin.driver;
const { PlainTextSaslAuthenticator } = auth;

Creare variabili stringa per le credenziali raccolte in precedenza in questa guida. Nomina le variabili hostname e primaryKey.
```
const hostname = '<host>';
const primaryKey = '<key>';
```
Creare un oggetto di tipo PlainTextSaslAuthenticator usando le credenziali e le variabili di configurazione create nei passaggi precedenti. Archiviare l'oggetto in una variabile denominata authenticator.
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

Creare un Client oggetto usando la variabile authenticator. Assegnare alla variabile il nome client.

const client = new Client(
    `wss://${hostname}.gremlin.cosmos.azure.com:443/`,
    {
        authenticator,
        traversalsource: 'g',
        rejectUnauthorized: true,
        mimeType: 'application/vnd.gremlin-v2.0+json'
    }
);

Aprire il file index.ts nell'ambiente di sviluppo integrato (IDE).

Importare il gremlin pacchetto e i tipi richiesti:

import gremlin from 'gremlin';
const { Client, auth } = gremlin.driver;
const { PlainTextSaslAuthenticator } = auth;

Creare variabili stringa per le credenziali raccolte in precedenza in questa guida. Nomina le variabili hostname e primaryKey.
```
const hostname: string = '<host>';
const primaryKey: string = '<key>';
```
Creare un oggetto di tipo PlainTextSaslAuthenticator usando le credenziali e le variabili di configurazione create nei passaggi precedenti. Archiviare l'oggetto in una variabile denominata authenticator.
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

Creare un Client oggetto usando la variabile authenticator. Assegnare alla variabile il nome client.

const client = new Client(
    `wss://${hostname}.gremlin.cosmos.azure.com:443/`,
    {
        authenticator,
        traversalsource: 'g',
        rejectUnauthorized: true,
        mimeType: 'application/vnd.gremlin-v2.0+json'
    }
);

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.submit('g.V().drop()');
```

Creare una query Gremlin che aggiunge un vertice.

const insert_vertex_query = `
    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.submit(insert_vertex_query, {
    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.submit(insert_vertex_query, {
    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.submit(insert_vertex_query, {
    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.

const insert_edge_query = `
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
`;

Aggiungere due bordi.

await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'cccccccc-2222-3333-4444-dddddddddddd',
});

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

Creare una query Gremlin che aggiunge un vertice.

const insert_vertex_query: string = `
    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.submit(insert_vertex_query, {
    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.submit(insert_vertex_query, {
    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.submit(insert_vertex_query, {
    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.

const insert_edge_query: string = `
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
`;

Aggiungere due bordi.

await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

await client.submit(insert_edge_query, {
    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 che legge un vertice usando l'identificatore univoco e il valore della chiave di partizione.
```
const read_vertex_query = 'g.V([prop_partition_key, prop_id])';
```

Leggere quindi un vertice specificando i parametri obbligatori.

let read_results = await client.submit(read_vertex_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

let matched_item = read_results._items[0];

Creare una query che legge un vertice usando l'identificatore univoco e il valore della chiave di partizione.
```
const read_vertex_query: string = 'g.V([prop_partition_key, prop_id])';
```

Leggere quindi un vertice specificando i parametri obbligatori.

let read_results = await client.submit(read_vertex_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

let matched_item = read_results._items[0];

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 individui tutti i vertici che si diramano da un vertice specifico.

const find_vertices_query = `
    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.

let find_results = await client.submit(find_vertices_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_name: 'Montau Turtle Surfboard',
});

Scorrere i risultati della query.

for (const item of find_results._items) {
    // Do something here with each result
}

Creare una query che individui tutti i vertici che si diramano da un vertice specifico.

const find_vertices_query: string = `
    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.

let find_results = await client.submit(find_vertices_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_name: 'Montau Turtle Surfboard',
});

Scorrere i risultati della query.

for (const item of find_results._items) {
    // Do something here with each result
}

Eseguire il codice

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

node index.js

npx tsx index.ts

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