Краткое руководство. Создание графовой базы данных с помощью пакета SDK для Java и API Gremlin для Azure Cosmos DB

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

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

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

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

Перед созданием графовой базы данных необходимо создать учетную запись графовой базы данных Gremlin с 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-java-getting-started.git
    

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

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

Следующие фрагменты кода взяты из файла C:\git-samples\azure-cosmos-db-graph-java-getting-started\src\GetStarted\Program.java.

Это консольное приложение Java использует базу данных API Gremlin с драйвером OSS Apache TinkerPop.

  • Client Gremlin инициализируется на основе конфигурации в файле C:\git-samples\azure-cosmos-db-graph-java-getting-started\src\remote.yaml.

    cluster = Cluster.build(new File("src/remote.yaml")).create();
    ...
    client = cluster.connect();
    
  • Ряд шагов Gremlin выполняется с использованием метода client.submit.

    ResultSet results = client.submit(gremlin);
    
    CompletableFuture<List<Result>> completableFutureResults = results.all();
    List<Result> resultList = completableFutureResults.get();
    
    for (Result result : resultList) {
        System.out.println(result.toString());
    }
    

Обновление информации о подключении

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

  1. В учетной записи Azure Cosmos DB на портале Azure выберите элемент Ключи.

    Скопируйте первую часть значения URI.

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

  2. Откройте файл src/remote.yaml и вставьте значение уникального идентификатора вместо $name$ в hosts: [$name$.graphs.azure.com].

    Теперь строка 1 в файле remote.yaml будет выглядеть примерно так:

    hosts: [test-graph.graphs.azure.com]

  3. В значении endpoint измените graphs на gremlin.cosmosdb. (Если учетная запись базы данных графа создана до 20 декабря 2017 г., оставьте значение конечной точки без изменений и перейдите к следующему шагу.)

    Значение конечной точки должно выглядеть так:

    "endpoint": "https://testgraphacct.gremlin.cosmosdb.azure.com:443/"

  4. На портале Azure используйте кнопку "Копировать", чтобы скопировать первичный ключ и вставить его вместо $masterKey$ в password: $masterKey$.

    Теперь строка 4 в файле remote.yaml будет выглядеть примерно так:

    password: 2Ggkr662ifxz2Mg==

  5. В файле remote.yaml измените строку 3. Укажите вместо

    username: /dbs/$database$/colls/$collection$

    значение

    username: /dbs/sample-database/colls/sample-graph

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

  6. Сохраните файл remote.yaml.

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

  1. В окне терминала Git перейдите в папку azure-cosmos-db-graph-java-getting-started с помощью команды cd.

    cd "C:\git-samples\azure-cosmos-db-graph-java-getting-started"
    
  2. В окне терминала Git введите приведенную ниже команду, чтобы установить необходимые пакеты Java.

    mvn package
    
  3. В окне терминала Git выполните следующую команду, чтобы запустить приложение Java.

    mvn exec:java -D exec.mainClass=GetStarted.Program
    

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

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

    Когда программа завершит работу, нажмите клавишу ВВОД и откройте окно веб-браузера с порталом Azure.

Просмотр и добавление демонстрационных данных

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

  1. В учетной записи Azure Cosmos DB на портале Azure выберите Обозреватель данных, разверните sample-graph, а затем выберите Граф и нажмите кнопку Применить фильтр.

    Снимок экрана: выбран пункт &quot;Граф&quot; в разделе API и выделена кнопка &quot;Применить фильтр&quot;.

  2. В списке результатов обратите внимание на новых пользователей, добавленных в граф. Выберите пользователя ben. Вы увидите, что он связан с пользователем robin. Здесь можно перетаскивать вершины мышью, увеличивать или уменьшать масштаб колесиком мыши, а также увеличивать размер графа с помощью двойной стрелки.

    Новые вершины в графе в обозревателе данных на портале Azure

  3. Давайте добавим несколько новых пользователей. Щелкните Создать вершину, чтобы добавить данные в граф.

    Снимок экрана: панель &quot;Новая вершина&quot; для ввода значений.

  4. В поле метки укажите пользователя.

  5. Щелкните Добавить свойство, чтобы добавить каждое из указанных ниже свойств. Обратите внимание, что вы можете создать уникальные свойства для каждого пользователя в графе. Требуется только ключ идентификатора.

    ключ value Примечания
    идентификатор ashley Уникальный идентификатор вершины. Если не указать идентификатор, он создастся автоматически.
    gender Женский
    Технология java

    Примечание

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

  6. Щелкните ОК. Чтобы увидеть кнопку ОК в нижней части экрана, может потребоваться развернуть экран.

  7. Еще раз щелкните Создать вершину, чтобы добавить нового пользователя.

  8. Введите метку person.

  9. Щелкните Добавить свойство, чтобы добавить каждое из указанных ниже свойств:

    ключ value Примечания
    идентификатор rakesh Уникальный идентификатор вершины. Если не указать идентификатор, он создастся автоматически.
    gender Мужской
    Учебное заведение MIT
  10. Щелкните ОК.

  11. Нажмите кнопку Применить фильтр со стандартным значением фильтра g.V(), чтобы отобразить все значения графа. Все пользователи теперь отображаются в списке Результаты.

    По мере добавления новых данных используйте фильтры для ограничения результатов. По умолчанию обозреватель данных использует g.V() для получения всех вершин в графе. Вы можете задать для него другой запрос графа, например g.V().count(), который возвращает число всех вершин графа в формате JSON. Если вы изменили фильтр, снова установите фильтр g.V() и щелкните Применить фильтр, чтобы снова отобразить полный список результатов.

  12. Теперь вы можете соединить пользователей rakesh и ashley. Выберите в списке Результаты пользователя ashley и щелкните Изменение целевого объекта вершины в графе рядом с пунктом Целевые объекты внизу справа. Чтобы отобразить кнопку, может потребоваться развернуть окно.

    Изменение целевого объекта вершины в графе в Azure Cosmos DB

  13. В поле Целевой объект введите rakesh, затем в поле Граничная метка введите слово знает и установите флажок.

    Добавление подключения в обозревателе данных в Azure Cosmos DB

  14. Теперь выберите пользователя rakesh в списке результатов. Вы увидите, что пользователи ashley и rakesh связаны.

    Две соединенных вершины в обозревателе данных в Azure Cosmos DB

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

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