Avvio rapido: Libreria client di Azure Cosmos DB for Apache Gremlin per Python

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 Python 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 Python, connettersi all'account, eseguire operazioni comuni ed eseguire query sui dati di esempio finali.

Codice sorgente della libreria | Pacchetto (PyPi)

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.

Python 3.12 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	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 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.
Importare il gremlinpython pacchetto da Python Package Index (PyPI).
```
pip install gremlinpython
```
Creare il file app.py.

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 app.py nell'ambiente di sviluppo integrato (IDE).
Importare i tipi seguenti dalla gremlin_python.driver libreria:
- gremlin_python.driver.client
- gremlin_python.driver.serializer
```
from gremlin_python.driver import client, serializer
```
Creare variabili stringa per le credenziali raccolte in precedenza in questa guida. Nomina le variabili hostname e primary_key.
```
hostname = "<host>"
primary_key = "<key>"
```

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

client = client.Client(
    url=f"wss://{hostname}.gremlin.cosmos.azure.com:443/",
    traversal_source="g",
    username="/dbs/cosmicworks/colls/products",
    password=f"{primary_key}",
    message_serializer=serializer.GraphSONSerializersV2d0()
)

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.
```
client.submit("g.V().drop()").all().result()
```

Creare una query Gremlin che aggiunge un vertice.

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.

client.submit(
    message=insert_vertex_query,
    bindings={
        "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,
    },
).all().result()

Aggiungere altri due vertici per due prodotti aggiuntivi.

client.submit(
    message=insert_vertex_query,
    bindings={
        "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,
    },
).all().result()

client.submit(
    message=insert_vertex_query,
    bindings={
        "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,
    },
).all().result()

Creare un'altra query Gremlin che aggiunge un arco.

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.

client.submit(
    message=insert_edge_query,
    bindings={
        "prop_partition_key": "gear-surf-surfboards",
        "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "prop_target_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    },
).all().result()

client.submit(
    message=insert_edge_query,
    bindings={
        "prop_partition_key": "gear-surf-surfboards",
        "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "prop_target_id": "cccccccc-2222-3333-4444-dddddddddddd",
    },
).all().result()

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.
```
read_vertex_query = "g.V([prop_partition_key, prop_id])"
```

Leggere quindi un vertice specificando i parametri obbligatori.

matched_item = client.submit(
    message=read_vertex_query,
    bindings={
        "prop_partition_key": "gear-surf-surfboards",
        "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    }
).one()

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.

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.

find_results = client.submit(
    message=find_vertices_query,
    bindings={
        "prop_partition_key": "gear-surf-surfboards",
        "prop_name": "Montau Turtle Surfboard",
    },
).all().result()

Scorrere i risultati della query.

for result in find_results:
    # Do something here with each result

Eseguire il codice

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

python app.py

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