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

Articolo
06/13/2024

SI APPLICA A: Gremlin

Azure Cosmos DB per Apache Gremlin è un servizio di database a grafo completamente gestito che implementa il diffuso Apache Tinkerpop, un framework di calcolo a grafo usando il linguaggio di query Gremlin. L'API per Gremlin offre un modo agevole per iniziare a usare Gremlin con un servizio che può crescere e aumentare in base alle esigenze di gestione minima.

In questo avvio rapido, viene usata la libreria gremlinpython per connettersi a un account Azure Cosmos DB per Gremlin appena creato.

Codice sorgente della libreria | Pacchetto (PyPi)

Prerequisiti

Un account Azure con una sottoscrizione attiva.
- Se non si ha una sottoscrizione di Azure. Sottoscrivere un account Azure gratuito.
- Se non si vuole una sottoscrizione di Azure. È possibile provare gratuitamente Azure Cosmos DB senza la necessità di alcuna sottoscrizione.
Python (ultima versione)
- Python non è installato? Provare questo avvio rapido in GitHub Codespaces.
Interfaccia della riga di comando di Azure

Azure Cloud Shell

Azure Cloud Shell è un ambiente di shell interattivo ospitato in Azure e usato tramite il browser. È possibile usare Bash o PowerShell con Cloud Shell per usare i servizi di Azure. È possibile usare i comandi preinstallati di Cloud Shell per eseguire il codice contenuto in questo articolo senza dover installare strumenti nell'ambiente locale.

Per avviare Azure Cloud Shell:

Opzione	Esempio/Collegamento
Selezionare Prova nell'angolo superiore destro di un blocco di codice o di comando. Quando si seleziona Prova, il codice o il comando non viene copiato automaticamente in Cloud Shell.
Passare a https://shell.azure.com o selezionare il pulsante Avvia Cloud Shell per aprire Cloud Shell nel browser.
Selezionare il pulsante Cloud Shell nella barra dei menu nell'angolo in alto a destra del portale di Azure.

Per usare Azure Cloud Shell:

Avviare Cloud Shell.
Selezionare il pulsante Copia in un blocco di codice (o in un blocco di comando) per copiare il codice o il comando.
Incollare il codice o il comando nella sessione di Cloud Shell selezionando CTRL+MAIUSC+V in Windows e Linux o selezionando CMD+MAIUSC+V in macOS.
Selezionare INVIO per eseguire il codice o il comando.

Configurazione

Questa sezione illustra come creare un’API per l’account Gremlin e configurare un progetto Python per usare la libreria per connettersi all'account.

Creare un'API per l'account Gremlin

L'API per l'account Gremlin deve essere creata prima di usare la libreria Python. Inoltre, è utile disporre anche del database e del grafo.

Creare variabili della shell per accountName, resourceGroupName e location.

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
location="westus"

# Variable for account name with a randomly generated suffix

let suffix=$RANDOM*$RANDOM
accountName="msdocs-gremlin-$suffix"

Se non è già stato fatto, accedere all'interfaccia della riga di comando di Azure usando az login.
Usare az group create per creare un nuovo gruppo di risorse nella propria sottoscrizione.
```
az group create \
    --name $resourceGroupName \
    --location $location
```
Usare az cosmosdb create per creare una nuova API per l'account Gremlin con le impostazioni predefinite.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
Nota

È possibile avere fino a un account Azure Cosmos DB del livello gratuito per ogni sottoscrizione di Azure ed è necessario acconsentire esplicitamente durante la creazione dell'account. Se questo comando non riesce ad applicare lo sconto per il livello gratuito, significa che un altro account nella sottoscrizione è già stato abilitato per il livello gratuito.

Ottenere l’API per il NOME dell’endpoint Gremlin dell’account usando az cosmosdb show.

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

Trovare la CHIAVE dall'elenco di chiavi per l'account con az-cosmosdb-keys-list.

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

Registrare i valori NOME e CHIAVE. Queste credenziali saranno necessarie più avanti.

Creare un database denominato cosmicworks usando az cosmosdb gremlin database create.

az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

Creare un grafo usando az cosmosdb gremlin graph create. Assegnare al grafo il nome products, quindi impostare la velocità effettiva su 400 e infine impostare il percorso della chiave di partizione su /category.

az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400

Creare una nuova applicazione console Python

Creare una nuova console Python in una cartella vuota usando il terminale preferito.

Aprire il terminale in una cartella vuota.
Creare il file app.py.
```
touch app.py
```

Installare il pacchetto PyPI

Aggiungere il pacchetto PyPI gremlinpython al progetto Python.

Salvare il file requirements.txt.
```
touch requirements.txt
```
Aggiungere il pacchetto gremlinpython dall'indice dei pacchetti Python al file dei requisiti.
```
gremlinpython==3.7.0
```
Installare tutti i requisiti per il progetto.
```
python install -r requirements.txt
```

Configurare le variabili di ambiente

