Краткое руководство. Создание приложения .NET Framework или Core с помощью учетной записи API Gremlin для Azure Cosmos DB

ПРИМЕНИМО К: API Gremlin

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

В этом кратком руководстве описано, как создать учетную запись API Gremlin для Azure Cosmos DB, базу данных и граф (контейнер) с помощью портала Azure. Затем вы можете создать и запустить консольное приложение c помощью драйвера Gremlin.Net с открытым кодом.

Предварительные требования

Если вы еще не установили Visual Studio 2019, вы можете скачать и использовать бесплатную среду Visual Studio 2019 Community Edition. При установке Visual Studio необходимо включить возможность разработки для Azure.

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

Создание учетной записи базы данных

  1. В новом окне браузера войдите на портал Azure.

  2. В меню слева выберите Создать ресурс.

    Создание ресурса на портале Azure

  3. На странице New (Новый) выберите Базы данных > Azure Cosmos DB.

    Область "Базы данных" на портале Azure

  4. На странице Создание учетной записи Azure Cosmos DB введите параметры для новой учетной записи Azure Cosmos DB.

    Параметр Значение Описание
    Подписка имя подписки; Выберите подписку Azure, которую нужно использовать для этой учетной записи Azure Cosmos.
    Группа ресурсов Имя группы ресурсов Выберите группу ресурсов или Создать, затем введите уникальное имя для новой группы ресурсов.
    Имя учетной записи Введите уникальное имя. Введите уникальное имя для идентификации вашей учетной записи Azure Cosmos DB. URI вашей учетной записи gremlin.azure.com будет добавлен к уникальному имени учетной записи.

    Имя может содержать только строчные буквы, цифры и дефисы (-). Его длина должна быть от 3 до 44 знаков.
    API Gremlin (граф) API определяет тип учетной записи, которую нужно создать. Azure Cosmos DB предоставляет пять API: API Core (SQL) для баз данных документов, API Gremlin для графовых баз данных, API MongoDB для баз данных документов, API таблиц Azure и API Cassandra. Для каждого API требуется создать отдельную учетную запись.

    Выберите Gremlin (граф), так как при работе с этим кратким руководством вы создаете таблицу, которая работает с API Gremlin.

    Дополнительные сведения об API Gremlin.
    Расположение Ближайший к пользователям регион Выберите географическое расположение для размещения учетной записи Azure Cosmos DB. Используйте ближайшее к пользователям расположение, чтобы предоставить им максимально быстрый доступ к данным.
    Режим емкости "Подготовленная пропускная способность" или "Бессерверный" Выберите Подготовленная пропускная способность, чтобы создать учетную запись в режиме подготовленной пропускной способности. Выберите Бессерверный, чтобы создать учетную запись в режиме Бессерверный.
    Применение скидки на основе категории "Бесплатный" для Azure Cosmos DB Применить или не применять В категории "Бесплатный" Azure Cosmos DB для учетной записи бесплатно предоставляются первые 1000 единиц запросов в секунду и 25 ГБ свободного места. Ознакомьтесь с дополнительными сведениями о категории "Бесплатный".

    Примечание

    Вы можете использовать не более одной учетной записи Azure Cosmos DB категории "Бесплатный" на подписку Azure. При создании учетной записи нужно зарегистрироваться. Если параметр подачи заявки на скидку на основе категории "Бесплатный" не отображается, это означает, что в подписке уже включена другая учетная запись категории "Бесплатный".

    Страница Новая учетная запись для Azure Cosmos DB

  5. На вкладке Глобальное распределение настройте следующие сведения. При работе с этим кратким руководством можно оставить значения по умолчанию.

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

    Примечание

    Следующие параметры недоступны, если вы выбрали значение Бессерверный для параметра Режим емкости:

    • Применение скидки на основе категории "Бесплатный"
    • Геоизбыточность
    • Выполнение операций записи в нескольких регионах
  6. При необходимости можно настроить дополнительные сведения на следующих вкладках.

  7. Выберите Review + create (Просмотреть и создать).

  8. Создание учетной записи займет несколько минут. Дождитесь, пока на портале откроется страница с сообщением Congratulations! Your Azure Cosmos DB account was created (Поздравляем! Ваша учетная запись Azure Cosmos DB создана).

    Страница с созданной учетной записью Azure Cosmos DB

