Hızlı Başlangıç: Node.jsiçin Apache Gremlin istemci kitaplığı için Azure Cosmos DB

Şunlara uygulanır: ✅ Apache Gremlin

Important

99,999% kullanılabilirlik hizmet düzeyi sözleşmesi (SLA), anında otomatik ölçeklendirme ve birden çok bölgede otomatik yük devretme ile yüksek ölçekli senaryolar için bir veritabanı çözümü mü arıyorsunuz? NoSQL için Azure Cosmos DB'yi göz önünde bulundurun.

Çevrimiçi analitik işleme (OLAP) grafı uygulamak mı yoksa mevcut bir Apache Gremlin uygulamasını geçirmek mi istiyorsunuz? Graph in Microsoft Fabric'ı göz önünde bulundurun.

Yapılandırılmamış verileri depolamak, yönetmek ve sorgulamak için Node.js için Apache Gremlin için Azure Cosmos DB istemci kitaplığını kullanmaya başlayın. Yeni bir hesap oluşturmak, Node.js istemci kitaplığı yüklemek, hesaba bağlanmak, yaygın işlemler gerçekleştirmek ve son örnek verilerinizi sorgulamak için bu kılavuzdaki adımları izleyin.

Kitaplık kaynak kodu | Paket (npm)

Prerequisites

Azure aboneliği
- Eğer bir Azure aboneliğiniz yoksa, başlamadan önce ücretsiz bir hesap oluşturun.

Azure Cloud Shell'de Azure CLI'nın en son sürümü.
- CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız, az login komutunu kullanarak Azure CLI oturum açın.

Node.js 22 veya üzeri

Kurulum

İlk olarak, bu kılavuz için hesap ve geliştirme ortamını ayarlayın. Bu bölümde hesap oluşturma, kimlik bilgilerini alma ve geliştirme ortamınızı hazırlama işlemi boyunca size yol gösterilir.

Hesap oluştur

Apache Gremlin hesabı için bir API oluşturarak başlayın. Hesap oluşturulduktan sonra veritabanı ve grafik kaynaklarını oluşturun.

Azure CLI
Azure portalı

Henüz bir hedef kaynak grubunuz yoksa, aboneliğinizde yeni bir kaynak grubu oluşturmak için komutunu kullanın az group create .
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Varsayılan ayarlarla Apache Gremlin hesabı için yeni bir Azure Cosmos DB oluşturmak için az cosmosdb create komutunu kullanın.

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

az cosmosdb gremlin database create kullanarak cosmicworks adlı yeni bir veritabanı oluşturun.

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

