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

ОБЛАСТЬ ПРИМЕНЕНИЯ: API Gremlin

В этом руководстве показано, как использовать PHP и API Gremlin в Azure Cosmos DB для создания консольного приложения путем клонирования примера с сайта GitHub. Кроме того, здесь показано, как создать учетную запись Azure Cosmos DB с помощью веб-портала Azure.

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

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

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

Кроме того, примите во внимание:

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

Перед созданием графовой базы данных необходимо создать учетную запись графовой базы данных Gremlin с Azure Cosmos DB.

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

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

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

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

    Область

  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. Создание учетной записи займет несколько минут. Подождите, пока на портале откроется страница с сообщением Поздравляем! Учетная запись Azure Cosmos DB создана.

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

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

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

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

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

    Страница

  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-php-getting-started.git
    

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

Это необязательный шаг. Если вы хотите узнать, как создать в коде ресурсы базы данных, изучите приведенные ниже фрагменты кода. Они взяты из файла connect.php, который расположен в папке C:\git-samples\azure-cosmos-db-graph-php-getting-started\. Если вас это не интересует, можете сразу переходить к разделу Обновление строки подключения.

  • connection в Gremlin инициализируется в начале файла connect.php с помощью объекта $db.

    $db = new Connection([
        'host' => '<your_server_address>.graphs.azure.com',
        'username' => '/dbs/<db>/colls/<coll>',
        'password' => 'your_primary_key'
        ,'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  • Выполнение шагов Gremlin с использованием метода $db->send($query);.

    $query = "g.V().drop()";
    ...
    $result = $db->send($query);
    $errors = array_filter($result);
    }
    

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

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

  1. На портале Azure щелкните Ключи.

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

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

  2. Откройте файл connect.php и в строке 8 вставьте значение URI вместо your_server_address.

    Код инициализации для объекта подключения теперь должен выглядеть примерно так:

    $db = new Connection([
        'host' => 'testgraphacct.gremlin.cosmosdb.azure.com',
        'username' => '/dbs/<db>/colls/<coll>',
        'password' => 'your_primary_key'
        ,'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  3. Измените параметр username в объекте подключения, указав имена вашей базы данных и графа. Если использовались рекомендуемые значения sample-database и sample-graph, код должен выглядеть следующим образом:

    'username' => '/dbs/sample-database/colls/sample-graph'

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

    $db = new Connection([
        'host' => 'testgraphacct.gremlin.cosmosdb.azure.com',
        'username' => '/dbs/sample-database/colls/sample-graph',
        'password' => 'your_primary_key',
        'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  4. На портале Azure с помощью кнопки "Копировать" скопируйте первичный ключ и вставить его вместо your_primary_key в параметр пароля (password).

    Код инициализации для объекта подключения теперь должен выглядеть так:

    $db = new Connection([
        'host' => 'testgraphacct.graphs.azure.com',
        'username' => '/dbs/sample-database/colls/sample-graph',
        'password' => '2Ggkr662ifxz2Mg==',
        'port' => '443'
    
        // Required parameter
        ,'ssl' => TRUE
    ]);
    
  5. Сохраните файл connect.php.

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

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

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

    composer install
    
  3. В окне терминала Git используйте приведенную ниже команду, чтобы запустить приложение PHP.

    php connect.php
    

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

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

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

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

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

  1. Щелкните Обозреватель данных, затем разверните sample-graph, щелкните Граф и нажмите кнопку Применить фильтр.

    Снимок экрана: раздел

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

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

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

    Снимок экрана: область для ввода значений —

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

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

    Клавиши Значение Примечания
    идентификатор ashley Уникальный идентификатор вершины. Если не указать идентификатор, он создастся автоматически.
    gender Женский
    tech java

    Примечание

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

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

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

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

  9. Щелкните Добавить свойство, чтобы поочередно добавить следующие свойства:

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

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

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

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

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

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

    Добавление связи между пользователями ashley и rakesh в обозревателе данных

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

    Две вершины, связанные между собой в обозревателе данных

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