Szybki start: biblioteka klienta usługi Azure Cosmos DB dla języka Apache Gremlin dla Node.js

Dotyczy: ✅ Apache Gremlin

Ważne

Szukasz rozwiązania bazy danych dla scenariuszy o dużej skali z umową SLA gwarantującą poziom dostępności na poziomie 99,999%, natychmiastowym skalowaniem automatycznym i automatycznym przełączaniem awaryjnym między wieloma regionami? Rozważmy usługę Azure Cosmos DB dla noSQL.

Czy chcesz zaimplementować graf przetwarzania analitycznego online (OLAP) lub przeprowadzić migrację istniejącej aplikacji Apache Gremlin? Rozważ użycie programu Graph w usłudze Microsoft Fabric.

Rozpocznij pracę z biblioteką klienta usługi Azure Cosmos DB for Apache Gremlin, aby Node.js przechowywać, zarządzać i przeszukiwać dane nieustrukturyzowane. Wykonaj kroki opisane w tym przewodniku, aby utworzyć nowe konto, zainstalować bibliotekę klienta Node.js, nawiązać połączenie z kontem, wykonać typowe operacje i wykonać zapytanie o ostateczne przykładowe dane.

Pakiet kodu | źródłowego biblioteki (npm)

Wymagania wstępne

Subskrypcja platformy Azure
- Jeśli nie masz subskrypcji Azure, przed rozpoczęciem utwórz darmowe konto.

Najnowsza wersja interfejsu wiersza polecenia platformy Azure w usłudze Azure Cloud Shell.
- Jeśli wolisz uruchamiać polecenia referencyjne CLI lokalnie, zaloguj się do Azure CLI przy użyciu polecenia az login.

Node.js 22 lub nowsze

Konfigurowanie

Najpierw skonfiguruj konto i środowisko programistyczne dla tego przewodnika. W tej sekcji przedstawiono proces tworzenia konta, uzyskiwania poświadczeń, a następnie przygotowywania środowiska deweloperskiego.

Tworzenie konta

Zacznij od utworzenia interfejsu API dla konta apache Gremlin. Po utworzeniu konta utwórz bazę danych i zasoby grafu.

Interfejs wiersza polecenia platformy Azure
Portal Azure

Jeśli nie masz jeszcze docelowej grupy zasobów, użyj az group create polecenia , aby utworzyć nową grupę zasobów w ramach subskrypcji.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Użyj polecenia az cosmosdb create, aby utworzyć konto usługi Azure Cosmos DB dla Apache Gremlin z ustawieniami domyślnymi.

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

Utwórz nową bazę danych przy użyciu az cosmosdb gremlin database create nazwy cosmicworks.

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

Użyj polecenia , az cosmosdb gremlin graph create aby utworzyć nowy graf o nazwie products.

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

