Rychlé zahájení: Klientská knihovna Azure Cosmos DB pro Apache Gremlin v rámci Node.js

• 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 Node.js 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 Node.js klientskou knihovnu, 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 (npm)

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.

• Node.js 22 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. Inicializace nového modulu

   npm init es6 --yes
   

3. gremlin Nainstalujte balíček z Node Package Manageru (npm).

   npm install --save gremlin
   

4. Vytvořte soubor index.js .

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

2. Inicializace nového modulu

   npm init es6 --yes
   

3. typescript Nainstalujte balíček z Node Package Manageru (npm).

   npm install --save-dev typescript
   

4. tsx Nainstalujte balíček z npm.

   npm install --save-dev tsx
   

5. gremlin Nainstalujte balíček z npm.

   npm install --save gremlin
   

6. @types/node Nainstalujte balíček z npm.

   npm install --save-dev @types/node
   

7. @types/gremlin Nainstalujte balíček z npm.

   npm install --save-dev @types/gremlin
   

8. Inicializace projektu TypeScript pomocí kompilátoru (tsc).

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

9. Vytvořte soubor index.ts .

Objektový model

	Popis
DriverRemoteConnection	Představuje připojení k serveru 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 index.js v integrovaném vývojovém prostředí (IDE).

2. Importujte gremlin balíček a požadované typy:

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

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

   const hostname = '<host>';
   const primaryKey = '<key>';
   

4. Vytvořte objekt typu PlainTextSaslAuthenticator pomocí přihlašovacích údajů a konfiguračních proměnných vytvořených v předchozích krocích. Uložte objekt do proměnné s názvem authenticator.

   const authenticator = new PlainTextSaslAuthenticator(
       '/dbs/cosmicworks/colls/products',
       primaryKey
   );
   

5. Vytvořte Client objekt pomocí proměnné authenticatoru. Pojmenujte proměnnou client.

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

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

2. Importujte gremlin balíček a požadované typy:

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

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

   const hostname: string = '<host>';
   const primaryKey: string = '<key>';
   

4. Vytvořte objekt typu PlainTextSaslAuthenticator pomocí přihlašovacích údajů a konfiguračních proměnných vytvořených v předchozích krocích. Uložte objekt do proměnné s názvem authenticator.

   const authenticator = new PlainTextSaslAuthenticator(
       '/dbs/cosmicworks/colls/products',
       primaryKey
   );
   

5. Vytvořte Client objekt pomocí proměnné authenticatoru. Pojmenujte proměnnou client.

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

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

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

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

3. Přidejte vrchol pro jeden produkt.

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

4. Přidejte dva další vrcholy pro dva nové produkty.

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

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

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

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

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

   await client.submit('g.V().drop()');
   

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

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

3. Přidejte vrchol pro jeden produkt.

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

4. Přidejte dva další vrcholy pro dva nové produkty.

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

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

   const insert_edge_query: string = `
       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.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',
   });
   

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

   const read_vertex_query = 'g.V([prop_partition_key, prop_id])';
   

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

   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];
   

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

   const read_vertex_query: string = 'g.V([prop_partition_key, prop_id])';
   

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

   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];
   

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.

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

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

3. Iterujte výsledky dotazu.

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

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

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

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

3. Iterujte výsledky dotazu.

   for (const item of find_results._items) {
       // 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.

node index.js

npx tsx index.ts

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