Фильтрация и сортировка

Фильтрация и сортировка

Одна из общих функций, предоставляемых большинством сервисов, — это возможность возвращать список ресурсов через API. Эти ресурсы можно фильтровать и сортировать по различным критериям.

Рассмотрим примеры API реестра и документов AppEngine. Конечная точка /apps позволяет получить список всех установленных приложений, а конечная точка /documents возвращает список всех доступных документов, как показано ниже:

• Список приложений
• Список документов

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

Сортировка

Для сортировки списка можно использовать параметр запроса sort. Параметр sort требует указания одного имени поля или списка имен полей, разделенных запятыми, определяющего порядок сортировки. Порядок имен полей в списке — слева направо, то есть первое имя поля является основным критерием сортировки, за ним следует второе, а затем следующее за ним поле.

По умолчанию сортировка выполняется по возрастанию. Однако это можно изменить, добавив перед именем поля знак минус (-). В этом случае список будет отсортирован в порядке убывания на основе этого конкретного поля. Важно отметить, что сравнение строк для сортировки нечувствительно к регистру.

Посмотрите на следующий вызов API:

GET …/problems?sort=status,-startTime,relevance

API отсортирует элементы результатов сначала по status по возрастанию, затем по убыванию startTime и, наконец, по возрастанию relevance.

Фильтрация

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

Отфильтрованный результат всегда представляет собой список, независимо от количества записей. Если результат пуст, это все равно считается успешным выполнением API с кодом ответа HTTP 200 - Ok.

Формирование выражения фильтра

Для построения выражения фильтра используйте набор выражений на уровне полей в сочетании с логическими операторами. Поддерживаются следующие логические операторы: or, and и not.

Для группировки выражений также можно использовать скобки. Если скобки не используются, применяется стандартный порядок приоритета логических операторов, при этом and имеет приоритет над or.

Общая форма выражения на уровне поля выглядит так: <Fieldname> <Operator> <Value>. Давайте разберемся в них:

• <Fieldname> — это имя поля, по которому вы хотите выполнить фильтрацию.
• <Operator> — это оператор, определяющий, как должно выглядеть поле по сравнению с указанным значением.
• <Value> — это значение, с которым сравнивается поле. В зависимости от типа фильтруемого поля, значение может быть строкой, датой/временем, числом или логическим значением.

Типы данных и операторы

Ниже приведён список типов данных, поддерживаемых в выражении фильтра, а также операторы:

Тип данных	Поддерживаемые операторы	Представление
число (short, int, long, float, double)	=, !=, <, <=, >, >=, in	Целые числа: десятичная и шестнадцатеричная (с ведущим знаком 0x). Числа с плавающей запятой: научная запись с необязательным показателем степени e или E.
Строка	=, !=, contains, starts-with, ends-with, in	Только одинарные кавычки: 'Hello World!'. Специальные символы (например, кавычки) предваряются символом \. Точные операторы = и != регистр чувствительны к регистру. Неточные операторы contains, starts-with и ends-with нечувствительны к регистру.
Логический	=, !=	Сравнение с константами true или false только.
Дата/Время	=, !=, <, <=, >, >=, in	Строка, соответствующая стандарту ISO 8601, в одном из следующих форматов: yyyy-MM-ddThh:mm:ss[+/-]hh:mm (например 2007-12-03T10:15:30+01:00) yyyy-MM-ddThh:mm:ss (например 2007-12-03T10:15:30) yyyy-MM-dd (например 2007-12-03) hh:mm:ss (например 10:15:30)
Множество	contains, is-empty	contains: Сравнение с элементами, содержащимися в массиве, например, 'Hello World!' для массива строк. is-empty: Проверяет, пуст ли массив.

Оператор 'in'

Его можно использовать для сравнения на равенство внутри постоянного списка возможных значений, который предоставляется оператором in.

Предположим, name имеет тип данных строка. Вместо того чтобы писать...

name = '123' or name = '456' or name = '789'

вы можете написать

name in('123','456','789')

Оператор поддерживается для всех типов данных, кроме логических (boolean). Вы можете использовать константу списка только справа от оператора in; вы не можете использовать её как поле типа данных list. Таким образом, это выражение недействительно:

('123','456','789') contains '123'

Примеры

GET /clients?filter=age=30
GET /clients?filter=firstName='Konrad' and lastName='Zuse'
GET /documents?filter=owner='user1' and lastModified>='2022-02-06T11:00:00Z'
GET /tenants?filter=tenantUuid starts-with 'abc' and not(deleted=false or active=true)
GET /caches?filter=cacheHitRate<90.5
GET /locations?filter=distance>=1.0E4
GET /apps?filter=resourceStatus.subResourceTypes contains 'FUNCTIONS'

Фильтрация полей и частичные результаты

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

Если API поддерживает частичные результаты, он принимает параметр запроса add-fields для включения отсутствующих полей в ответ по умолчанию.

Фильтрация полей поддерживается только в API, которые отображают или получают данные о ресурсе.

Что следует помнить

• add-fields принимает список имен полей, разделенных запятыми, которые добавляются к набору полей по умолчанию.
• Повторяющиеся поля в списке приводят к ошибке.
• Добавление полей, уже имеющихся в ответе по умолчанию, считается избыточным и игнорируется.
• Обращение к неизвестным полям приводит к ошибке.
• Точка разделяет вложенные имена полей.

Пример

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

GET /entities

{

 "totalCount": 72,
 "nextPageKey": "…",
 "entities": [
   {
     "entityId": "HOST-0004DD30F142D18C"
   }
 ]

}

В следующем примере вы используете add-fields для добавления lastSeenTms и properties.bitness в дополнение к результату по умолчанию, который вы можете увидеть в приведенном ниже результате:

GET /entities?add-fields=lastSeenTms,properties.bitness

{

 "totalCount": 72,
 "nextPageKey": "…",
 "entities": [
   {
     "entityId": "HOST-0004DD30F142D18C",
     "lastSeenTms": 1615991063257,
     "properties": {
       "bitness": "64"
     }
   }
 ]

}