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

Начало работы с клиентской библиотекой Apache Gremlin для Azure Cosmos DB для .NET для хранения, управления и запроса неструктурированных данных. Выполните действия, описанные в этом руководстве, чтобы создать новую учетную запись, установить клиентская библиотека .NET, подключиться к учетной записи, выполнить общие операции и запросить окончательные образцы данных.

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

Предпосылки

• подписка Azure

  • Если у вас нет подписки на Azure, создайте бесплатную учетную запись перед началом.

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

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

• Пакет SDK для .NET 9.0 или более поздней версии

Настройка

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

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

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

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

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

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

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

1. Начните с пустой папки.

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

   dotnet new console
   

3. Gremlin.Net Импортируйте пакет из NuGet.

   dotnet add package Gremlin.Net
   

4. Создайте проект.

   dotnet build
   

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

Примеры кода

• Проверка подлинности клиента
• Вставка данных
• Чтение данных
• Запрос данных

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

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

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

2. Удалите любое существующее содержимое в файле.

3. Добавьте директивы using для следующих пространств имен:

   • Gremlin.Net.Driver
   • Gremlin.Net.Structure.IO.GraphSON

   using Gremlin.Net.Driver;
   using Gremlin.Net.Structure.IO.GraphSON;
   

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

   string hostname = "<host>";
   string primaryKey = "<key>";
   

5. Создайте GremlinServer с использованием учетных данных и переменных конфигурации, созданных на предыдущих шагах. Присвойте переменной serverимя.

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

6. Теперь создайте GremlinClient, используя переменную server и конфигурацию GraphSON2MessageSerializer.

   GremlinClient client = new(
       server,
       new GraphSON2MessageSerializer()
   );
   

Вставка данных

Затем вставьте новые вершины и пограничные данные в граф. Перед созданием новых данных снимите график всех существующих данных.

1. g.V().drop() Выполните запрос, чтобы очистить все вершины и края из графа.

   await client.SubmitAsync("g.V().drop()");
   

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

   string insertVertexQuery = """
       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.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["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.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["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.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["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, который добавляет ребро.

   string insertEdgeQuery = """
       g.V([prop_partition_key, prop_source_id])
           .addE('replaces')
           .to(g.V([prop_partition_key, prop_target_id]))
   """;
   

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

   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "cccccccc-2222-3333-4444-dddddddddddd"
   });
   

Чтение данных

Затем считывайте данные, которые ранее были вставлены в граф.

1. Создайте запрос, который считывает вершину с помощью уникального идентификатора и значения партиционного ключа.

   string readVertexQuery = "g.V([prop_partition_key, prop_id])";
   

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

   ResultSet<Dictionary<string, object>> readResults = await client.SubmitAsync<Dictionary<string, object>>(readVertexQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   Dictionary<string, object> matchedItem = readResults.Single();
   

Запрос данных

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

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

   string findVerticesQuery = """
       g.V().hasLabel('product')
           .has('category', prop_partition_key)
           .has('name', prop_name)
           .outE('replaces').inV()
   """;
   

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

   ResultSet<Dictionary<string, object>> findResults = await client.SubmitAsync<Dictionary<string, object>>(findVerticesQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_name"] = "Montau Turtle Surfboard"
   });
   

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

   foreach (Dictionary<string, object> result in findResults)
   {
       // Do something here with each result
   }
   

Запустите код

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

dotnet run

Очистите ресурсы

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

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