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

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

适用于: ✅ Apache Gremlin

重要

你是否正在寻找一种数据库解决方案，以应对需要高扩展性、99.999% 可用性服务级别协议（SLA）、即时自动扩展和跨多个区域的自动故障转移的场景？请考虑 Azure Cosmos DB for NoSQL。

您是要构建联机分析处理（OLAP）图表，还是迁移现有的 Apache Gremlin 应用程序？考虑 Microsoft Fabric 中的 Graph。

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

库源代码 | 包 (npm)

Prerequisites

Azure 订阅服务
- 如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

Azure Cloud Shell 中最新版本的 Azure CLI。
- 如果想要在本地运行 CLI 引用命令，请使用 az login 该命令登录到 Azure CLI。

Node.js 22 或更高版本

设置

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

创建帐户

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

Azure CLI
Azure 门户

如果还没有目标资源组，请使用 az group create 命令在订阅中创建新的资源组。
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

使用 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"

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

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

使用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"

登录到 Azure 门户 (https://portal.azure.com)。
在全局搜索栏中输入 Azure Cosmos DB。
在“服务”中，选择“Azure Cosmos DB”。
在 Azure Cosmos DB 窗格中，选择“创建”，然后在“其他”选项卡中选择“用于 Apache Gremlin 的 Azure Cosmos DB”。

在“基本信息”窗格中，配置以下选项，然后选择“查看 + 创建” ：

	值
工作负载类型	学习
订阅	选择您的 Azure 订阅
资源组	创建新的资源组，或选择现有资源组
帐户名	提供一个全局唯一的名称
可用性区域	禁用
位置	为订阅选择支持的 Azure 区域

提示

可以将任何未指定的选项保留为其默认值。还可以将帐户配置为将帐户总吞吐量限制为每秒 1,000 个请求单位（RU/秒），或启用免费层以最大程度地降低成本。

在“查看 + 创建”窗格中，等待帐户验证成功完成，然后选择“创建”。
门户会自动导航到“部署”窗格。等待部署完成。
部署完成后，选择 转到资源 以导航至 Apache Gremlin 帐户的新 API。
在资源菜单中，选择 “数据资源管理器” 选项。
在数据资源管理器中，选择“ + 新建图形”。
在 “添加图形 ”对话框中，配置以下选项，然后选择“ 确定” ：

值

数据库 新建

数据库名称 cosmicworks

图形名称 products

分区键 /category

提示

可以将任何未指定的选项保留为其默认值。

	值
数据库	新建
数据库名称	`cosmicworks`
图形名称	`products`
分区键	`/category`

获取凭据

现在，获取用于创建与最近创建的帐户的连接的客户端库的密码。

Azure CLI
Azure 门户

使用 az cosmosdb show 获取帐户的主机。

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

记录来自上一个命令输出的属性 host 的值。此属性的值是你在本指南后面部分用于通过库连接到帐户的主机。

使用 az cosmosdb keys list 来获取帐户的密钥。

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

记录来自上一个命令输出的属性 primaryMasterKey 的值。此属性的值是本指南稍后使用的密钥，用于通过库连接到帐户。

准备开发环境

然后，使用新项目和客户端库配置开发环境。在转到本指南的其余部分之前，此步骤是最后一个必需的先决条件。

从空文件夹开始。
初始化新模块。
```
npm init es6 --yes
```
从节点包管理器 (npm) 安装gremlin包。
```
npm install --save gremlin
```
创建 index.js 文件。

从空文件夹开始。
初始化新模块。
```
npm init es6 --yes
```
从节点包管理器 (npm) 安装typescript包。
```
npm install --save-dev typescript
```
在 npm 上安装 tsx 包。
```
npm install --save-dev tsx
```
在 npm 上安装 gremlin 包。
```
npm install --save gremlin
```
在 npm 上安装 @types/node 包。
```
npm install --save-dev @types/node
```
在 npm 上安装 @types/gremlin 包。
```
npm install --save-dev @types/gremlin
```

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

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

创建 index.ts 文件。

对象模型

	DESCRIPTION
`DriverRemoteConnection`	表示与 Gremlin 服务器的连接
`GraphTraversalSource`	用于构造和执行 Gremlin 遍历

对客户端进行身份验证

首先，使用本指南前面收集的凭据对客户端进行身份验证。

在集成开发环境中打开 index.js 文件（IDE）。

导入gremlin包和所需的类型：

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

为本指南前面收集的凭据创建字符串变量。命名变量 hostname 和 primaryKey.
```
const hostname = '<host>';
const primaryKey = '<key>';
```
使用前面步骤中创建的凭据和配置变量创建类型 PlainTextSaslAuthenticator 对象。将对象存储在名为 .. 的 authenticator变量中。
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

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

在集成开发环境（IDE）中打开 index.ts 文件。

导入gremlin包和所需的类型：

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

为本指南前面收集的凭据创建字符串变量。命名变量 hostname 和 primaryKey.
```
const hostname: string = '<host>';
const primaryKey: string = '<key>';
```
使用前面步骤中创建的凭据和配置变量创建类型 PlainTextSaslAuthenticator 对象。将对象存储在名为 .. 的 authenticator变量中。
```
const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);
```

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

插入数据

接下来，在图形中插入新的顶点和边缘数据。创建新数据之前，请清除任何现有数据的图形。

g.V().drop()运行查询以清除图形中的所有顶点和边缘。
```
await client.submit('g.V().drop()');
```

创建添加顶点的 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)
`;

为单个产品添加顶点。

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

为两个额外产品再添加两个顶点。

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

创建另一个用于添加边的 Gremlin 查询。

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

添加两个边缘。

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

g.V().drop()运行查询以清除图形中的所有顶点和边缘。
```
await client.submit('g.V().drop()');
```

创建添加顶点的 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)
`;

为单个产品添加顶点。

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

为两个额外产品再添加两个顶点。

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

创建另一个用于添加边的 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]))
`;

添加两个边缘。

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

读取数据

然后，读取以前插入到图形中的数据。

创建使用唯一标识符和分区键值读取顶点的查询。
```
const read_vertex_query = 'g.V([prop_partition_key, prop_id])';
```

然后，通过提供所需的参数来读取顶点。

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

创建使用唯一标识符和分区键值读取顶点的查询。

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

然后，通过提供所需的参数来读取顶点。

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

查询数据

最后，使用查询查找与图中特定遍历或筛选器匹配的所有数据。

创建一个查询，用于查找从特定顶点遍历的所有顶点。

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

执行指定 Montau Turtle Surfboard 产品的查询。

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

迭代遍历查询结果。

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