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

  • Статья

Область применения: Гремлин

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

В этом кратком руководстве вы используете библиотеку gremlinpython для подключения к созданной учетной записи Azure Cosmos DB для Gremlin.

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

Необходимые компоненты

Azure Cloud Shell

В Azure есть Azure Cloud Shell, интерактивная оболочка среды, с которой можно работать в браузере. Для работы со службами Azure можно использовать Bash или PowerShell с Cloud Shell. Для запуска кода из этой статьи можно использовать предварительно установленные команды Cloud Shell. Ничего дополнительного в локальной среде устанавливать не нужно.

Начало работы с Azure Cloud Shell

Вариант Пример и ссылка
Нажмите кнопку Попробовать в правом верхнем углу блока кода или команд. При нажатии кнопки Попробовать код или команда не копируется в Cloud Shell автоматически. Screenshot that shows an example of Try It for Azure Cloud Shell.
Чтобы открыть Cloud Shell в браузере, перейдите по адресу https://shell.azure.com или нажмите кнопку Запуск Cloud Shell. Button to launch Azure Cloud Shell.
Нажмите кнопку Cloud Shell в строке меню в правом верхнем углу окна портала Azure. Screenshot that shows the Cloud Shell button in the Azure portal

Чтобы использовать Azure Cloud Shell, выполните следующие действия:

  1. Запустите Cloud Shell.

  2. Нажмите кнопку Копировать в блоке кода (или блоке команд), чтобы скопировать код или команду.

  3. Вставьте код или команду в окно сеанса Cloud Shell, нажав клавиши CTRL+SHIFT+V в Windows и Linux или CMD+SHIFT+V в macOS.

  4. Нажмите клавишу ВВОД, чтобы запустить код или команду.

Установка

В этом разделе описывается создание учетной записи API для Gremlin и настройка проекта Python для подключения к учетной записи библиотеки.

Создание учетной записи API для Gremlin

Учетная запись API для Gremlin должна быть создана перед использованием библиотеки Python. Кроме того, она также помогает разместить базу данных и граф.

  1. Создайте переменные оболочки для accountName, resourceGroupName и location.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
location="westus"

# Variable for account name with a randomly generated suffix

let suffix=$RANDOM*$RANDOM
accountName="msdocs-gremlin-$suffix"

  2. Если вы еще не сделали этого, войдите в Azure CLI с помощью az login.

  3. Используется az group create для создания новой группы ресурсов в подписке.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. Используется az cosmosdb create для создания нового API для учетной записи Gremlin с параметрами по умолчанию.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true

    Примечание.

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

  5. Получите API для конечной точки Gremlin для учетной записи с помощью az cosmosdb show.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

  6. Найдите ключ из списка ключей для учетной записиaz-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  7. Запишите значения NAME и KEY. Эти учетные данные используются позже.

  8. Создайте базу данных с именем cosmicworks с помощью az cosmosdb gremlin database create.

    az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

  9. Создание графа с помощью az cosmosdb gremlin graph create. Присвойте графу productsимя, а затем задайте пропускную способность 400и, наконец, задайте путь ключа /categoryсекции.

    az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400

Создание консольного приложения Python

Создайте консольное приложение Python в пустой папке с помощью предпочтительного терминала.

  1. Откройте терминал в пустой папке.

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

    touch app.py

Установка пакета PyPI

Добавьте пакет PyPI в gremlinpython проект Python.

  1. Создайте файл requirements.txt.

    touch requirements.txt

  2. gremlinpython Добавьте пакет из индекса пакета Python в файл требований.

    gremlinpython==3.7.0

  3. Установите все требования к проекту.

    python install -r requirements.txt

Настройка переменных среды

Чтобы использовать значения NAME и URI , полученные ранее в этом кратком руководстве, сохраните их в новых переменных среды на локальном компьютере под управлением приложения.

  1. Чтобы задать переменную среды, используйте терминал для сохранения значений как COSMOS_ENDPOINT и COSMOS_KEY соответственно.

    export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"

  2. Убедитесь, что переменные среды были заданы правильно.

    printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY

