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

• 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 .NET pro ukládání, správu a dotazování nestrukturovaných dat. Podle kroků v tomto průvodci vytvořte nový účet, nainstalujte klientskou knihovnu .NET, 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 (NuGet)

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.

• .NET SDK 9.0 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. Vytvoření nové konzolové aplikace .NET

   dotnet new console
   

3. Importujte Gremlin.Net balíček z NuGetu.

   dotnet add package Gremlin.Net
   

4. Zkompilujte projekt.

   dotnet build
   

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 Program.cs v integrovaném vývojovém prostředí (IDE).

2. Odstraňte veškerý existující obsah v souboru.

3. Přidejte direktivy using pro následující obory názvů:

   • Gremlin.Net.Driver
   • Gremlin.Net.Structure.IO.GraphSON

   using Gremlin.Net.Driver;
   using Gremlin.Net.Structure.IO.GraphSON;
   

4. 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 primaryKey.

   string hostname = "<host>";
   string primaryKey = "<key>";
   

5. Vytvořte GremlinServer pomocí přihlašovacích údajů a konfiguračních proměnných, které jste vytvořili v předchozích krocích. Pojmenujte proměnnou server.

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

6. Nyní vytvořte GremlinClient pomocí proměnné server a konfigurace GraphSON2MessageSerializer.

   GremlinClient client = new(
       server,
       new GraphSON2MessageSerializer()
   );
   

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.

   await client.SubmitAsync("g.V().drop()");
   

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

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

3. Přidejte vrchol pro jeden produkt.

   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
   });
   

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

   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
   });
   

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

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

6. Přidejte dvě hrany.

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

Č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.

   string readVertexQuery = "g.V([prop_partition_key, prop_id])";
   

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

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

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.

   string findVerticesQuery = """
       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.

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

3. Iterujte výsledky dotazu.

   foreach (Dictionary<string, object> result in findResults)
   {
       // 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.

dotnet run

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ě.