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

Изучите основы работы с параметрами запроса в ваших функциях HTTP Connector в соответствии с документацией 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. Выберите запрос, который вы хотите использовать, затем прокрутите вниз до вкладки Parameters.

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

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

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

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

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

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

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

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

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

Лимиты

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

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

Фильтры

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

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

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

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

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

Сортировка

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

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

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

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

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

Offsets

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

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

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

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

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

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

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

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

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

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