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

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

项目
12/11/2023

适用对象： Gremlin

Azure Cosmos DB for Apache Gremlin 是一种完全托管的图形数据库服务，用于实现常用的 Apache Tinkerpop（使用 Gremlin 查询语言的图形计算框架）。 API for Gremlin 为你提供了一种低摩擦方式来将 Gremlin 与服务结合使用，可通过最少的管理根据需要进行增长和横向扩展。

在本快速入门中，你会使用gremlin库连接到新建的 Azure Cosmos DB for Gremlin 帐户。

库源代码 | 包 (npm)

先决条件

具有活动订阅的 Azure 帐户。
- 无 Azure 订阅？注册免费 Azure 帐户。
- 不需要 Azure 订阅？可以免费试用 Azure Cosmos DB，无需订阅。
Node.js (LTS)
- 尚未安装 Node.js？在GitHub Codespaces.codespaces.new/github/codespaces-blank?/quickstart=1) 中试用此快速入门
Azure 命令行接口 (CLI)

Azure Cloud Shell

Azure 托管 Azure Cloud Shell（一个可通过浏览器使用的交互式 shell 环境）。可以将 Bash 或 PowerShell 与 Cloud Shell 配合使用来使用 Azure 服务。可以使用 Cloud Shell 预安装的命令来运行本文中的代码，而不必在本地环境中安装任何内容。

若要启动 Azure Cloud Shell，请执行以下操作：

选项	示例/链接
选择代码或命令块右上角的“试用”。选择“试用”不会自动将代码或命令复制到 Cloud Shell。
转到 https://shell.azure.com 或选择“启动 Cloud Shell”按钮可在浏览器中打开 Cloud Shell。
选择 Azure 门户右上角菜单栏上的 Cloud Shell 按钮。

若要使用 Azure Cloud Shell，请执行以下操作：

启动 Cloud Shell。
选择代码块（或命令块）上的“复制”按钮以复制代码或命令。
在 Windows 和 Linux 上选择 Ctrl+Shift+V，或在 macOS 上选择 Cmd+Shift+V 将代码或命令粘贴到 Cloud Shell 会话中。
选择“Enter”运行代码或命令。

设置

本部分会引导你创建 API for Gremlin 帐户和设置 Node.js 项目以使用该库连接到帐户。

创建 API for Gremlin 帐户

在使用 Node.js 库之前，应先创建 API for Gremlin 帐户。此外，它还有助于设置数据库和图形。

为 accountName、resourceGroupName 和 location 创建 shell 变量。

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
location="westus"

# Variable for account name with a randomly generated suffix

let suffix=$RANDOM*$RANDOM
accountName="msdocs-gremlin-$suffix"

如果尚未登录到 Azure CLI，请使用 az login 登录。

使用 az group create 在订阅中创建新的资源组。

az group create \
    --name $resourceGroupName \
    --location $location

使用 az cosmosdb create 创建具有默认设置的新 API for Gremlin 帐户。
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
注意

每个 Azure 订阅最多可以有一个免费层 Azure Cosmos DB 帐户，并且你必须在创建帐户时选择加入使用。如果此命令无法用于应用免费层折扣的选项，这意味着订阅中的另一个帐户已启用免费层。

使用 az cosmosdb show 获取帐户的 API for Gremlin 终结点 NAME。

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

使用 az-cosmosdb-keys-list 从帐户的密钥列表中查找 KEY。

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

记录 NAME 和 KEY 的值。稍后会使用这些凭据。

使用 az cosmosdb gremlin database create 创建名为“cosmicworks”的数据库。

az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

使用 az cosmosdb gremlin graph create 创建图形。将图形命名为products，然后将吞吐量设置为400，最后将分区键路径设置为/category。

az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400

新建 Node.js 控制台应用程序

使用首选终端在空文件夹中新建 Node.js 控制台应用程序。

在空文件夹中打开终端。
初始化新模块
```
npm init es6 --yes
```
创建app.js文件
```
touch app.js
```

安装 npm 包

将 gremlin npm 包添加到 Node.js 项目。

打开package.json文件，并将内容替换为此 JSON 配置。

{
  "main": "app.js",
  "type": "module",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "gremlin": "^3.*"
  }
}

使用npm install命令安装package.json文件中指定的所有包。
```
npm install
```

配置环境变量

要使用本快速入门中前面获得的 NAME 和 URI 值，请将其保存到运行应用程序的本地计算机上的新环境变量。

