Краткое руководство. Библиотека Apache Gremlin для .NET для Azure Cosmos DB для Apache Gremlin

Статья
10/06/2023

Область применения: Гремлин

Azure Cosmos DB для Apache Gremlin — это полностью управляемая служба базы данных графа, реализуемая популярную Apache Tinkerpopплатформу вычислений графов с помощью языка запросов Gremlin. API для Gremlin дает вам низкий уровень трения, чтобы приступить к работе с Gremlin со службой, которая может расти и масштабировать столько, сколько вам нужно с минимальным управлением.

В этом кратком руководстве вы используете библиотеку Gremlin.Net для подключения к созданной учетной записи Azure Cosmos DB для Gremlin.

Исходный код библиотеки | Пакет (NuGet)

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

Учетная запись Azure с активной подпиской.
- Нет подписки Azure? Зарегистрируйте бесплатную учетную запись Azure.
- Не хотите подписку Azure? Вы можете попробовать Azure Cosmos DB бесплатно без подписки.
.NET (LTS)
- Не установлен .NET? Воспользуйтесь этим кратким руководством в GitHub Codespaces.
Интерфейс командной строки Azure (CLI)

Azure Cloud Shell

В Azure есть Azure Cloud Shell, интерактивная оболочка среды, с которой можно работать в браузере. Для работы со службами Azure можно использовать Bash или PowerShell с Cloud Shell. Для запуска кода из этой статьи можно использовать предварительно установленные команды Cloud Shell. Ничего дополнительного в локальной среде устанавливать не нужно.

Начало работы с Azure Cloud Shell

Вариант	Пример и ссылка
Нажмите кнопку Попробовать в правом верхнем углу блока кода или команд. При нажатии кнопки Попробовать код или команда не копируется в Cloud Shell автоматически.
Чтобы открыть Cloud Shell в браузере, перейдите по адресу https://shell.azure.com или нажмите кнопку Запуск Cloud Shell.
Нажмите кнопку Cloud Shell в строке меню в правом верхнем углу окна портала Azure.

Чтобы использовать Azure Cloud Shell, выполните следующие действия:

Запустите Cloud Shell.
Нажмите кнопку Копировать в блоке кода (или блоке команд), чтобы скопировать код или команду.
Вставьте код или команду в окно сеанса Cloud Shell, нажав клавиши CTRL+SHIFT+V в Windows и Linux или CMD+SHIFT+V в macOS.
Нажмите клавишу ВВОД, чтобы запустить код или команду.

Установка

В этом разделе описано, как создать API для учетной записи Gremlin и настроить проект .NET, чтобы использовать библиотеку для подключения к учетной записи.

Создание учетной записи API для Gremlin

Перед использованием библиотеки .NET необходимо создать учетную запись API для Gremlin. Кроме того, она также помогает разместить базу данных и граф.

Создайте переменные оболочки для accountName, resourceGroupName и location.

# 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 для учетной записи Gremlin с параметрами по умолчанию.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
Примечание.

Вы можете использовать не более одной учетной записи Azure Cosmos DB категории "Бесплатный" на подписку Azure. При создании учетной записи нужно зарегистрироваться. Если эта команда не применяет скидку на бесплатный уровень, это означает, что другая учетная запись в подписке уже включена с уровнем "Бесплатный".
Получите API для конечной точки Gremlin для учетной записи с помощью az cosmosdb show.
```
az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"
```

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

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

Запишите значения NAME и KEY. Эти учетные данные используются позже.

Создайте базу данных с именем cosmicworks с помощью az cosmosdb gremlin database create.

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

Создание консольного приложения .NET

Создайте консольное приложение .NET в пустой папке с помощью предпочтительного терминала.

Откройте терминал в пустой папке.
Используйте команду dotnet new, указывающую шаблон консоли.
```
dotnet new console
```

Установка пакета NuGet

Добавьте пакет NuGet в Gremlin.NET проект .NET.

dotnet add package Используйте команду, указывающую Gremlin.Net пакет NuGet.
```
dotnet add package Gremlin.Net
```
Создание проекта .NET с помощью dotnet build.
```
dotnet build
```
Убедитесь, что сборка прошла успешно и без ошибок. Ожидаемые выходные данные сборки будут выглядеть примерно следующим образом:
```
Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> \dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)
```

