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

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

В этом кратком руководстве вы научитесь создавать учетную запись API Gremlin (граф) Azure Cosmos DB и управлять ею на портале Azure, а также добавите данные с помощью приложения Node.js, клонированного из GitHub. Azure Cosmos DB — это служба многомодельной базы данных, позволяющая быстро создавать и запрашивать документы, таблицы, пары "ключ-значение" и графовые базы данных, используя возможности глобального распределения и горизонтального масштабирования.

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

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

  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-nodejs-getting-started.git
    
  4. Откройте файл решения в Visual Studio.

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

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

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

Это консольное приложение использует драйвер Gremlin Node.js с открытым кодом.

  • Создание клиента Gremlin.

    const authenticator = new Gremlin.driver.auth.PlainTextSaslAuthenticator(
        `/dbs/${config.database}/colls/${config.collection}`, 
        config.primaryKey
    )
    
    
    const client = new Gremlin.driver.Client(
        config.endpoint, 
        { 
            authenticator,
            traversalsource : "g",
            rejectUnauthorized : true,
            mimeType : "application/vnd.gremlin-v2.0+json"
        }
    );
    
    

    Все конфигурации находятся в файле config.js, который мы изменим в следующем разделе.

  • Для выполнения различных операций Gremlin определяется набор функций. Это один из них:

    function addVertex1()
    {
        console.log('Running Add Vertex1'); 
        return client.submit("g.addV(label).property('id', id).property('firstName', firstName).property('age', age).property('userid', userid).property('pk', 'pk')", {
                label:"person",
                id:"thomas",
                firstName:"Thomas",
                age:44, userid: 1
            }).then(function (result) {
                    console.log("Result: %s\n", JSON.stringify(result));
            });
    }
    
  • Каждая функция выполняет метод client.execute с параметром строки запроса Gremlin. Ниже приведен пример выполнения g.V().count():

    function countVertices()
    {
        console.log('Running Count');
        return client.submit("g.V().count()", { }).then(function (result) {
            console.log("Result: %s\n", JSON.stringify(result));
        });
    }
    
  • В конце файла вызываются все методы. После этого они выполняются один за другим:

    client.open()
    .then(dropGraph)
    .then(addVertex1)
    .then(addVertex2)
    .then(addEdge)
    .then(countVertices)
    .catch((err) => {
        console.error("Error running query...");
        console.error(err)
    }).then((res) => {
        client.close();
        finish();
    }).catch((err) => 
        console.error("Fatal error:", err)
    );
    

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

  1. Откройте файл config.js.

  2. В файле config.js заполните ключ config.endpoint значением конечной точки Gremlin, полученным на странице Обзор учетной записи Cosmos DB на портале Azure.

    config.endpoint = "https://<your_Gremlin_account_name>.gremlin.cosmosdb.azure.com:443/";

    Просмотр и копирование ключа доступа на портале Azure, страница обзора

  3. В файле config.js заполните значения параметра config.primaryKey значением первичного ключа на странице Ключи учетной записи Cosmos DB на портале Azure.

    config.primaryKey = "PRIMARYKEY";

    Колонка Ключи на портале Azure

  4. Введите имя базы данных и графа (контейнера) для значения config.database и config.collection.

Вот как должен выглядеть файл config.js:

var config = {}

// Note that this must include the protocol (HTTPS:// for .NET SDK URI or wss:// for Gremlin Endpoint) and the port number
config.endpoint = "https://testgraphacct.gremlin.cosmosdb.azure.com:443/"; 
config.primaryKey = "Pams6e7LEUS7LJ2Qk0fjZf3eGo65JdMWHmyn65i52w8ozPX2oxY3iP0yu05t9v1WymAHNcMwPIqNAEv3XDFsEg==";
config.database = "graphdb"
config.collection = "Persons"

module.exports = config;

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

  1. Откройте окно терминала. С помощью команды cd перейдите в каталог установки файла package.json, включенного в проект.

  2. Запустите npm install, чтобы установить необходимые модули npm, включая gremlin.

  3. Запустите node app.js в окне терминала, чтобы запустить приложение Node.

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

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

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

Данные, созданные в примере приложения, отображаются в следующей области в пределах вкладки Граф при нажатии Применить фильтр.

Повторите выполнение g.V() с .has('firstName', 'Thomas') для тестирования фильтра. Обратите внимание, что в значении учитывается регистр.

Просмотр соглашений об уровне обслуживания на портале 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, как создать граф с помощью обозревателя данных, а также как запустить приложение Node.js, чтобы добавить данные в граф. Теперь вы можете создавать более сложные запросы и внедрять эффективную логику обхода графа с помощью Gremlin.