要设置环境变量，请使用终端将值分别保留为“COSMOS_ENDPOINT”和“COSMOS_KEY”。
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```

验证是否已正确设置环境变量。

printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY

本文中的代码连接到名为“cosmicworks”的数据库和名为“products”的图形。然后，代码在遍历添加的项之前，将顶点和边缘添加到图形。

验证客户端

对大多数 Azure 服务的应用程序请求必须获得授权。对于 API for Gremlin，请使用本快速入门前面获取的名称和URI值。

打开app.js文件。
导入 gremlin 模块。
```
import gremlin from 'gremlin'
```
创建 accountName 和 accountKey 变量。将COSMOS_GREMLIN_ENDPOINT和COSMOS_GREMLIN_KEY环境变量存储为每个相应变量的值。
```
const accountName = process.env.COSMOS_GREMLIN_ENDPOINT
const accountKey = process.env.COSMOS_GREMLIN_KEY
```

使用PlainTextSaslAuthenticator为帐户的凭据新建对象。

const credentials = new gremlin.driver.auth.PlainTextSaslAuthenticator(
  '/dbs/cosmicworks/colls/products',
  `${accountKey}`
)

使用Client通过远程服务器凭据和GraphSON 2.0序列化程序进行连接。然后，使用Open新建与服务器的连接。

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

client.open()

创建顶点

现在，应用程序已连接到帐户，请使用标准 Gremlin 语法创建顶点。

使用“submit”在 API for Gremlin 帐户的服务器端运行命令。使用以下属性创建产品顶点：

	值
label	`product`
id	`68719518371`
`name`	`Kiama classic surfboard`
`price`	`285.55`
`category`	`surfboards`

await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518371',
    prop_name: 'Kiama classic surfboard',
    prop_price: 285.55,
    prop_partition_key: 'surfboards'
  }
)

使用以下属性创建第二个产品顶点：

	值
label	`product`
id	`68719518403`
`name`	`Montau Turtle Surfboard`
`price`	`600.00`
`category`	`surfboards`

await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518403',
    prop_name: 'Montau Turtle Surfboard',
    prop_price: 600.00,
    prop_partition_key: 'surfboards'
  }
)

使用以下属性创建第三个产品顶点：

	值
label	`product`
id	`68719518409`
`name`	`Bondi Twin Surfboard`
`price`	`585.50`
`category`	`surfboards`

await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518409',
    prop_name: 'Bondi Twin Surfboard',
    prop_price: 585.50,
    prop_partition_key: 'surfboards'
  }
)

创建边缘

使用 Gremlin 语法创建边缘，以定义顶点之间的关系。

创建从名为“替换”的 Montau Turtle Surfboard 产品到 Kiama classic surfboard 产品的边缘。

await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    prop_partition_key: 'surfboards',
    prop_source_id: '68719518403',
    prop_target_id: '68719518371'
  }
)

提示

此边缘定义使用 g.V(['<partition-key>', '<id>']) 语法。或者，也可使用 g.V('<id>').has('category', '<partition-key>')。

创建从同一产品到 Bondi Twin Surfboard 的另一个替换边缘。

await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    prop_partition_key: 'surfboards',
    prop_source_id: '68719518403',
    prop_target_id: '68719518409'
  }
)

查询顶点和边缘

使用 Gremlin 语法遍历图形并发现顶点之间的关系。

遍历图形并查找 Montau Turtle Surfboard 替换的所有顶点。

const result = await client.submit(
  'g.V().hasLabel(\'product\').has(\'category\', prop_partition_key).has(\'name\', prop_name).outE(\'replaces\').inV()', {
    prop_partition_key: 'surfboards',
    prop_name: 'Montau Turtle Surfboard'
  }
)

将此遍历的结果写入控制台。
```
console.dir(result)
```

运行代码

运行应用程序以验证应用程序是否按预期工作。应用程序执行时应没有错误或警告。应用程序的输出包括有关创建项和查询项的数据。

在 Node.js 项目文件夹中打开终端。
使用npm <script>运行应用程序。观察应用程序的输出。
```
npm start
```

清理资源

当不再需要 API for Gremlin 帐户时，删除相应的资源组。

为 resourceGroupName 创建 shell 变量（如果尚不存在）。

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"

使用 az group delete 删除资源组。

az group delete \
    --name $resourceGroupName

下一步

使用 Azure Cosmos DB for Apache Gremlin 创建和查询数据

通过