Добавление графа

Теперь вы можете использовать обозреватель данных на портале Azure для создания базы данных графов.

  1. Выберите Data Explorer > New Graph (Создать граф).

    Справа отобразится область Добавление графа (вам может потребоваться прокрутить вправо, чтобы увидеть ее).

    Страница добавления графа в обозревателе данных на портале Azure

  2. На странице Добавление графа введите параметры для нового графа.

    Параметр Рекомендуемое значение Описание
    Идентификатор базы данных sample-database Введите имя новой базы данных, например sample-database. Имя базы данных может иметь длину от 1 до 255 символов и не может содержать / \ # ? или пробел.
    Пропускная способность 400 ЕЗ Укажите для пропускной способности 400 единиц запросов в секунду. Чтобы сократить задержку, позже вы можете увеличить масштаб пропускной способности.
    Идентификатор графа sample-graph Введите имя новой коллекции, например sample-graph. Для имен графов предусмотрены те же требования к символам, что и для идентификаторов баз данных.
    Ключ раздела /pk Всем учетным записям Cosmos DB требуется ключ раздела для выполнения горизонтального масштабирования. Сведения о выборе подходящего ключа раздела см. в статье Использование секционированного графа в Azure Cosmos DB.
  3. После заполнения формы нажмите кнопку ОК.

Клонирование примера приложения

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

  1. Откройте командную строку, создайте папку git-samples, а затем закройте окно командной строки.

    md "C:\git-samples"
    
  2. Откройте окно терминала git, например git bash, и выполните команду cd, чтобы перейти в новую папку для установки примера приложения.

    cd "C:\git-samples"
    
  3. Выполните команду ниже, чтобы клонировать репозиторий с примером. Эта команда создает копию примера приложения на локальном компьютере.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git
    
  4. Затем откройте файл решения в Visual Studio.

  5. Восстановите пакеты NuGet в проекте, в том числе драйвер Gremlin.Net и пакет Newtonsoft.Json.

  6. Вы также можете установить драйвер Gremlin.Net@v3.4.6 вручную, используя диспетчер пакетов NuGet или служебную программу командной строки NuGet.

    nuget install Gremlin.NET -Version 3.4.6
    

Примечание

Сейчас API Gremlin поддерживает только Gremlin.NET до версии 3.4.6. В случае установки последней версии вы получите ошибки при использовании службы.

Просмотр кода

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

