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

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

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

Запрос с помощью фильтров

Фильтры могут быть очень полезны для извлечения только тех данных, которые вас интересуют. Иногда синтаксис этих фильтров может быть немного запутанным. Ниже описано, как формируется каждый из них на примере GET-запроса на получение записей, а затем приведен полный пример.

Имена полей для пользовательских полей всегда имеют префикс в виде пятизначного строкового идентификатора. Их легче всего найти после запроса GET all, чтобы проверить истинное имя поля.

• Например. "field"="maytq_scrap_count".

Значенияаргументов часто просты. Если это текстовое значение, обязательно заключите его в кавычки.

• Например. "arg":15

Подберите тип функции, которую вы хотите использовать.

• Например. "functionType": "greaterThan".

Полный запрос для этого может выглядеть примерно так:

https://brian.tulip.co/api/v3/tables/W2HPvyCZrjMMHTiip/records?limit=100&sortBy=\_sequenceNumber&sortDir=asc&filters=[{"field": "maytq\_scrap\_count", "arg":15, "functionType": "greaterThan"}]&filterAggregator=any

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

Чтобы найти доступные параметры запроса, перейдите к документации API. Если вы используете API Tulip Table, вы можете найти документацию по адресу: your-instance.tulip.co/apiDocs.Select the request you want to use then scroll down to the Parameters tab.

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

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

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

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

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

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

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

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

Limits

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

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

{height="" width=""}.

Фильтры

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

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

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

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

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

{height="" width=""}.

Сортировка

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

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

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

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

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

{height="" width=""}.

Смещения

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

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

{height="" width=""}.

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

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

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

{height="" width=""}.

Несколько фильтров

В некоторых случаях в таблице необходимо проверить несколько фильтров. В этом случае вы можете добавить несколько фильтров в объект filters. Это может выглядеть следующим образом:

filters=[{"field": "maytq\_scrap\_count", "arg":15, "functionType": "greaterThan"},{"field": "maytq\_scrap\_reason", "arg": "scratch", "functionType": "equal"}].

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

• Обзор HTTP-коннекторов
• Как создать и настроить функцию HTTP-коннектора
• Как использовать API для работы с таблицами