Как создать и настроить функцию HTTP-коннектора

Узнайте, как работать с модальной панелью Connector Function и процессом ее создания.

Обзор

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

Для получения информации об основах API ознакомьтесь со статьей Как использовать API.

Настройка

Перед созданием функции-коннектора необходимо создать HTTP-коннектор для установления соединения между приложениями и сервисом, с которым необходимо взаимодействовать. В рамках этого коннектора вы будете создавать свои функции коннектора, и каждая функция коннектора в рамках коннектора будет использовать конфигурацию родительского коннектора. Чтобы создать HTTP-коннектор, выполните действия, описанные в этой статье: Как настроить коннектор.

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

Создание функции коннектора

На странице Connectors выберите коннектор, с которым вы хотите работать, щелкнув на его названии.

На этой странице отображается список функций, связанных с этим коннектором. Чтобы создать новую функцию коннектора, нажмите + Создать функцию.

Прежде чем создавать новую функцию, полезно ознакомиться с редактором функций коннектора, который рассмотрен в этой статье: .:::(Internal) (Личные заметки) вставить сюда обзорную статью по функциям коннекторов :::

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

Вот как мы будем настраивать функцию коннектора:

1. Выберите тип API Call.
2. Напишите URL-адрес API
3. Задайте входные данные
4. Определить параметры возвращаемых данных
5. Задайте выходные данные, используя точечную нотацию

Тип вызова и URL

Первые два элемента, которые необходимо настроить для любой функции HTTP-коннектора, - это тип вызова API (GET, POST, PUT и т.д.) и URL конечной точки. Выберите тип вызова из списка с помощью выпадающего списка и введите путь к конечной точке в поле, следующее за базовым URL. Для получения подробной информации о конечных точках и их конфигурации обратитесь к документации по API того сервиса, к которому вы хотите подключиться.

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

В этой статье мы будем использовать в качестве примера API Document360 - сервис, на котором размещена база знаний Tulip. Функция, которую мы настраиваем, возвращает статью вместе со связанными с ней свойствами на основе идентификатора статьи.

Назовем нашу функцию, установим тип вызова (GET) и введем URL для вызова:

:::(Info) (ПРИМЕЧАНИЕ) URL-адрес вызова чувствителен к регистру. Убедитесь, что вы вводите его именно так, как он указан в документации по API:

Получите тип вызова и URL из документации по конечным точкам вашей системы. Эти два действия определяют ваш REST-запрос. Подробное описание того, что представляет собой REST-запрос, приведено в разделе Анатомия REST-запроса.

Щелчок на кнопке Test запускает функцию и выводит информацию в разделе Test Results редактора. Выбрав пункт Body в разделе Test Results, вы можете просмотреть полный, нефильтрованный результат запроса. Отлично, у нас есть данные!

{{glossary.Input}

В текущей конфигурации нашей функции коннектора мы можем получить только один конкретный идентификатор статьи.

Наша цель - настроить эту функцию таким образом, чтобы она возвращала информацию о любой интересующей нас статье. Для этого нам необходимо изменить нашу функцию таким образом, чтобы она могла передавать значение для любого ID статьи.

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

Настройка входов состоит из двух частей: 1.) создание входа на панели ввода; 2.) указание места, где этот вход будет использоваться в функции коннектора.

Сначала добавьте поле на панель ввода. Тип данных входа можно изменить, нажав на значок рядом с названием входа. Убедитесь, что выбранный тип соответствует типу источника, который будет использоваться в приложении. Поле рядом с именем input может использоваться для тестирования значений, которые вы хотите передать в функцию коннектора, и имитировать входные данные из ваших приложений.

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

В нашем примере мы можем получить доступ к конкретной статье, указав ее в конце пути к конечной точке или вместо "{articleId}".

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

Мы добавляем входные данные в путь к конечной точке, ставя знак доллара**($**) перед и после параметра (в данном случае "ID"). Строка между знаками доллара чувствительна к регистру и должна точно совпадать с именем входного параметра. Если мы вернемся к нашему примеру, то изменим URL так, чтобы ID совпадал с вводимым параметром. Текст между знаками доллара превратится в блок, обозначающий свойство, как показано ниже:

Теперь мы можем задавать ID в качестве входных значений, а не вводить их непосредственно в URL конечной точки.

Для добавления дополнительных входных данных нажмите на кнопку + в правом верхнем углу поля ввода.

Параметры

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

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

В парах "ключ-значение" один из компонентов является "ключом", а другой - "значением"; оба они добавляются в конец URL-адреса ссылки вашей формы. Их можно сравнить с маркерами в электронном письме для персонализации имени человека. Использование пар "ключ-значение" позволяет передавать информацию в форму.

Ключ указывает на имя переменной.

Значение указывает на значение свойства.

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

Эти параметры запроса и запроса являются необязательными для заполнения полями, но они придают конкретность результатам тестирования, если это необходимо.

Outputs

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

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

Чтобы проверить правильность отображения выходов, перейдите на вкладку Выходы в панели Результаты тестирования и обратите внимание на возвращаемые результаты.

Если выходы совпадают с результатами, то поздравляем! Вы успешно создали рабочую функцию коннектора и можете использовать ее в приложениях. Дальнейшие действия описаны в разделе Использование HTTP-коннекторов в приложениях.

Если у вас возникли проблемы, связанные с некорректной работой функции коннектора, обратитесь к нашему Руководству по устранению неполадок, чтобы узнать, что может быть не так.

Пройдите курс HTTP Connectors University, чтобы получить подробную информацию о создании коннекторов.

Дополнительное чтение

• Обзор HTTP-коннекторов
• Как форматировать выходные данные HTTP-коннекторов

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

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