Rychlý start: Klientská knihovna Azure Cosmos DB pro Apache Gremlin pro Python

• Python
• Node.js
• C#

Důležité

Hledáte databázové řešení pro scénáře ve velkém měřítku s 99,999% smlouvou o úrovni služeb (SLA), okamžitým automatickým škálováním a automatickým převzetím služeb při selhání napříč několika oblastmi? Zvažte Azure Cosmos DB for NoSQL.

Chcete implementovat graf online analytického zpracování (OLAP) nebo migrovat existující aplikaci Apache Gremlin? Zvažte Graph v Microsoft Fabricu.

Začínáme s klientskou knihovnou Azure Cosmos DB for Apache Gremlin pro Python pro ukládání, správu a dotazování nestrukturovaných dat Postupujte podle kroků v tomto průvodci a vytvořte nový účet, nainstalujte klientskou knihovnu Pythonu, připojte se k účtu, proveďte běžné operace a dotazujte se na konečná ukázková data.

Balíček zdrojového kódu | knihovny (PyPi)

Požadavky

• Předplatné Azure

  • Pokud nemáte předplatné Azure, vytvořte si bezplatný účet před zahájením.

• Nejnovější verze Azure CLI v Azure Cloud Shellu

  • Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, přihlaste se k Azure CLI pomocí az login příkazu.

• Python 3.12 nebo novější

Nastavení

Nejprve pro tuto příručku nastavte účet a vývojové prostředí. Tato část vás provede procesem vytvoření účtu, získáním jeho přihlašovacích údajů a následnou přípravou vývojového prostředí.

Vytvoření účtu

Začněte vytvořením rozhraní API pro účet Apache Gremlin. Po vytvoření účtu vytvořte databázi a prostředky pro graf.

Azure CLI

1. Pokud ještě nemáte cílovou skupinu prostředků, použijte az group create příkaz k vytvoření nové skupiny prostředků ve vašem předplatném.

   az group create \
       --name "<resource-group-name>" \
       --location "<location>"
   

2. az cosmosdb create Pomocí příkazu vytvořte nový účet Azure Cosmos DB pro Apache Gremlin s výchozím nastavením.

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

3. Vytvořte novou databázi s názvem az cosmosdb gremlin database createcosmicworks.

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

4. az cosmosdb gremlin graph create Pomocí příkazu vytvořte nový graf s názvem products.

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

Azure Portal

