通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：适用于 Node.js 的 Azure Cosmos DB for Apache Gremlin 客户端库

  • 适用于: ✅ Apache Gremlin

开始使用 Azure Cosmos DB for Apache Gremlin 客户端库以存储、管理和查询 Node.js 的非结构化数据。 按照本指南中的步骤创建新帐户、安装 Node.js 客户端库、连接到帐户、执行常见作以及查询最终示例数据。

库源代码 | 包 (npm)

Prerequisites

  • Azure 订阅服务

    • 如果没有 Azure 订阅，请在开始之前创建一个免费帐户。
  • Node.js 22 或更高版本

设置

首先，为本指南设置帐户和开发环境。 本部分将指导你完成创建帐户、获取其凭据以及准备开发环境的过程。

创建帐户

首先创建用于 Apache Gremlin 帐户的 API。 创建帐户后，创建数据库和图形资源。

  1. 如果还没有目标资源组，请使用 az group create 命令在订阅中创建新的资源组。

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

  2. 使用 az cosmosdb create 命令创建具有默认设置的新 Azure Cosmos DB for Apache Gremlin 帐户。

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

  3. 使用 az cosmosdb gremlin database create 创建一个名为 cosmicworks 的新数据库。

    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. 从节点包管理器 (npm) 安装gremlin包。

    npm install --save gremlin

  4. 创建 index.js 文件。

  1. 从空文件夹开始。

  2. 初始化新模块。

    npm init es6 --yes

  3. 从节点包管理器 (npm) 安装typescript包。

    npm install --save-dev typescript

  4. 在 npm 上安装 tsx 包。

    npm install --save-dev tsx

  5. 在 npm 上安装 gremlin 包。

    npm install --save gremlin

  6. 在 npm 上安装 @types/node 包。

    npm install --save-dev @types/node

  7. 在 npm 上安装 @types/gremlin 包。

    npm install --save-dev @types/gremlin

  8. 使用编译器tsc （） 初始化 TypeScript 项目。

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

  9. 创建 index.ts 文件。

对象模型

DESCRIPTION
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使用验证器变量创建对象。 为变量 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. 在集成开发环境（IDE）中打开 index.ts 文件。

  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使用验证器变量创建对象。 为变量 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>"

后续步骤

适用于 Apache Gremlin 的 Azure Cosmos DB 概述