Обзор GraphQL API

InfraVision предоставляет GraphQL API только для чтения в дополнение к REST API. Этот API работает на базе Strawberry Django.

Запросы

GraphQL позволяет клиенту указать произвольный вложенный список полей для включения в ответ. Все запросы выполняются к корневой точке API /graphql. Например, чтобы вернуть ID цепи и имя провайдера для каждой цепи с активным статусом, вы можете выполнить запрос, подобный следующему:

curl -H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
http://netbox/graphql/ \
--data '{"query": "query {circuit_list(filters:{status: STATUS_ACTIVE}) {cid provider {name}}}"}'

Ответ будет включать запрошенные данные в формате JSON:

{
  "data": {
    "circuits": [
      {
        "cid": "1002840283",
        "provider": {
          "name": "CenturyLink"
        }
      },
      {
        "cid": "1002840457",
        "provider": {
          "name": "CenturyLink"
        }
      }
    ]
  }
}

Примечание

Рекомендуется пропускать возвращаемые данные через парсер JSON, такой как jq, для лучшей читаемости.

InfraVision предоставляет как единичное, так и множественное поле запроса для каждого типа объекта:

$OBJECT: Возвращает один объект. Необходимо указать уникальный ID объекта как (id: 123).
$OBJECT_list: Возвращает список объектов, опционально отфильтрованный по заданным параметрам.

Например, запрос device(id:123) для получения конкретного устройства (идентифицированного по его уникальному ID), и запрос device_list (с опциональным набором фильтров) для получения всех устройств.

Для получения более подробной информации о построении GraphQL-запросов см. документацию по запросам GraphQL. Для синтаксиса фильтрации и поиска обратитесь к документации Strawberry Django.

Фильтрация

Изменено в InfraVision v4.3

Синтаксис фильтрации для GraphQL API существенно изменился в InfraVision v4.3.

Фильтры можно указать как пары ключ-значение в скобках сразу после имени запроса. Например, следующий запрос вернёт только активные площадки:

query {
  site_list(
    filters: {
      status: STATUS_ACTIVE
    }
  ) {
    name
  }
}

Фильтры можно комбинировать с логическими операторами, такими как OR и NOT. Например, следующий запрос вернёт каждую площадку, которая запланирована или назначена арендатору с именем Foo:

query {
  site_list(
    filters: {
      status: STATUS_PLANNED,
      OR: {
        tenant: {
          name: {
            exact: "Foo"
          }
        }
      }
    }
  ) {
    name
  }
}

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

query {
  device_list {
    id
    name
    interfaces(filters: {enabled: true}) {
      name
    }
  }
}

Множественные типы возврата

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

{
    cable_list {
      id
      a_terminations {
        ... on CircuitTerminationType {
          id
          class_type
        }
        ... on ConsolePortType {
          id
          class_type
        }
        ... on ConsoleServerPortType {
          id
          class_type
        }
      }
    }
}

Поле "class_type" — это простой способ различить, какой это тип объекта при просмотре возвращаемых данных или при фильтрации. Оно содержит имя класса, например "CircuitTermination" или "ConsoleServerPort".

Пагинация

Запросы могут быть пагинированы путём указания пагинации в запросе и предоставления смещения и опционально лимита в запросе. Если лимит не указан, используется значение по умолчанию 100. Запросы не пагинируются, если это не запрошено в запросе. Пример пагинированного запроса показан ниже:

query {
  device_list(pagination: { offset: 0, limit: 20 }) {
    id
  }
}

Аутентификация

GraphQL API InfraVision использует те же токены аутентификации API, что и REST API. Токены аутентификации включаются в запросы путём прикрепления HTTP-заголовка Authorization в следующей форме:

Authorization: Token $TOKEN

Отключение GraphQL API

Если GraphQL API не нужен, его можно отключить, установив параметр конфигурации GRAPHQL_ENABLED в False и перезапустив InfraVision.