1. Přihlaste se k webu Azure Portal (https://portal.azure.com).

2. Do globálního panelu hledání zadejte Azure Cosmos DB .

3. V rámci služeb vyberte Azure Cosmos DB.

4. V podokně Azure Cosmos DB vyberte Vytvořit a potom Azure Cosmos DB for Apache Gremlin v kartě Ostatní.

5. V podokně Základy nakonfigurujte následující možnosti a pak vyberte Zkontrolovat a vytvořit:

   	Hodnota
   Typ úlohy	Vzdělávání
   Předplatné	Výběr předplatného Azure
   Skupina prostředků	Vytvoření nové skupiny prostředků nebo výběr existující skupiny prostředků
   Název účtu	Zadejte globálně jedinečný název.
   Zóny dostupnosti	Zakázat
   Umístění	Vyberte podporovanou oblast Azure pro vaše předplatné.

   Tip

   U výchozích hodnot můžete ponechat všechny nezadané možnosti. Můžete také nakonfigurovat účet tak, aby omezil celkovou propustnost účtu na 1 000 jednotek žádostí za sekundu (RU/s), nebo povolit úroveň Free, aby se minimalizovaly náklady.

6. V podokně Zkontrolovat a vytvořit počkejte na úspěšné ověření účtu a pak vyberte Vytvořit.

7. Portál automaticky přejde do podokna Nasazení . Počkejte, až se nasazení dokončí.

8. Po dokončení nasazení vyberte Přejít k prostředku a přejděte k novému rozhraní API pro účet Apache Gremlin.

9. V nabídce prostředků vyberte možnost Průzkumník dat .

10. V Průzkumníku dat vyberte + Nový graf.

11. V dialogovém okně Přidat graf nakonfigurujte následující možnosti a pak vyberte OK:

    	Hodnota
    Databáze	Create new
    Název databáze	cosmicworks
    Název grafu	products
    Klíč oddílu	/category

    Tip

    U výchozích hodnot můžete ponechat všechny nezadané možnosti.

Získání přihlašovacích údajů

Teď získejte heslo pro klientskou knihovnu, které se má použít k vytvoření připojení k nedávno vytvořenému účtu.

Azure CLI

1. Slouží az cosmosdb show k získání hostitele pro účet.

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

2. Poznamenejte si hodnotu host vlastnosti z výstupu předchozích příkazů. Hodnota této vlastnosti je hostitel , který použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. Slouží az cosmosdb keys list k získání klíčů pro účet.

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

4. Poznamenejte si hodnotu primaryMasterKey vlastnosti z výstupu předchozích příkazů. Hodnota této vlastnosti je klíč , který použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Azure Portal

1. V nabídce prostředků pro účet vyberte možnost Přehled .

2. Poznamenejte si hodnotu názvu účtu. Hodnota této vlastnosti je hostitel , který použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. V nabídce prostředků pro účet znovu vyberte možnost Připojovací řetězce v části Nastavení .

4. Zveřejnit a zaznamenat hodnotu pole PRIMÁRNÍ KLÍČ na této stránce. Hodnota této vlastnosti je klíč , který použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Příprava vývojového prostředí

Potom nakonfigurujte vývojové prostředí s novým projektem a klientskou knihovnou. Tento krok je posledním požadovaným předpokladem před přechodem na zbytek této příručky.

1. Začněte v prázdné složce.

2. Importujte balíček z indexu gremlinpython balíčků Pythonu (PyPI).

   pip install gremlinpython
   

3. Vytvořte soubor app.py.

Objektový model

	Popis
GremlinClient	Představuje klienta sloužícího k připojení a interakci se serverem Gremlin.
GraphTraversalSource	Používá se ke konstrukci a provádění procházení Gremlin.

Příklady kódu

• Ověření klienta
• Vložte data
• Čtení dat
• Dotazování dat

Ověření klienta

Začněte ověřením klienta pomocí přihlašovacích údajů shromážděných dříve v této příručce.

1. Otevřete soubor app.py v integrovaném vývojovém prostředí (IDE).

2. Importujte z gremlin_python.driver knihovny následující typy:

   • gremlin_python.driver.client
   • gremlin_python.driver.serializer

   from gremlin_python.driver import client, serializer
   

3. Vytvořte řetězcové proměnné pro přihlašovací údaje shromážděné dříve v této příručce. Pojmenujte proměnné hostname a primary_key.

   hostname = "<host>"
   primary_key = "<key>"
   

4. Vytvořte Client objekt pomocí přihlašovacích údajů a konfiguračních proměnných vytvořených v předchozích krocích. Pojmenujte proměnnou 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()
   )
   

Vložení dat

V dalším kroku vložte do grafu nový vrchol a hraniční data. Před vytvořením nových dat vymažte graf všech existujících dat.

1. Spuštěním g.V().drop() dotazu vymažte všechny vrcholy a hrany z grafu.

   client.submit("g.V().drop()").all().result()
   

2. Vytvořte dotaz Gremlin, který přidá vrchol.

   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)"
   )
   

3. Přidejte vrchol pro jeden produkt.

   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()
   

4. Přidejte dva vrcholy pro dvě další produkty.

   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()
   

5. Vytvořte další dotaz Gremlin, který přidá hranu.

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

6. Přidejte dvě hrany.

   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()
   

Čtení dat

Potom načtěte data, která byla dříve vložena do grafu.

1. Vytvořte dotaz, který načte vrchol pomocí jedinečného identifikátoru a hodnoty klíče oddílu.

   read_vertex_query = "g.V([prop_partition_key, prop_id])"
   

2. Pak načtěte vrchol zadáním požadovaných parametrů.

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

Dotaz k datům

Nakonec pomocí dotazu najděte všechna data, která odpovídají určitému procházení nebo filtru v grafu.

1. Vytvořte dotaz, který najde všechny vrcholy, které směřují ven z konkrétního vrcholu.

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

2. Spusťte dotaz určující Montau Turtle Surfboard produkt.

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

3. Iterujte výsledky dotazu.

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

Spuštění kódu

Spusťte nově vytvořenou aplikaci pomocí terminálu v adresáři vaší aplikace.

python app.py

Vyčištění prostředků

Pokud účet už nepotřebujete, odeberte ho z předplatného Azure odstraněním prostředku.

Azure CLI

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

Azure Portal

1. Přejděte k existujícímu prostředku Azure Cosmos DB pro Apache Gremlin , který jste vytvořili dříve v této příručce.

2. Na stránce zdroje vyberte na panelu nástrojů Odstranit.

3. Postupujte podle pokynů v potvrzovacím dialogovém okně.