Как использовать API для работы с таблицами

Назначение

Настройка и использование Tulip API для взаимодействия с Tulip из других систем.

Примечание: статья для продвинутых.

Предполагается наличие опыта работы с API.

:::(Info) (ПРИМЕЧАНИЕ) Расширенная статья: Предполагает предыдущий опыт работы с API :::

Tulip взаимодействует со многими API других систем с помощью коннекторов. Использование коннекторов Приложение Tulip может инициировать HTTP- или SQL-запрос.

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

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

Добавление API

Перейдите на страницу настроек вашего аккаунта Tulip.

В меню Настройки выберите пункт Токены API.

На этой странице можно настроить "API-токены", которые представляют собой конфигурации API, содержащие ключ API, секрет и заголовок авторизации. Чтобы добавить API-токен, выберите кнопку Add API Token (Добавить API-токен) в правой верхней части этой страницы. Выбрав ее, настройте API-токен нужным образом.

Задайте имя API-токена и определите области, которые он будет иметь право выполнять. В данном примере API-токен может читать из таблиц Tulip, а также записывать в них. API-токены можно архивировать, если они не используются.

После нажатия кнопки Create (Создать) будет предоставлена информация об API. Обязательно сохраните эту информацию, так как к ней нельзя будет получить доступ повторно!

Теперь эту информацию можно использовать для настройки соединения с API Tulip.

Тестирование API

Закройте всплывающее окно информации и перейдите к кнопке API Documentation, расположенной рядом с опцией Create API Token.

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

На этой же странице находится URL-адрес сервера, необходимый для настройки запросов к API из внешних систем. Для ознакомления с API нажмите на кнопку Авторизация.

Эта кнопка позволит получить дополнительную информацию по настройке API для целей тестирования. В полях введите следующие данные:

• Имя пользователя: Ключ API
• Пароль: Секрет

Нажмите кнопку авторизации, и вы сможете приступить к тестированию некоторых распространенных HTTP-запросов к таблицам.

Каждый из параметров на этой странице может быть расширен и протестирован. Каждый запрос содержит полезную информацию о соответствующих ответах.

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

Запрос с использованием фильтров

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

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

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

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

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

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

• Ex. "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

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

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

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

Примеры

В следующих примерах рассматривается процесс выполнения запросов к API Tulip. Для выполнения запросов к Tulip в этих примерах используется Postman.

Получение имен и информации о таблицах

Этот запрос Get позволяет внешней системе получить идентификаторы и информацию о столбцах всех таблиц в экземпляре Tulip. Это может быть полезно в качестве метода поиска интересующей таблицы для настройки POST-запроса.

В Postman установите для авторизации значение Basic Auth, введите ключ и секрет API.

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

Чтобы получить URL-адрес запроса, запустите кнопку Execute и проверьте наличие Request Information.

Этот URL-адрес запроса может быть использован в качестве URL-адреса сервера для обработки GET-запроса от Postman.

Нажмите кнопку Send, и запрос вернет всю информацию из таблиц.

Создание записи в таблице

Используя POST-запрос и идентификатор таблицы, указанный выше, можно создать запись таблицы из внешней системы. Авторизация и заголовок останутся прежними, но URL-адрес запроса будет несколько иным.

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

https://.tulip.co/api/v3/tables//records.

Для корректной обработки POST-запроса потребуется тело запроса. Схема столбцов приведена выше в разделе "Тестирование", а также может быть найдена в документации по API. Единственный столбец, который полностью необходим для успешного выполнения запроса, - это столбец ID. Все остальные столбцы, которые не добавлены, будут сохранены как null в записи таблицы при ее создании. Добавьте это содержимое в тело запроса.

При отправке Postman проверяет, что запись была создана.

Вы нашли то, что искали?

Вы также можете зайти на community.tulip.co, чтобы задать свой вопрос или узнать, сталкивались ли другие с подобным вопросом!