Как задать параметры запроса
  • 04 Nov 2023
  • 4 Минуты для чтения
  • Авторы

Как задать параметры запроса


Article Summary

Изучите основы работы с параметрами запроса в функциях HTTP-коннектора в соответствии с документацией API.

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

Как найти параметры запроса в документации

Чтобы найти доступные параметры запроса, перейдите к документации по API. Если вы используете API Tulip Table, то документацию можно найти по адресу: your-instance.tulip.co/apiDocs. Выберите запрос, который вы хотите использовать, затем прокрутите вниз до вкладки Parameters.

Parameters in API Docs.png

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

Синтаксис параметров запроса

Синтаксис параметров запросов опирается на формат строки запроса. В этом формате заданным параметрам присваиваются значения, а сама строка запроса является частью URL.

В редакторе функций коннектора нажмите кнопку Добавить параметр, чтобы создать новый параметр запроса.

Query Parameters - Add Parameter.png

Параметр запроса состоит из двух частей: ключа и значения. Ключ - это имя параметра, а значение - информация, которая задает параметр для результатов.

В синтаксисе параметров запроса используется Dot Notation, в котором указывается точный тип параметра. Убедитесь, что регистр написания соответствует стандарту API другой системы.

Применение общих параметров к функциям коннектора

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

:::(Info) (ПРИМЕЧАНИЕ) В целях преемственности в каждом из приведенных ниже примеров мы будем использовать один и тот же запрос API Call. Это GET-запрос, который получает список записей в таблице Tulip Table через API Tulip Table. В других API, которые вы используете, параметры могут отличаться, поэтому обязательно ознакомьтесь с требованиями документации по API. :::

Limits

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

ПримерМы хотим получить не более 70 записей при выполнении функции коннектора. К счастью, значение по умолчанию для лимита в этом запросе равно 10, а максимальное - 100. Синтаксис параметра запроса должен выглядеть следующим образом:

Query Parameters - Limits.png

Фильтры

Фильтры разделяют и уточняют результаты на основе заданной информации параметра.

Фильтры состоят из трех частей, которые необходимо прописать в отдельных параметрах:

  • Field - имя столбца в таблице
  • Тип функции - тип функции сравнения
  • Аргумент - значение, с которым сравниваются результаты.

Каждый фильтр состоит из трех частей, и каждый полный фильтр представляет собой объект. Используя точечную нотацию для записи каждого ключа, укажите тип параметра ('filter'), номер фильтра (от 0 до n) и часть фильтра ('field', 'functionType' или 'arg'). Для всех трех частей фильтра должен быть свой параметр.

ПримерМы хотим сделать так, чтобы в результатах функции коннектора отображались только те значения определенного поля (eubmc_value), которые равны заданному входному значению (consumable) функции. Поскольку это наш первый фильтр в параметрах функции, номер фильтра равен 0. Это означает, что каждый ключ для этого фильтра будет начинаться с 'filter.0'. Синтаксис данного фильтра должен выглядеть следующим образом:

Query Parameters - Filters.png

Сортировка

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

Функции сортировки состоят из двух частей:

  • sortBy - поле, по которому необходимо отсортировать результаты
  • sortDir - направление сортировки, либо по возрастанию (asc), либо по убыванию (desc).

Каждая функция сортировки состоит из трех частей. Используя точечную нотацию для записи каждого ключа, укажите тип параметра ('sortOptions'), номер сортировки (от 0 до n) и аргумент сортировки ('sortBy' или 'sortDir'). Для того чтобы функция sort работала, в ней должны присутствовать параметры для всех трех частей.

ПримерМы хотим, чтобы результаты работы функции соединителя сортировались по последнему обновленному полю в порядке возрастания. Поскольку это наша первая функция сортировки, номер сортировки равен 0. Это означает, что оба ключа для этой сортировки будут начинаться с 'sortOptions.0'. Для ключа sortBy в качестве значения используется специальное значение ('_updatedAt'), полученное из документации API для сортировки по обновленным полям. Синтаксис этих параметров должен выглядеть следующим образом:

Query Parameters - Sorting.png

Offsets

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

ПримерМы хотим просматривать только записи после 5-й позиции, чтобы не видеть 5 верхних результатов. Синтаксис параметра запроса должен выглядеть следующим образом:

Query Parameters - Offset.png

Агрегаторы фильтров

Агрегаторы фильтров определяют способ объединения фильтров в параметрах. Можно выбрать два значения: 'any' и 'all'. Значение 'all' означает, что все фильтры должны иметь запись, чтобы запись была включена в результаты. Значение 'any' означает, что хотя бы один из фильтров должен соответствовать записи, чтобы она была включена в результаты. По умолчанию используется значение 'all', независимо от того, задан этот параметр или нет.

ПримерВ параметрах запроса имеется ряд фильтров, но для того, чтобы записи соответствовали нашему запросу, необходимо, чтобы только один из них был истинным. Синтаксис параметра запроса должен выглядеть следующим образом:

Query Parameter - Filter Aggregators.png

Дальнейшее чтение


Была ли эта статья полезной?