Настройка переменных среды

Чтобы использовать значения 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 для Gremlin используйте значения NAME и URI , полученные ранее в этом кратком руководстве.

Откройте файл Program.cs.
Удалите любое существующее содержимое в файле.
Добавьте блок using для Gremlin.Net.Driver пространства имен.
```
using Gremlin.Net.Driver;
```
Создание accountName и accountKey строковые переменные. Сохраните COSMOS_GREMLIN_ENDPOINT переменные среды и COSMOS_GREMLIN_KEY переменные среды в качестве значений для каждой соответствующей переменной.
```
string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
```

Создайте новый экземпляр GremlinServer с использованием учетных данных учетной записи.

var server = new GremlinServer(
    hostname: $"{accountName}.gremlin.cosmos.azure.com",
    port: 443,
    username: "/dbs/cosmicworks/colls/products",
    password: $"{accountKey}",
    enableSsl: true
);

Создайте новый экземпляр с помощью учетных данных удаленного GremlinClient сервера и сериализатора GraphSON 2.0 .
```
using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);
```

Создание вершин

Теперь, когда приложение подключено к учетной записи, используйте стандартный синтаксис Gremlin для создания вершин.

Используется SubmitAsync для запуска сервера команд на стороне API для учетной записи Gremlin. Создайте вершину продукта со следующими свойствами:

значение

label product

id 68719518371

name Kiama classic surfboard

price 285.55

category surfboards
```
await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', 'surfboards')"
);
```

Создайте вторую вершину продукта со следующими свойствами:

	значение
label	`product`
id	`68719518403`
`name`	`Montau Turtle Surfboard`
`price`	`600.00`
`category`	`surfboards`

await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600.00).property('category', 'surfboards')"
);

Создайте третью вершину продукта с этими свойствами:

	значение
label	`product`
id	`68719518409`
`name`	`Bondi Twin Surfboard`
`price`	`585.50`
`category`	`surfboards`

await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', 'surfboards')"
);

Создание ребер

Создайте края с помощью синтаксиса Gremlin для определения связей между вершинами.

Создайте край из именованного Montau Turtle Surfboard продукта, Kiama classic surfboard заменяющего продукт.
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
);
```
Совет

Это определение края использует g.V(['<partition-key>', '<id>']) синтаксис. Кроме того, можно использовать g.V('<id>').has('category', '<partition-key>').

Создайте другой объект, заменяя ребра из того же продукта Bondi Twin Surfboard.

await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
);

Вершины запросов и края

Используйте синтаксис Gremlin для обхода графа и обнаружения связей между вершинами.

Проходит по графу и находит все вершины, которые Montau Turtle Surfboard заменяются.

var results = await client.SubmitAsync<Dictionary<string, object>>(
    requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
);

Напишите в консоль статическую строку [CREATED PRODUCT]\t68719518403. Затем выполните итерацию по каждой соответствующей вершине с помощью foreach цикла и записи в консоль сообщение, которое начинается с [REPLACES PRODUCT] и включает соответствующее поле продукта id в качестве суффикса.
```
Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}
```

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

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

Откройте терминал в папке проекта .NET.
Используется dotnet run для запуска приложения.
```
dotnet run
```

Просмотрите выходные данные приложения.

[CREATED PRODUCT]       68719518403
[REPLACES PRODUCT]      68719518371
[REPLACES PRODUCT]      68719518409

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

Если вам больше не нужен API для учетной записи Gremlin, удалите соответствующую группу ресурсов.

Создайте переменную оболочки для resourceGroupName , если она еще не существует.
```
# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
```
Используется az group delete для удаления группы ресурсов.
```
az group delete \
    --name $resourceGroupName
```

Следующий шаг

Создание и запрос данных с помощью Azure Cosmos DB для Apache Gremlin

	значение
label	`product`
id	`68719518371`
`name`	`Kiama classic surfboard`
`price`	`285.55`
`category`	`surfboards`