Новые возможности: Custom API request | Упрощаем настройку HTTP-запросов

Новый функционал в Albato – “Custom API request” позволяет вам создавать и настраивать запросы в API самостоятельно, независимо от метода, который вы хотите использовать.

Простыми словами, теперь вы можете выполнить запрос к API любого приложения в Albato, даже если требуемого действия нет в списке стандартных возможностей. Это особенно удобно, если вам нужно использовать редкие методы или если какое-то действие не доступно в Albato, но есть в API приложения. Это позволяет упростить настройку HTTP запроса, так как вам не нужно беспокоиться о настройке авторизации или обработке ошибок.

Зачем это нужно?

Допустим, в Albato есть публичное приложение, такое как HubSpot, но вам нужно выполнить какое-то действие, которого нет в стандартном наборе возможностей. Вместо того чтобы ждать, пока Albato добавит это действие, вы можете использовать “Custom API request”.

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

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

Правила работы:

Действие позволяет выполнять запросы только к разрешенным URL-адресам – обычно это URL-адреса самого приложения, то есть его API. Если у приложения используется собственный кастомный домен, это также учитывается. Например, если вы используете действие для приложения “HubSpot”, запросы можно отправлять только на URL-адреса, начинающиеся с https://api.hubapi.com/. Путь после этого URL может быть любым. Важно отметить, что список разрешенных доменов будет указан в подсказке к соответствующему полю. Любые другие URL-адреса будут недоступны, и действие выдаст ошибку, если вы попытаетесь выполнить запрос в работающей связке. URL при этом нужно указывать полностью

Настройка действия

Для начала добавляем действие в связку. Для этого, добавляем в связку действие, выбираем интересующее нас приложение. При наличии такого действия (доступно не у всех приложений), его можно увидеть внизу, в списке действий (”Custom API request”)

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

Это открывает окно настройки данного действия.

Давайте разберем, какое поле за что отвечает :

• URL: Здесь указывается полный URL, на который должен быть выполнен запрос. Допускаются только разрешенные домены, которые указаны в подсказке к полю.
• Метод запроса: Выбирается метод, который будет использоваться при вызове запроса (например, GET, POST, PUT).
• Формат запроса: Определяется формат тела запроса (Content-type). Тело запроса формируется автоматически Albato на основе маппинга в разделе “Параметры запроса”.
• Параметры запроса: Подраздел, с множеством возможных полей. Здесь создаются необходимые поля для передачи в запросе: указывается их ключ, тип и значение.
• Заголовки запроса: Аналогично параметрам запроса, но для настройки заголовков. Необходимо помнить, что Content-type и авторизация будут установлены автоматически.
• Параметры ответа: Здесь настраиваются поля ответа, указывается маппинг (ключ) откуда нужно забирать значения. Они могут использоваться в последующих шагах для обработки ответа от запроса.

Далее в зависимости от вашего кейса, необходимо настроить все поля.

Давайте рассмотрим настройку на примере. Предположим, нам нужно создать звонок в HubSpot, используя их API документацию https://developers.hubspot.com/docs/api/crm/calls

Пример исходного запроса:

• URL: https://api.hubapi.com/crm/v3/objects/calls
• Метод: POST
• Формат: JSON

Тело запроса:

Мы начинаем настраивать наше действие.

Затем создаем необходимые поля для передачи в запросе. Для этого нажмите на кнопку “+” в разделе. После этого приступаем к настройке маппинга ключей для правильной передачи данных.

Маппинг ключей

? Далее разберём сначала, как правильно прописывать маппинг ключей, то есть общее правило, без нашего примера.

Если нужно заполнить переменную name и JSON выглядит так:

Ключ указывается name .

Если нужная переменная находится в объекте и нужно её заполнить, то путь к объекту указывается через точку. Пример JSON:

Теперь, чтобы заполнить переменную name, необходимо указать маппинг ключа в левом поле в таком виде: contact.namе.

Если переменная находится в массиве объектов, и при этом необходимо заполнить конкретный объект, то маппинг указывается через точку, но с указанием позиции объекта в массиве (исчисление начинается с нуля). Пример JSON:

В данном случае, если необходимо заполнить поле name в первом объекте, маппинг указывается как contаcts.0.namе. Если нужно заполнить второй объект, маппинг будет contаcts.1.namе.

Теперь вернемся к нашему примеру

Допустим, нам нужно задать значение параметра associationCategory как HUBSPOT_DEFINED, которое является строкой. Для этого создаем поле и указываем маппинг как associations.0.types.0.associationCategory, выбираем тип String и указываем значение.

Аналогично делаем для associationTypeId, только теперь у нас целое число.

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

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

Такая настройка сформирует JSON, аналогичный примеру из HubSpot. Если у вас есть другие ключи, вы также сможете их изменить.

Кроме того, мы можем настроить получение ответа сразу. Согласно документации, на этот запрос приходит JSON-ответ.

Прописываем нужный нам ключ и выбираем тип. В данном случае это просто id

Правило написания ключей здесь полностью аналогично параметрам запроса.

Настройка действия завершена! Теперь мы можем запускать связку и вызывать наш запрос.

Типизация полей параметров

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

• String: Строка.
• Int: Целое число.
• Decimal: Дробное число.
• Boolean: Отправляется true/false.
• DateTime: Тип даты и времени. При выборе этого типа следует указать формат и таймзону отправляемой даты.
• Date: То же самое, что и DateTime, но без времени.
• Phone: Еще один внутренний тип. При выборе данного типа, в шестерёнке добавляются поля с форматом и окончательным типом переменной (int или string). Данный сценарий полезен, когда в API поле с телефоном необходимо передавать строгий формат (прим. +{{countryCode}}########## , выбрав такую маску в настройках, даже если в поле попадёт телефон в формате +7(968)111-22-33 то Albato автоматически его конвертирует в нужный формат для API
• ObjectArray: Массив объектов, использует ‘Строковую секцию’.

Если выбран тип Date, DateTime или Phone, то у поля появляется дополнительная настройка формата.

Их настраивать обязательно. В случае, если это дата (с временем или без), в шестерёнке настраивается формат, в котором будет передана сама дата.

Если выбирается “Строка”, то нужно прописать формат даты по правилам PHP, доступным по ссылке: https://www.php.net/manual/ru/datetime.format.php, а также указать таймзону.

Если выбирается “Число”, тогда можно выбрать Unixtime (количество секунд с 1 января 1970 года) или millisecond (то же самое, только в миллисекундах). Albato автоматически конвертирует дату в нужный для API формат. При этом не важно, в каком формате дата попала в это поле, главное, чтобы это был изначально валидный формат даты.

Если выбирается тип “Телефон”, тогда указывается маска, по которой всегда будет формироваться номер телефона.

Помимо этого, если нам нужно динамически отправить массив объектов, то есть что-то вроде:

Здесь у нас “products” — это массив объектов, то есть набор товаров в заказе. Если предыдущий шаг отдаёт “Строковую секцию” и вы также хотите динамически передать массив, в зависимости от количества элементов, полученных от предыдущего шага, то для поля нужно установить тип “Object Array”.

Сначала мы указываем ключ самого массива, а затем поля этого массива.

Следуя примеру выше, мы настраиваем поля таким образом:

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

Настройка этого типа в параметрах ответа, как и всех остальных, происходит полностью по аналогичному сценарию.