- Распечатать
Как использовать 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, чтобы задать свой вопрос или узнать, сталкивались ли другие с подобным вопросом!