Примеры кода

Код в этой статье подключается к базе данных с именем cosmicworks и графом products. Затем код добавляет вершины и края в граф перед обходом добавленных элементов.

аутентификация клиента;

Запросы приложений к большинству служб Azure должны быть авторизованы. Для API для Gremlin используйте значения NAME и URI , полученные ранее в этом кратком руководстве.

  1. Откройте файл app.py.

  2. Импорт client и serializer из gremlin_python.driver модуля.

    import os
from gremlin_python.driver import client, serializer

    Предупреждение

    В зависимости от версии Python также может потребоваться импортировать asyncio и переопределить политику цикла событий:

    import asyncio
import sys

if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

  3. Создание ACCOUNT_NAME и ACCOUNT_KEY переменные. Сохраните COSMOS_GREMLIN_ENDPOINT переменные среды и COSMOS_GREMLIN_KEY переменные среды в качестве значений для каждой соответствующей переменной.

    ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]

  4. Используется Client для подключения с помощью учетных данных учетной записи и сериализатора GraphSON 2.0 .

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

Создание вершин

Теперь, когда приложение подключено к учетной записи, используйте стандартный синтаксис Gremlin для создания вершин.

  1. Используется submit для запуска сервера команд на стороне API для учетной записи Gremlin. Создайте вершину продукта со следующими свойствами:

    значение
    label product
    id 68719518371
    name Kiama classic surfboard
    price 285.55
    category surfboards 
    client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518371",
        "prop_name": "Kiama classic surfboard",
        "prop_price": 285.55,
        "prop_partition_key": "surfboards",
    },
)

  2. Создайте вторую вершину продукта со следующими свойствами:

    значение
    label product
    id 68719518403
    name Montau Turtle Surfboard
    price 600.00
    category surfboards 
    client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518403",
        "prop_name": "Montau Turtle Surfboard",
        "prop_price": 600.00,
        "prop_partition_key": "surfboards",
    },
)

  3. Создайте третью вершину продукта с этими свойствами:

    значение
    label product
    id 68719518409
    name Bondi Twin Surfboard
    price 585.50
    category surfboards 
    client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518409",
        "prop_name": "Bondi Twin Surfboard",
        "prop_price": 585.50,
        "prop_partition_key": "surfboards",
    },
)

Создание ребер

Создайте края с помощью синтаксиса Gremlin для определения связей между вершинами.

  1. Создайте край из именованного Montau Turtle Surfboard продукта, Kiama classic surfboard заменяющего продукт.

    client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_source_id": "68719518403",
        "prop_target_id": "68719518371",
    },
)

    Совет

    Это определение края использует g.V(['<partition-key>', '<id>']) синтаксис. Кроме того, можно использовать g.V('<id>').has('category', '<partition-key>').

  2. Создайте другой объект, заменяя ребра из того же продукта Bondi Twin Surfboard.

    client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_source_id": "68719518403",
        "prop_target_id": "68719518409",
    },
)

Вершины запросов и края

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

  1. Проходит по графу и находит все вершины, которые Montau Turtle Surfboard заменяются.

    result = client.submit(
    message=(
        "g.V().hasLabel('product')"
        ".has('category', prop_partition_key)"
        ".has('name', prop_name)"
        ".outE('replaces').inV()"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_name": "Montau Turtle Surfboard",
    },
)

  2. Напишите в консоль результат этого обхода.

    print(result)

Выполнение кода

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

  1. Откройте терминал в папке проекта Python.

  2. Используется python <filename> для запуска приложения. Просмотрите выходные данные приложения.

    python app.py

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

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

  1. Создайте переменную оболочки для resourceGroupName , если она еще не существует.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"

  2. Используется az group delete для удаления группы ресурсов.

    az group delete \
    --name $resourceGroupName

Следующий шаг

Создание и запрос данных с помощью Azure Cosmos DB для Apache Gremlin