Zaloguj się do witryny Azure Portal (https://portal.azure.com).
Wprowadź wartość Azure Cosmos DB na pasku wyszukiwania globalnego.
W obszarze Usługi wybierz pozycję Azure Cosmos DB.
W okienku Azure Cosmos DB wybierz pozycję Utwórz, a następnie pozycję Azure Cosmos DB for Apache Gremlin na karcie Inne .

W okienku Podstawowe skonfiguruj następujące opcje, a następnie wybierz pozycję Przejrzyj i utwórz:

	Wartość
Typ obciążenia	Szkolenie
Subskrypcja	Wybierz subskrypcję platformy Azure
Grupa zasobów	Utwórz nową grupę zasobów lub wybierz istniejącą grupę zasobów
Nazwa konta	Podaj globalnie unikatową nazwę
Strefy dostępności	Wyłącz
Lokalizacja	Wybieranie obsługiwanego regionu platformy Azure dla subskrypcji

Napiwek

Możesz pozostawić wszystkie nieokreślone opcje do ich wartości domyślnych. Możesz również skonfigurować konto, aby ograniczyć łączną przepływność konta do 1000 jednostek żądań na sekundę (RU/s) lub włączyć warstwę Bezpłatna, aby zminimalizować koszty.

W okienku Przeglądanie i tworzenie poczekaj na pomyślne zakończenie walidacji konta, a następnie wybierz pozycję Utwórz.
Portal automatycznie przechodzi do okienka Wdrażanie. Poczekaj na zakończenie wdrożenia.
Po zakończeniu wdrażania wybierz pozycję Przejdź do zasobu, i przejdź do nowego API konta Apache Gremlin.
W menu zasobów wybierz opcję Eksplorator danych .
W Eksploratorze danych wybierz pozycję + Nowy wykres.

W oknie dialogowym Dodawanie grafu skonfiguruj następujące opcje, a następnie wybierz przycisk OK:

	Wartość
Baza danych	Utwórz nową
Nazwa bazy danych	`cosmicworks`
Nazwa grafu	`products`
klucz partycji	`/category`

Napiwek

Możesz pozostawić wszystkie nieokreślone opcje do ich wartości domyślnych.

Pobieranie poświadczeń

Teraz pobierz hasło biblioteki klienta do utworzenia połączenia z niedawno utworzonym kontem.

Interfejs wiersza polecenia platformy Azure
Portal Azure

Użyj az cosmosdb show , aby uzyskać hosta dla konta.

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

Zapisz wartość właściwości host z wyników wcześniejszych poleceń. Wartość tej właściwości to host, którego używasz w kolejnych częściach tego przewodnika, aby połączyć się z kontem w bibliotece.

Użyj az cosmosdb keys list, aby uzyskać klucze dla konta.

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

Zapisz wartość właściwości primaryMasterKey z wyników wcześniejszych poleceń. Wartość tej właściwości jest kluczem używanym w dalszej części tego przewodnika w celu nawiązania połączenia z kontem z biblioteką.

Przygotowywanie środowiska projektowego

Następnie skonfiguruj środowisko deweloperskie przy użyciu nowego projektu i biblioteki klienta. Ten krok jest ostatnim wymaganiem wstępnym przed przejściem do pozostałej części tego przewodnika.

Rozpocznij w pustym folderze.
Zainicjuj nowy moduł.
```
npm init es6 --yes
```
gremlin Zainstaluj pakiet z poziomu menedżera pakietów node (npm).
```
npm install --save gremlin
```
Utwórz plik index.js .

Rozpocznij w pustym folderze.
Zainicjuj nowy moduł.
```
npm init es6 --yes
```
typescript Zainstaluj pakiet z poziomu menedżera pakietów node (npm).
```
npm install --save-dev typescript
```
Zainstaluj pakiet tsx z npm.
```
npm install --save-dev tsx
```
Zainstaluj pakiet gremlin z npm.
```
npm install --save gremlin
```
Zainstaluj pakiet @types/node z npm.
```
npm install --save-dev @types/node
```
Zainstaluj pakiet @types/gremlin z npm.
```
npm install --save-dev @types/gremlin
```

Zainicjuj projekt TypeScript przy użyciu kompilatora (tsc).

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

Utwórz plik index.ts .

Model obiektów

	Opis
`DriverRemoteConnection`	Reprezentuje połączenie z serwerem Gremlin
`GraphTraversalSource`	Służy do konstruowania i wykonywania przemierzeń Gremlin

Uwierzytelnianie klienta

Zacznij od uwierzytelnienia klienta przy użyciu poświadczeń zebranych wcześniej w tym przewodniku.

Otwórz plik index.js w zintegrowanym środowisku projektowym (IDE).

Zaimportuj gremlin pakiet i wymagane typy:

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

Utwórz zmienne tekstowe dla poświadczeń zebranych wcześniej w tym przewodniku. Nazwij zmienne hostname i primaryKey.
```
const hostname = '<host>';
const primaryKey = '<key>';
```
Utwórz obiekt typu PlainTextSaslAuthenticator przy użyciu poświadczeń i zmiennych konfiguracji utworzonych w poprzednich krokach. Zapisz obiekt w zmiennej o nazwie authenticator.
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

Utwórz Client obiekt przy użyciu zmiennej authenticator. Nadaj zmiennej clientnazwę .

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

Otwórz plik index.ts w zintegrowanym środowisku projektowym (IDE).

Zaimportuj gremlin pakiet i wymagane typy:

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

Utwórz zmienne tekstowe dla poświadczeń zebranych wcześniej w tym przewodniku. Nazwij zmienne hostname i primaryKey.
```
const hostname: string = '<host>';
const primaryKey: string = '<key>';
```
Utwórz obiekt typu PlainTextSaslAuthenticator przy użyciu poświadczeń i zmiennych konfiguracji utworzonych w poprzednich krokach. Zapisz obiekt w zmiennej o nazwie authenticator.
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

Utwórz Client obiekt przy użyciu zmiennej authenticator. Nadaj zmiennej clientnazwę .

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

Wstawianie danych

Następnie wstaw nowe dane wierzchołka i krawędzi do grafu. Przed utworzeniem nowych danych wyczyść graf wszystkich istniejących danych.

Uruchom zapytanie, g.V().drop() aby wyczyścić wszystkie wierzchołki i krawędzie z grafu.
```
await client.submit('g.V().drop()');
```

Stwórz zapytanie Gremlin dodające wierzchołek.

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

Dodaj wierzchołek dla pojedynczego produktu.

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

Dodaj dwa kolejne wierzchołki dla dwóch dodatkowych produktów.

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

Utwórz kolejne zapytanie Języka Gremlin, które dodaje krawędź.

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

Dodaj dwie krawędzie.

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

Uruchom zapytanie, g.V().drop() aby wyczyścić wszystkie wierzchołki i krawędzie z grafu.
```
await client.submit('g.V().drop()');
```

Stwórz zapytanie Gremlin dodające wierzchołek.

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

Dodaj wierzchołek dla pojedynczego produktu.

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

Dodaj dwa kolejne wierzchołki dla dwóch dodatkowych produktów.

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

Utwórz kolejne zapytanie Języka Gremlin, które dodaje krawędź.

const insert_edge_query: string = `
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
`;

Dodaj dwie krawędzie.

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

Odczyt danych

Następnie odczytaj dane, które zostały wcześniej wstawione do grafu.

Utwórz zapytanie, które odczytuje wierzchołek przy użyciu unikatowego identyfikatora i wartości klucza partycji.
```
const read_vertex_query = 'g.V([prop_partition_key, prop_id])';
```

Następnie odczytaj wierzchołek, podając wymagane parametry.

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

Utwórz zapytanie, które odczytuje wierzchołek przy użyciu unikatowego identyfikatora i wartości klucza partycji.
```
const read_vertex_query: string = 'g.V([prop_partition_key, prop_id])';
```

Następnie odczytaj wierzchołek, podając wymagane parametry.

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

Wykonywanie zapytań o dane

Na koniec użyj zapytania, aby znaleźć wszystkie dane zgodne z określonym przechodzeniem lub filtrem na grafie.

Utwórz zapytanie, które znajduje wszystkie wierzchołki wychodzące z określonego wierzchołka.

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

Wykonaj zapytanie określające Montau Turtle Surfboard produkt.

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

Iterowanie wyników zapytania.

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

Utwórz zapytanie, które znajduje wszystkie wierzchołki wychodzące z określonego wierzchołka.

const find_vertices_query: string = `
    g.V().hasLabel('product')
        .has('category', prop_partition_key)
        .has('name', prop_name)
        .outE('replaces').inV()
`;

Wykonaj zapytanie określające Montau Turtle Surfboard produkt.

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

Iterowanie wyników zapytania.

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

Uruchamianie kodu

Uruchom nowo utworzoną aplikację przy użyciu terminalu w katalogu aplikacji.

node index.js

npx tsx index.ts

Czyszczenie zasobów

Jeśli konto nie jest już potrzebne, usuń konto z subskrypcji platformy Azure, usuwając zasób.

Interfejs wiersza polecenia platformy Azure
Portal Azure

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

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-10-30