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

• Python
• Node.js
• C#

Important

Вы ищете решение для баз данных для крупномасштабных сценариев с соглашением об уровне обслуживания (SLA) с доступностью 99,999%, мгновенным автомасштабированием и автоматическим переключением на резервные ресурсы в нескольких регионах? Рассмотрим Azure Cosmos DB для NoSQL.

Вы хотите реализовать граф интерактивной аналитической обработки (OLAP) или перенести существующее приложение Apache Gremlin? Рассмотрим Graph в Microsoft Fabric.

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

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

Предпосылки

• подписка Azure

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

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

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

• Python 3.12 или более поздней версии

Настройка

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

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

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

Azure CLI

1. Если у вас еще нет целевой группы ресурсов, используйте az group create команду для создания новой группы ресурсов в подписке.

   az group create \
       --name "<resource-group-name>" \
       --location "<location>"
   

2. Используйте команду az cosmosdb create, чтобы создать новую Azure Cosmos DB для учетной записи Apache Gremlin с параметрами по умолчанию.

   az cosmosdb create \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --locations "regionName=<location>" \
       --capabilities "EnableGremlin"
   

3. Создайте новую базу данных с именем az cosmosdb gremlin database createcosmicworks.

   az cosmosdb gremlin database create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --name "cosmicworks"
   

4. az cosmosdb gremlin graph create Используйте команду для создания нового графа с именемproducts.

   az cosmosdb gremlin graph create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --database-name "cosmicworks" \
       --name "products" \
       --partition-key-path "/category"
   

Портал Azure

1. Войдите на портал Azure (https://portal.azure.com).

2. Введите Azure Cosmos DB в глобальной строке поиска.

3. В Services выберите Azure Cosmos DB.

4. В области Azure Cosmos DB выберите Create, а затем Azure Cosmos DB для Apache Gremlin на вкладке Others.

5. В области "Основные сведения" настройте следующие параметры и нажмите кнопку "Проверить и создать".

   	Value
   Тип рабочей нагрузки	Обучение
   Подписка	Выберите подписку Azure.
   Группа ресурсов	Создание новой группы ресурсов или выбор существующей группы ресурсов
   Имя аккаунта	Укажите глобально уникальное имя
   Зоны доступности	Отключить
   Местоположение	Выберите поддерживаемый регион Azure для подписки

   Tip

   Вы можете оставить любые не указанные параметры значениями по умолчанию. Вы также можете настроить учетную запись, чтобы ограничить общую пропускную способность учетной записи до 1000 единиц запросов в секунду (ЕЗ/с) или включить бесплатный уровень для минимизации затрат.

6. На панели "Проверка и создание" дождитесь успешной проверки учетной записи и нажмите кнопку "Создать".

7. Портал автоматически переходит в область развертывания. Дождитесь завершения развертывания.

8. После завершения развертывания выберите "Перейти к ресурсу" , чтобы перейти к новой учетной записи API для Apache Gremlin.

9. В меню ресурсов выберите параметр Data Explorer.

10. В обозревателе данных выберите +Создать граф.

11. В диалоговом окне "Добавление графа" настройте следующие параметры и нажмите кнопку "ОК".

    	Value
    База данных	Создать
    Имя базы данных	cosmicworks
    Имя графа	products
    Ключ раздела	/category

    Tip

    Вы можете оставить любые не указанные параметры значениями по умолчанию.

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

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

Azure CLI

1. Используйте az cosmosdb show для получения хоста для учетной записи.

   az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "{host:name}"
   

2. Запишите значение host свойства из выходных данных предыдущих команд. Значение этого свойства — это хост, который вы используете далее в этом руководстве для подключения к учетной записи и библиотеке.

3. Используйте az cosmosdb keys list для получения ключей для учетной записи.

   az cosmosdb keys list \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --type "keys"
   

4. Запишите значение primaryMasterKey свойства из выходных данных предыдущих команд. Это значение свойства — это ключ , который вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.

Портал Azure

1. В меню ресурсов для учетной записи выберите пункт "Обзор ".

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

3. В меню ресурсов для учетной записи снова выберите параметр "Строки подключения " в разделе "Параметры ".

4. Отобразите и запишите значение поля PRIMARY KEY на этой странице. Это значение свойства — это ключ , который вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.

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

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

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

2. gremlinpython Импортируйте пакет из индекса пакетов Python (PyPI).

   pip install gremlinpython
   

3. Создайте файл app.py.

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

	Description
GremlinClient	Представляет клиент, используемый для подключения и взаимодействия с сервером Gremlin
GraphTraversalSource	Используется для создания и выполнения обходов Gremlin

Примеры кода

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

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

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

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

2. Импортируйте следующие типы из библиотеки gremlin_python.driver :

   • gremlin_python.driver.client
   • gremlin_python.driver.serializer

   from gremlin_python.driver import client, serializer
   

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

   hostname = "<host>"
   primary_key = "<key>"
   

4. Client Создайте объект с помощью учетных данных и переменных конфигурации, созданных на предыдущих шагах. Присвойте переменной clientимя.

   client = client.Client(
       url=f"wss://{hostname}.gremlin.cosmos.azure.com:443/",
       traversal_source="g",
       username="/dbs/cosmicworks/colls/products",
       password=f"{primary_key}",
       message_serializer=serializer.GraphSONSerializersV2d0()
   )
   

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

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

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

   client.submit("g.V().drop()").all().result()
   

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

   insert_vertex_query = (
       "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. Добавьте вершину для одного продукта.

   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   

4. Добавьте еще две вершины для дополнительных двух продуктов.

   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   
   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   

5. Создайте ещё один запрос Gremlin, который добавляет ребро.

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

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

   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       },
   ).all().result()
   
   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "cccccccc-2222-3333-4444-dddddddddddd",
       },
   ).all().result()
   

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

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

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

   read_vertex_query = "g.V([prop_partition_key, prop_id])"
   

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

   matched_item = client.submit(
       message=read_vertex_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
       }
   ).one()
   

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

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

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

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

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

   find_results = client.submit(
       message=find_vertices_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_name": "Montau Turtle Surfboard",
       },
   ).all().result()
   

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

   for result in find_results:
       # Do something here with each result
   

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

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

python app.py

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

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

Azure CLI

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

Портал Azure

1. Перейдите к существующему ресурсу Azure Cosmos DB для Apache Gremlin , созданному ранее в этом руководстве.

2. На странице ресурса выберите "Удалить " в строке меню.

3. Следуйте инструкциям в диалоговом окне подтверждения.