az cosmosdb gremlin graph create adlı productsyeni bir grafik oluşturmak için komutunu kullanın.

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ında (https://portal.azure.com) oturum açın.
Genel arama çubuğuna Azure Cosmos DB yazın.
Services içinde Azure Cosmos DB öğesini seçin.
Azure Cosmos DB bölmesinde Oluştur'u ve ardından Diğerleri sekmesinde Apache Gremlin için Azure Cosmos DB'yi seçin.

Temel Bilgiler bölmesinde aşağıdaki seçenekleri yapılandırın ve gözden geçir ve oluştur'u seçin:

	Value
İş Yükü Türü	Öğrenim
Abonelik	Azure aboneliğinizi seçin
Kaynak Grubu	Yeni kaynak grubu oluşturma veya var olan bir kaynak grubunu seçme
Firma Adı	Genel olarak benzersiz bir ad sağlayın
Erişilebilirlik Bölgeleri	Disable
Konum	Aboneliğiniz için desteklenen bir Azure bölgesi seçin

Tip

Belirtilmeyen seçenekleri varsayılan değerlerine bırakabilirsiniz. Ayrıca hesabı, toplam hesap aktarım hızını saniyede 1.000 istek birimiyle (RU/sn) sınırlandıracak şekilde yapılandırabilir veya maliyetlerinizi en aza indirmek için ücretsiz katmanı etkinleştirebilirsiniz.

Gözden Geçir ve oluştur bölmesinde hesabınızın doğrulamasının başarıyla tamamlanmasını bekleyin ve oluştur'u seçin.
Portal otomatik olarak Dağıtım bölmesine gider. Dağıtımın tamamlanmasını bekleyin.
Dağıtım tamamlandıktan sonra Kaynağa Git seçeneğini belirleyerek Apache Gremlin hesabı için yeni API'ye erişin.
Kaynak menüsünde Veri Gezgini seçeneğini belirleyin.
Veri Gezgini'nde + Yeni Grafik'i seçin.

Grafik Ekle iletişim kutusunda aşağıdaki seçenekleri yapılandırın ve tamam'ı seçin:

	Value
Veritabanı	Yeni oluştur
Veritabanı adı	`cosmicworks`
Grafik adı	`products`
Bölüm anahtarı	`/category`

Tip

Belirtilmeyen seçenekleri varsayılan değerlerine bırakabilirsiniz.

Kimlik bilgilerini alma

Şimdi, son oluşturulan hesaba bağlantı oluşturmak için kullanılacak istemci kitaplığının parolasını alın.

Azure CLI
Azure portalı

az cosmosdb show kullanarak hesabın ana bilgisayarını alın.

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

Önceki komutların çıkışından host özelliğinin değerini kaydedin. Bu özelliğin değeri, bu kılavuzun ilerleyen bölümlerinde kütüphaneye bağlantı kurmak için kullandığınız ana bilgisayardır.

az cosmosdb keys list, hesabın anahtarlarını almak için kullanın.

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

Önceki komutların çıkışından primaryMasterKey özelliğinin değerini kaydedin. Bu özelliğin değeri, bu kılavuzun ilerleyen bölümlerinde kitaplığa bağlanmak için kullandığınız anahtardır .

Geliştirme ortamını hazırlama

Ardından geliştirme ortamınızı yeni bir proje ve istemci kitaplığıyla yapılandırın. Bu adım, bu kılavuzun geri kalanına geçmeden önce gereken son önkoşuldur.

Boş bir klasörden başlayın.
Yeni bir modül başlatın.
```
npm init es6 --yes
```
Node Paket Yöneticisi'dan (npm) gremlin paketini yükleyin.
```
npm install --save gremlin
```
index.js dosyasını oluşturun.

Boş bir klasörden başlayın.
Yeni bir modül başlatın.
```
npm init es6 --yes
```
Node Paket Yöneticisi'dan (npm) typescript paketini yükleyin.
```
npm install --save-dev typescript
```
tsx Paketi npm'den yükleyin.
```
npm install --save-dev tsx
```
gremlin Paketi npm'den yükleyin.
```
npm install --save gremlin
```
@types/node Paketi npm'den yükleyin.
```
npm install --save-dev @types/node
```
@types/gremlin Paketi npm'den yükleyin.
```
npm install --save-dev @types/gremlin
```

Derleyiciyi ()tsc kullanarak TypeScript projesini başlatın.

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

index.ts dosyasını oluşturun.

Nesne modeli

	Description
`DriverRemoteConnection`	Gremlin sunucusuna bağlantıyı temsil eder
`GraphTraversalSource`	Gremlin geçişlerini oluşturmak ve yürütmek için kullanılır

İstemcinin kimliğini doğrulama

Bu kılavuzda daha önce toplanan kimlik bilgilerini kullanarak istemcinin kimliğini doğrulayarak başlayın.

tümleşik geliştirme ortamınızda (IDE) index.js dosyasını açın.

Gerekli türleri ve gremlin paketini içeri aktarın:

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

Bu kılavuzun önceki bölümlerinde toplanan kimlik bilgileri için dize değişkenleri oluşturun. Değişkenleri hostname ve primaryKey olarak adlandırın.
```
const hostname = '<host>';
const primaryKey = '<key>';
```
Önceki adımlarda oluşturulan kimlik bilgilerini ve yapılandırma değişkenlerini kullanarak türünde PlainTextSaslAuthenticator bir nesne oluşturun. nesnesini adlı authenticatorbir değişkende depolayın.
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

Kimlik doğrulayıcı değişkenini kullanarak bir Client nesne oluşturun. değişkenini clientolarak adlandırın.

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

tümleşik geliştirme ortamınızda (IDE) index.ts dosyasını açın.

Gerekli türleri ve gremlin paketini içeri aktarın:

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

Bu kılavuzun önceki bölümlerinde toplanan kimlik bilgileri için dize değişkenleri oluşturun. Değişkenleri hostname ve primaryKey olarak adlandırın.
```
const hostname: string = '<host>';
const primaryKey: string = '<key>';
```
Önceki adımlarda oluşturulan kimlik bilgilerini ve yapılandırma değişkenlerini kullanarak türünde PlainTextSaslAuthenticator bir nesne oluşturun. nesnesini adlı authenticatorbir değişkende depolayın.
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

Kimlik doğrulayıcı değişkenini kullanarak bir Client nesne oluşturun. değişkenini clientolarak adlandırın.

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

Veri ekleme

Ardından, grafiğe yeni köşe ve kenar verileri ekleyin. Yeni verileri oluşturmadan önce mevcut verilerin grafiğini temizleyin.

Graftan g.V().drop() tüm köşeleri ve kenarları temizlemek için sorguyu çalıştırın.
```
await client.submit('g.V().drop()');
```

Bir düğüm ekleyen bir Gremlin sorgusu oluşturun.

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

Tek bir ürün için bir düğüm noktası ekleyin.

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

İki ekstra ürün için iki köşe daha ekleyin.

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

Kenar ekleyen başka bir Gremlin sorgusu oluşturun.

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

İki kenar ekleyin.

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

Graftan g.V().drop() tüm köşeleri ve kenarları temizlemek için sorguyu çalıştırın.
```
await client.submit('g.V().drop()');
```

Bir düğüm ekleyen bir Gremlin sorgusu oluşturun.

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

Tek bir ürün için bir düğüm noktası ekleyin.

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

İki ekstra ürün için iki köşe daha ekleyin.

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

Kenar ekleyen başka bir Gremlin sorgusu oluşturun.

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

İki kenar ekleyin.

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

Veriyi oku

Ardından, daha önce grafiğe eklenmiş olan verileri okuyun.

Benzersiz tanımlayıcıyı ve bölüm anahtarı değerini kullanarak bir düğümü okuyan bir sorgu oluşturun.
```
const read_vertex_query = 'g.V([prop_partition_key, prop_id])';
```

Ardından, gerekli parametreleri sağlayarak bir düğüm noktası okuyun.

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

Benzersiz tanımlayıcıyı ve bölüm anahtarı değerini kullanarak bir düğümü okuyan bir sorgu oluşturun.
```
const read_vertex_query: string = 'g.V([prop_partition_key, prop_id])';
```

Ardından, gerekli parametreleri sağlayarak bir düğüm noktası okuyun.

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

Sorgu verileri

Son olarak, grafikteki belirli bir dolaşma veya filtreyle eşleşen tüm verileri bulmak için sorgu kullanın.

Belirli bir düğümden dışarıya doğru giden tüm düğümleri bulan bir sorgu oluşturun.

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

Montau Turtle Surfboard ürününü belirten sorguyu yürütün.

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

Sorgu sonuçları üzerinde yineleme yapın.

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