Per usare i valori NOME e URI ottenuti in precedenza in questo avvio rapido, mantenerli in nuove variabili di ambiente nel computer locale che esegue l'applicazione.

Per impostare la variabile di ambiente, usare il terminale per mantenere i valori rispettivamente come COSMOS_ENDPOINT e COSMOS_KEY.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```
Verificare che le variabili di ambiente siano state impostate correttamente.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

Il codice di questo articolo si connette a un database denominato cosmicworks e a un grafo denominato products. Il codice aggiunge quindi vertici e contorni al grafico prima di attraversare gli elementi aggiunti.

Autenticare il client

Le richieste dell'applicazione per la maggior parte dei servizi di Azure devono essere autorizzate. Per l'API per Gremlin, usare i valori NOME e URI ottenuti in precedenza in questo avvio rapido.

Aprire il file app.py.

Importare client e serializer dal modulo gremlin_python.driver.

import os
from gremlin_python.driver import client, serializer

Avviso

A seconda della versione di Python, potrebbe essere necessario anche importare asyncio e sostituire i criteri del ciclo di eventi:

import asyncio
import sys

if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

Creare le variabili ACCOUNT_NAME e ACCOUNT_KEY. Archiviare le variabili di ambiente COSMOS_GREMLIN_ENDPOINT e COSMOS_GREMLIN_KEY come valori per ogni variabile corrispondente.
```
ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]
```

Usare Client per connettersi usando le credenziali dell'account e il serializzatore GraphSON 2.0.

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

Creare vertici

Ora che l'applicazione è connessa all'account, usare la sintassi Gremlin standard per creare vertici.

Usare submit per eseguire un comando lato server nell'API per l'account Gremlin. Creare un vertice prodotto con le proprietà seguenti:

	Valore
label	`product`
id	`68719518371`
`name`	`Kiama classic surfboard`
`price`	`285.55`
`category`	`surfboards`

client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518371",
        "prop_name": "Kiama classic surfboard",
        "prop_price": 285.55,
        "prop_partition_key": "surfboards",
    },
)

Creare un secondo vertice prodotto con queste proprietà:

	Valore
label	`product`
id	`68719518403`
`name`	`Montau Turtle Surfboard`
`price`	`600.00`
`category`	`surfboards`

client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518403",
        "prop_name": "Montau Turtle Surfboard",
        "prop_price": 600.00,
        "prop_partition_key": "surfboards",
    },
)

Creare un terzo vertice prodotto con queste proprietà:

	Valore
label	`product`
id	`68719518409`
`name`	`Bondi Twin Surfboard`
`price`	`585.50`
`category`	`surfboards`

client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518409",
        "prop_name": "Bondi Twin Surfboard",
        "prop_price": 585.50,
        "prop_partition_key": "surfboards",
    },
)

Creare contorni

Creare contorni usando la sintassi Gremlin per definire relazioni tra i vertici.

Creare un contorno dal prodotto Montau Turtle Surfboard denominato sostituisce al Kiama classic surfboard prodotto.

client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_source_id": "68719518403",
        "prop_target_id": "68719518371",
    },
)

Suggerimento

Questa definizione dei contorni usa la sintassi g.V(['<partition-key>', '<id>']). In alternativa, è possibile usare g.V('<id>').has('category', '<partition-key>').

Creare un altro contorno sostituisce dallo stesso prodotto all'oggetto Bondi Twin Surfboard.

client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_source_id": "68719518403",
        "prop_target_id": "68719518409",
    },
)

Eseguire query su vertici e contorni

Usare la sintassi Gremlin per attraversare il grafo e individuare le relazioni tra vertici.

Attraversare il grafo e trovare tutti i vertici che Montau Turtle Surfboard sostituisce.

result = client.submit(
    message=(
        "g.V().hasLabel('product')"
        ".has('category', prop_partition_key)"
        ".has('name', prop_name)"
        ".outE('replaces').inV()"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_name": "Montau Turtle Surfboard",
    },
)

Scrivere nella console il risultato di questo attraversamento.
```
print(result)
```

Eseguire il codice

Verificare che l'applicazione funzioni come previsto eseguendo l'applicazione. L'applicazione deve essere eseguita senza errori o avvisi. L'output dell'applicazione include i dati sugli elementi creati e sottoposti a query.

Aprire il terminale nella cartella del progetto Python.
Usare python <filename> per eseguire l'applicazione. Osservare l'output dell'applicazione.
```
python app.py
```

Pulire le risorse

Quando l'API per l'account Gremlin non è più necessaria, eliminare il gruppo di risorse corrispondente.

Creare una variabile shell per resourceGroupName, se non esiste già.

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"

Usare az group delete per eliminare il gruppo di risorse.
```
az group delete \
    --name $resourceGroupName
```

Passaggio successivo

Creare ed eseguire query sui dati usando Azure Cosmos DB for Apache Gremlin

Condividi tramite