Поделиться через

Краткое руководство: клиентская библиотека Azure Cosmos DB для Apache Gremlin для Node.js

  • Применяется к: ✅ Apache Gremlin

Чтобы начать работать с клиентской библиотекой Apache Gremlin для Azure Cosmos DB и Node.js, вы сможете эффективно хранить, управлять и запрашивать неструктурированные данные. Выполните действия, описанные в этом руководстве, чтобы создать новую учетную запись, установить клиентскую библиотеку Node.js, подключиться к учетной записи, выполнить типичные операции и запросить результаты выборки данных.

Пакет исходного кода | библиотеки (npm)

Необходимые компоненты

  • Последняя версия Azure CLI в Azure Cloud Shell.

    • Если вы предпочитаете локально запускать справочные команды CLI, войдите в Azure CLI с помощью az login команды.
  • Node.js 22 или более поздней версии

Установка

Сначала настройте учетную запись и среду разработки для этого руководства. В этом разделе описан процесс создания учетной записи, получения учетных данных и подготовки среды разработки.

Создать аккаунт

Сначала создайте API для учетной записи Apache Gremlin. После создания учетной записи создайте ресурсы базы данных и графа.

  1. Если у вас еще нет целевой группы ресурсов, используйте az group create команду для создания новой группы ресурсов в подписке.

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

  2. az cosmosdb create Используйте команду, чтобы создать новую учетную запись Azure Cosmos DB для Apache Gremlin с параметрами по умолчанию.

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

  3. Создайте новую базу данных с именем 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 Используйте команду для создания нового графа с именемproducts.

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

Получение учетных данных

Теперь получите пароль для клиентской библиотеки для создания подключения к недавно созданной учетной записи.

  1. Используйте az cosmosdb show для получения хоста для учетной записи.

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

  2. Запишите значение host свойства из выходных данных предыдущих команд. Значение этого свойства — это хост, который вы используете далее в этом руководстве для подключения к учетной записи и библиотеке.

  3. Используйте az cosmosdb keys list для получения ключей для учетной записи.

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

  4. Запишите значение primaryMasterKey свойства из выходных данных предыдущих команд. Это значение свойства — это ключ , который вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.

Подготовка среды разработки

Затем настройте среду разработки с новым проектом и клиентской библиотекой. Этот шаг является последним обязательным предварительным условием, прежде чем перейти к остальной части этого руководства.

  1. Запустите пустую папку.

  2. Инициализация нового модуля.

    npm init es6 --yes

  3. Установите пакет gremlin с помощью менеджера пакетов Node (npm).

    npm install --save gremlin

  4. Создайте файл index.js .

  1. Запустите пустую папку.

  2. Инициализация нового модуля.

    npm init es6 --yes

  3. Установите пакет typescript с помощью менеджера пакетов Node (npm).

    npm install --save-dev typescript

  4. Установите пакет tsx из npm.

    npm install --save-dev tsx

  5. Установите пакет gremlin из npm.

    npm install --save gremlin

  6. Установите пакет @types/node из npm.

    npm install --save-dev @types/node

  7. Установите пакет @types/gremlin из npm.

    npm install --save-dev @types/gremlin

  8. Инициализация проекта TypeScript с помощью компилятора (tsc).

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

  9. Создайте файл index.ts .

Объектная модель

Описание
DriverRemoteConnection Представляет подключение к серверу Gremlin
GraphTraversalSource Используется для создания и выполнения обходов Gremlin

Примеры кода

Проверка подлинности клиента

Начните с проверки подлинности клиента с помощью учетных данных, собранных ранее в этом руководстве.

  1. Откройте файлindex.js в интегрированной среде разработки (IDE).

  2. Импортируйте пакет gremlin и необходимые типы:

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

  3. Создайте строковые переменные для учетных данных, собранных ранее в этом руководстве. Назовите переменные hostname и primaryKey.

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

  4. Создайте объект типа PlainTextSaslAuthenticator с помощью учетных данных и переменных конфигурации, созданных на предыдущих шагах. Сохраните объект в переменной с именем authenticator.

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

  5. Client Создайте объект с помощью переменной authenticator. Присвойте переменной 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. Откройте файл index.ts в интегрированной среде разработки (IDE).

  2. Импортируйте пакет gremlin и необходимые типы:

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

  3. Создайте строковые переменные для учетных данных, собранных ранее в этом руководстве. Назовите переменные hostname и primaryKey.

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

  4. Создайте объект типа PlainTextSaslAuthenticator с помощью учетных данных и переменных конфигурации, созданных на предыдущих шагах. Сохраните объект в переменной с именем authenticator.

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

  5. Client Создайте объект с помощью переменной authenticator. Присвойте переменной 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. g.V().drop() Выполните запрос, чтобы очистить все вершины и края из графа.

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

  2. Создайте запрос Gremlin, который добавляет вершину.

    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. Добавьте вершину для одного продукта.

    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. Добавьте еще две вершины для дополнительных двух продуктов.

    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. Создайте ещё один запрос Gremlin, который добавляет ребро.

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

  6. Добавьте два края.

    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. g.V().drop() Выполните запрос, чтобы очистить все вершины и края из графа.

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

  2. Создайте запрос Gremlin, который добавляет вершину.

    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. Добавьте вершину для одного продукта.

    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. Добавьте еще две вершины для дополнительных двух продуктов.

    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. Создайте ещё один запрос Gremlin, который добавляет ребро.

    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. Добавьте два края.

    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. Создайте запрос, который считывает вершину с помощью уникального идентификатора и значения ключа раздела.

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

  2. Затем считывайте вершину, указав необходимые параметры.

    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. Создайте запрос, который считывает вершину с помощью уникального идентификатора и значения ключа раздела.

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

  2. Затем считывайте вершину, указав необходимые параметры.

    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. Создайте запрос, который находит все вершины, исходящие из определенной вершины.

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

  2. Выполните запрос, указывающий Montau Turtle Surfboard продукт.

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

  3. Итерируйте результаты запроса.

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

  1. Создайте запрос, который находит все вершины, исходящие из определенной вершины.

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

  2. Выполните запрос, указывающий Montau Turtle Surfboard продукт.

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

  3. Итерируйте результаты запроса.

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

Выполнение кода

Запустите созданное приложение с помощью терминала в каталоге приложения.

node index.js

npx tsx index.ts

Очистка ресурсов

Если учетная запись больше не нужна, удалите учетную запись из подписки Azure, удалив ресурс.

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