Фильтрация REST API

Фильтрация объектов

Объекты, возвращаемые конечной точкой списка API, могут быть отфильтрованы путём добавления одного или нескольких параметров запроса к URL. Например, GET /api/dcim/sites/?status=active вернёт только площадки со статусом "active".

Несколько параметров можно объединить для дальнейшего сужения результатов. Например, GET /api/dcim/sites/?status=active&region=europe вернёт только активные площадки в регионе Европа.

Как правило, передача нескольких значений для одного параметра приведёт к логической операции ИЛИ. Например, GET /api/dcim/sites/?region=north-america&region=south-america вернёт площадки в Северной Америке или Южной Америке. Однако логическая операция И будет использоваться в случаях, когда поле может иметь несколько значений, например теги. Например, GET /api/dcim/sites/?tag=foo&tag=bar вернёт только площадки, к которым применены оба тега "foo" и "bar".

Фильтрация по полю выбора

Некоторые модели имеют поля, ограниченные определёнными вариантами выбора, например поле status в модели Prefix. Чтобы найти все доступные варианты для этого поля, выполните аутентифицированный запрос OPTIONS к конечной точке списка модели и используйте jq для извлечения соответствующих параметров:

$ curl -s -X OPTIONS \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/ipam/prefixes/ | jq ".actions.POST.status.choices"
[
  {
    "value": "container",
    "display_name": "Container"
  },
  {
    "value": "active",
    "display_name": "Active"
  },
  {
    "value": "reserved",
    "display_name": "Reserved"
  },
  {
    "value": "deprecated",
    "display_name": "Deprecated"
  }
]

Примечание

Вышеуказанное работает только если токен API, используемый для аутентификации запроса, имеет разрешение на выполнение запроса POST к этой конечной точке.

Фильтрация по пользовательскому полю

Для фильтрации результатов по значению пользовательского поля добавьте префикс cf_ к имени пользовательского поля. Например, следующий запрос вернёт только площадки, где пользовательское поле с именем foo равно 123:

GET /api/dcim/sites/?cf_foo=123

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

Выражения поиска

Определённые поля модели также поддерживают фильтрацию с использованием дополнительных выражений поиска. Это позволяет выполнять отрицание и другую контекстно-зависимую фильтрацию.

Эти выражения поиска можно применить, добавив суффикс к имени нужного поля, например mac_address__n. В этом случае выражение фильтра предназначено для отрицания и отделяется двумя символами подчёркивания. Ниже приведены выражения поиска, поддерживаемые для разных типов полей.

Числовые поля

Числовые поля (ASN, VLAN ID и т.д.) поддерживают следующие выражения поиска:

Фильтр	Описание
`n`	Не равно
`lt`	Меньше чем
`lte`	Меньше или равно
`gt`	Больше чем
`gte`	Больше или равно
`empty`	Пусто/null (булево)

Вот пример выражения поиска для числового поля, который вернёт все VLAN с VLAN ID больше 900:

GET /api/ipam/vlans/?vid__gt=900

Строковые поля

Строковые (char) поля (Name, Address и т.д.) поддерживают следующие выражения поиска:

Фильтр	Описание
`n`	Не равно
`ic`	Содержит (без учёта регистра)
`nic`	Не содержит (без учёта регистра)
`isw`	Начинается с (без учёта регистра)
`nisw`	Не начинается с (без учёта регистра)
`iew`	Заканчивается на (без учёта регистра)
`niew`	Не заканчивается на (без учёта регистра)
`ie`	Точное совпадение (без учёта регистра)
`nie`	Обратное точное совпадение (без учёта регистра)
`empty`	Пусто/null (булево)
`regex`	Сопоставление регулярным выражением
`iregex`	Сопоставление регулярным выражением (без учёта регистра)

Вот пример выражения поиска для строкового поля, который вернёт все устройства со словом switch в имени:

GET /api/dcim/devices/?name__ic=switch

Внешние ключи и другие поля

Некоторые другие поля, а именно связи внешних ключей, поддерживают только выражение отрицания: n. Вот пример выражения поиска для внешнего ключа, который вернёт все VLAN, у которых ID группы VLAN не равен 3203:

GET /api/ipam/vlans/?group_id__n=3203

Сортировка объектов

Для сортировки результатов по определённому полю включите параметр запроса ordering. Например, отсортировать список площадок по значениям объекта:

GET /api/dcim/sites/?ordering=facility

Чтобы инвертировать сортировку, добавьте дефис перед именем поля:

GET /api/dcim/sites/?ordering=-facility

Можно указать несколько полей, разделив имена полей запятой. Например:

GET /api/dcim/sites/?ordering=facility,-name