Приведенные ниже фрагменты кода взяты из файла Program.cs.

  • Задайте параметры подключения на основе учетной записи, созданной ранее:

    private static string Host => Environment.GetEnvironmentVariable("Host") ?? throw new ArgumentException("Missing env var: Host");
    private static string PrimaryKey => Environment.GetEnvironmentVariable("PrimaryKey") ?? throw new ArgumentException("Missing env var: PrimaryKey");
    private static string Database => Environment.GetEnvironmentVariable("DatabaseName") ?? throw new ArgumentException("Missing env var: DatabaseName");
    private static string Container => Environment.GetEnvironmentVariable("ContainerName") ?? throw new ArgumentException("Missing env var: ContainerName");
    
    private static bool EnableSSL
    {
        get
        {
            if (Environment.GetEnvironmentVariable("EnableSSL") == null)
            {
                return true;
            }
    
            if (!bool.TryParse(Environment.GetEnvironmentVariable("EnableSSL"), out bool value))
            {
                throw new ArgumentException("Invalid env var: EnableSSL is not a boolean");
            }
    
            return value;
        }
    }
    
    private static int Port
    {
        get
        {
            if (Environment.GetEnvironmentVariable("Port") == null)
            {
                return 443;
            }
    
            if (!int.TryParse(Environment.GetEnvironmentVariable("Port"), out int port))
            {
                throw new ArgumentException("Invalid env var: Port is not an integer");
            }
    
            return port;
        } 
    }
    
  • Команды Gremlin, которые необходимо выполнить, перечислены в словаре:

    private static Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
    {
        { "Cleanup",        "g.V().drop()" },
        { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44).property('pk', 'pk')" },
        { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39).property('pk', 'pk')" },
        { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller').property('pk', 'pk')" },
        { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield').property('pk', 'pk')" },
        { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
        { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
        { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
        { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
        { "CountVertices",  "g.V().count()" },
        { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
        { "Project",        "g.V().hasLabel('person').values('firstName')" },
        { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
        { "Traverse",       "g.V('thomas').out('knows').hasLabel('person')" },
        { "Traverse 2x",    "g.V('thomas').out('knows').hasLabel('person').out('knows').hasLabel('person')" },
        { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
        { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
        { "CountEdges",     "g.E().count()" },
        { "DropVertex",     "g.V('thomas').drop()" },
    };
    
  • Создайте объекты подключения GremlinServer и GremlinClient, используя параметры, приведенные выше:

    string containerLink = "/dbs/" + Database + "/colls/" + Container;
    Console.WriteLine($"Connecting to: host: {Host}, port: {Port}, container: {containerLink}, ssl: {EnableSSL}");
    var gremlinServer = new GremlinServer(Host, Port, enableSsl: EnableSSL, 
                                            username: containerLink, 
                                            password: PrimaryKey);
    
    ConnectionPoolSettings connectionPoolSettings = new ConnectionPoolSettings()
    {
        MaxInProcessPerConnection = 10,
        PoolSize = 30, 
        ReconnectionAttempts= 3,
        ReconnectionBaseDelay = TimeSpan.FromMilliseconds(500)
    };
    
    var webSocketConfiguration =
        new Action<ClientWebSocketOptions>(options =>
        {
            options.KeepAliveInterval = TimeSpan.FromSeconds(10);
        });
    
    
    using (var gremlinClient = new GremlinClient(
        gremlinServer, 
        new GraphSON2Reader(), 
        new GraphSON2Writer(), 
        GremlinClient.GraphSON2MimeType, 
        connectionPoolSettings, 
        webSocketConfiguration))
    {
    
  • Выполните каждый запрос Gremlin, используя объект GremlinClient с асинхронной задачей. Вы можете считать запросы Gremlin из словаря, определенного на предыдущем шаге, и выполнять их. Позже вы можете получить результат и выполнить чтение значений, отформатированных как словарь, с помощью класса JsonSerializer из пакета Newtonsoft.json:

    foreach (var query in gremlinQueries)
    {
        Console.WriteLine(String.Format("Running this query: {0}: {1}", query.Key, query.Value));
    
        // Create async task to execute the Gremlin query.
        var resultSet = SubmitRequest(gremlinClient, query).Result;
        if (resultSet.Count > 0)
        {
            Console.WriteLine("\tResult:");
            foreach (var result in resultSet)
            {
                // The vertex results are formed as Dictionaries with a nested dictionary for their properties
                string output = JsonConvert.SerializeObject(result);
                Console.WriteLine($"\t{output}");
            }
            Console.WriteLine();
        }
    
        // Print the status attributes for the result set.
        // This includes the following:
        //  x-ms-status-code            : This is the sub-status code which is specific to Cosmos DB.
        //  x-ms-total-request-charge   : The total request units charged for processing a request.
        //  x-ms-total-server-time-ms   : The total time executing processing the request on the server.
        PrintStatusAttributes(resultSet.StatusAttributes);
        Console.WriteLine();
    }
    

Обновление строки подключения

Теперь вернитесь на портал Azure, чтобы получить данные строки подключения. Скопируйте эти данные в приложение.

  1. На портале Azure перейдите к учетной записи службы базы данных графа. На вкладке Обзор вкладку вы увидите две конечные точки:

    URI пакета SDK для .NET — это значение используется при подключении к учетной записи графа с помощью библиотеки Microsoft.Azure.Graphs.

    Конечная точка Gremlin — это значение используется при подключении к учетной записи графа с помощью библиотеки Gremlin.Net.

    Копирование конечной точки

    Чтобы запустить этот пример, скопируйте значение конечной точки Gremlin, удалите номер порта в конце, где URI принимает значение https://<your cosmos db account name>.gremlin.cosmosdb.azure.com. Значение конечной точки должно выглядеть как testgraphacct.gremlin.cosmosdb.azure.com

  2. Затем перейдите на вкладку Ключи и скопируйте значение Первичный ключ c портала Azure.

  3. После того как вы скопировали URI и первичный ключ своей учетной записи, сохраните их в новой переменной среды на локальном компьютере, на котором запущено приложение. Чтобы установить переменную среды, откройте окно командной строки и выполните следующую команду. Обязательно замените значения <Your_Azure_Cosmos_account_URI> и <Your_Azure_Cosmos_account_PRIMARY_KEY>.

    setx Host "<your Azure Cosmos account name>.gremlin.cosmosdb.azure.com"
    setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"
    
  4. Откройте файл Program.cs и обновите переменные database и container, используя базу данных и контейнер (которые также являются именами графов), созданные выше.

    private static string database = "your-database-name"; private static string container = "your-container-or-graph-name";

  5. Сохраните файл Program.cs.

Теперь приложение со всеми сведениями, необходимыми для взаимодействия с Azure Cosmos DB, обновлено.

Запуск консольного приложения

Нажмите клавиши CTRL+F5 для запуска приложения. Приложение выведет команды запроса Gremlin и результаты в консоль.

В окне консоли появятся вершины и ребра, добавляемые в граф. После завершения сценария закройте окно консоли, нажав клавишу ВВОД.

Просмотр с помощью обозревателя данных

Теперь вернитесь в обозреватель данных на портале Azure. Здесь вы можете просмотреть и запросить новые данные графа.

  1. В обозревателе данных новая база данных отображается в области "Графы". Разверните базу данных и узлы контейнера, а затем щелкните Граф.

  2. Нажмите кнопку Применить фильтр, чтобы использовать запрос по умолчанию для просмотра всех вершин графа. Данные, созданные в примере приложения, отображаются на панели Graphs (Графы).

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

    Просмотр графа в обозревателе данных на портале Azure

Просмотр соглашений об уровне обслуживания на портале Azure

На портале Azure можно отслеживать пропускную способность, объем хранилища, доступность, задержку и согласованность учетной записи Cosmos DB. На диаграммах метрик, связанных с соглашением об уровне обслуживания для Azure Cosmos DB, отображается значение, указанное в соглашении об уровне обслуживания, в сравнении с фактической производительностью. Этот набор метрик обеспечивает прозрачный мониторинг выполнения соглашения об уровне обслуживания.

Чтобы просмотреть метрики и соглашения об уровне обслуживания, сделайте следующее:

  1. Выберите Метрики в меню навигации учетной записи Cosmos DB.

  2. Выберите вкладку, например Задержка, и укажите временной интервал справа. Сравните на диаграмме строки Actual (Фактическое значение) и SLA (Соглашение об уровне обслуживания).

    Набор метрик Azure Cosmos DB

  3. Просмотрите метрики на других вкладках.

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

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

  1. На панели поиска портала Azure найдите и выберите Группы ресурсов.

  2. Выберите из списка группу ресурсов, созданную для этого краткого руководства.

    Выбор удаляемой группы ресурсов

  3. На странице обзора группы ресурсов выберите Удалить группу ресурсов.

    удаление группы ресурсов.

  4. В следующем окне введите имя группы ресурсов, которую требуется удалить, и щелкните Удалить.

Дальнейшие действия

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