Zapier интеграция на платформе Falcon Space

Интеграция Falcon с внешними сервисами через Zapier на примере Dropbox

Zapier - сервис, упрощающий интеграцию приложений между собой. Zapier позволяет пользователям создавать zap’ы - цепочки, описывающие передачу данных между приложениями. Каждый zap начинается с триггера, за которым следует одно или несколько действий. Триггерами могут быть любые события в приложении - новое письмо или сообщение, появление нового файла, создание нового заказа и т.п. Данные о событии передаются от триггера одного приложения к действию другого приложения. Например, появление новой строки в таблице Google Sheets приводит к появлению нового сообщения в чате.

Далее рассмотрим, как зарегистрировать своё приложение на Zapier, чтобы его можно было использовать в zap’ах в качестве триггера или действия. 

Подготовка сайта к интеграции

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

CREATE PROCEDURE [dbo].[api_order_zapTrigger] --zapTrigger - код запроса
@parameters DictionaryParameter READONLY,
@username nvarchar(256)
as
begin

    -- SELECT 1 - вывод метаданных о результате операции метода API
    select '' Msg, 1 Result, 0 errorCode    

    -- SELECT 2 - вывод самих данных в API
    select top 5 id, customerName from ord_orders order by id desc

end

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

Также подготовим входящий api запрос для создания действия:

CREATE PROCEDURE [dbo].[api_order_zapAction]
@parameters DictionaryParameter READONLY,
@username nvarchar(256)
as
begin
  
    declare @temp table ([Key] nvarchar(500), [Value] nvarchar(500))
    insert into @temp
    select [Key], [Value]
    from @parameters

    
    while ((select count(*) from @temp) > 0) begin
        declare @key nvarchar(500), @value nvarchar(500)
        select top 1 @key = [Key], @value = [Value] from @temp
        delete top (1) @temp
       
        declare @str nvarchar(2048) = 'Zapier action: ' + @key + ' - ' + @value
       
        exec as_print @str=@str

    end

    select '' Msg, 1 Result, 0 errorCode

    select 0

end

Данное действие будет выводить все данные входящего запроса в логе на панели управления Falcon с префиксом “Zapier action:“.

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

На этом подготовка к созданию приложения на стороне Falcon завершена, дальше создаем и настраиваем приложение на Zapier.

Настройка приложения Zapier

Приложение можно создать на странице для разработчиков: https://zapier.com/app/developer

Вам будет предложено заполнить форму для регистрации приложения. Для примера назовем наше приложение FalconTest. Обратите внимание на поле Intended Audience: private для личного использования, или public, если в итоге после публикации интеграция будет доступна всем пользователям Zapier.

Настройка авторизации

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

Настройка авторизации состоит из трех шагов.

1) Указываем данные, которые нужны для авторизации. Их нужно будет вводить при подключении приложения к zap. Добавляем поля username и password.

2) Настраиваем запрос для авторизации. По этому запросу будем получать токен для авторизации в обмен на логин и пароль. Указываем страницу /api/auth на Falcon.

Наши поля username и password доступны в переменных вида bundle.authData.username и bundle.authData.password, которые указываются в двойных фигурных скобках в редакторе запроса, либо без скобок в режиме кода (включается по кнопке “Switch to Code Mode”), где предлагается использовать JavaScript. Данный способ использования данных используется на Zapier везде, поэтому стоит обратить внимание.

3) На данном этапе нужно указать адрес реального метода api и проверить, что метод работает после авторизации. Укажем метод api, который мы создали ранее для триггера.

В URL Params указываем наш токен, доступный в переменной bundle.authData.token.

Название “token” в составе переменной используется в данном случае именно потому, что в ответе запроса на авторизацию Falcon токен возвращается в поле “token”.

4) На последнем шаге нажимаем Test Authentication, чтобы авторизоваться и проверить вызов api. Откроется окно, где нужно авторизоваться, используя одного из пользователей api из настроек в управлении api на Falcon. Если всё верно, на вкладке Response получим верный ответ api, после чего можно будет создавать триггеры и действия.

Добавление триггера

Так как триггером в нашем случае является создание нового заказа, создаем триггер с ключом (Key) new_order и названием (Name) New Order

Настройка триггера состоит из трех частей.

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

На вкладке Input Designer предлагается добавить параметры для триггера, которые можно использовать в качестве параметров при запросе к нашему api. Их нужно будет заполнять при создании zap. Указанные здесь параметры будут доступны при настройке запроса в виде переменных вида bundle.inputData.param_key, где param_key - ключ параметра, подобно тому, как был доступен токен при настройке авторизации. В данном случае у нас нет параметров для триггера, но мы еще вернемся к ним при создании действия.

На вкладке API Configuration настраивается работа с нашим api. Процесс включает три шага.

На первом шаге нужно настроить запрос к api.

Во-первых, нужно указать тип триггера. Нам доступен только тип Polling, который означает, что Zapier должен сам периодически опрашивать наш api в поисках обновлений, в то время как при использовании REST Hook запросы делаются только по необходимости и сервер должен сам оповещать Zapier об обновлениях.

Во-вторых, при настройке триггера нам придется переключиться в режим кода (Switch to Code Mode). Связано это с тем, что триггер должен получить на вход массив объектов, а наш api помимо этого возвращает еще и статус запроса. Чтобы из всего результата извлечь только массив данных, нужен JavaScript.

Код, описывающий наш запрос, будет выглядеть так:

const options = {
    url: 'https://polygon2.web-automation.ru/api/action/zapTrigger',
    method: 'GET',
    headers: {
        'Accept': 'application/json'
    },
    params: {
        'token': bundle.authData.token
    }
}



return z.request(options)
    .then((response) => {
        response.throwForStatus();
        const results = z.JSON.parse(response.content);

        return results.data;
    });

Почти весь код здесь совпадает с тем, что был вставлен в окно редактора по умолчанию. Обращаем внимание, что в параметрах указан токен, иначе не пройдет авторизация, и что в строке с return мы возвращаем именно results.data. Это и есть тот самый массив объектов, который триггер должен получить на вход.

На втором шаге api нужно протестировать запрос. При этом нужно будет авторизоваться, используя логин и пароль пользователя api в нашей системе. Авторизация может быть пропущена, если мы уже вводили логин и пароль при настройке авторизации выше. При успешном тестировании запроса получим верный ответ нашего api на вкладке Response.

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

Создание действия

Процесс создания действия во многом повторяет процесс создания триггера.

Есть те же разделы Settings, Input Designer и API Configuration.

Для примера мы создадим действие “Создать заказ” (Create Order), хотя на самом деле процедура для нашего действия не делает ничего, кроме вывода данных в лог.

Раздел Input Designer на этот раз используется не для создания формы с параметрами, а для того, чтобы описать, какие данные наше действие будет принимать на вход от других приложений. Добавим поля Username и Product типа Input Field:

При настройке API в этот раз используем POST запрос:

const options = {
    url: 'https://polygon2.web-automation.ru/api/action/zapAction',
    method: 'POST',
    headers: {
        'content-type': 'application/x-www-form-urlencoded'
    },

    params: {
        'token': bundle.authData.token
    },
    body: {
        'orderProduct': bundle.inputData.product,
        'orderUsername': bundle.inputData.username
    }
}

return z.request(options)
    .then((response) => {
        response.throwForStatus();
        const results = z.JSON.parse(response.content);
        return results;

    });

Параметры POST запроса указываются в разделе body. Наши данные из Input Designer доступны через переменные bundle.inputData.product и bundle.inputData.username. Обратите внимание на заголовок ‘content-type’, без него параметры из body не будут доступны. В строке с return в данном случае возвращаем просто results, потому что для действий нужно возвращать объект.

После настройки запроса его можно протестировать, как и в случае с триггером.

Тестирование интеграции на примере Dropbox

После создания приложения мы можем интегрировать его с другими доступными в Zapier приложениями. Для примера настроим интеграцию, которая будет создавать новые файлы в Dropbox при создании заказа, и интеграцию, которая будет при создании файла в Dropbox выводить его имя и содержимое в логе панели управления.

Чтобы создать новую интеграцию, нажмите “MAKE A ZAP” в личном кабинете (открывается сразу при открытии https://zapier.com после авторизации).

Использование нашего приложения в качестве триггера

Первым делом при создании нового zap нужно выбрать триггер. Выбираем наше приложение.

Выбираем наш триггер

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

На следующем шаге можно протестировать получение данных от триггера:

Если с данными всё в порядке, нажимаем “Done editing”, переходим ко второму приложению и выбираем Dropbox. Можно воспользоваться поиском, чтобы его найти.

В качестве действия выбираем Create Text File.

Далее авторизуемся в Dropbox и заполняем входные данные для действия создания текстового файла: директорию, имя файла (ID заказа) и содержимое файла (имя пользователя). Система сама подсказывает данные при заполнении.

При тестировании на следующем этапе в нашем Dropbox уже появится текстовый файл с данными из последнего заказа. Если тест прошел успешно, включаем zap и создаем новые заказы, чтобы протестировать работу.

Использование нашего приложения в качестве действия

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

В качестве триггера Dropbox выбираем New File in Folder

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

Перед проверкой убедитесь, что у вас в Dropbox есть такая директория и там есть файлы.

Тест триггера покажет различные данные о файле.

Вторым элементом zap выбираем наше приложение и действие Create order

В качестве наших username и product указываем содержимое файла (file text) и имя файла.

При тестировании действия получим в составе лога на нашем сайте список данных запроса к api, в составе которых должны быть поля orderUsername и orderProduct:

После включения интеграции и создания файлов в Dropbox в логе начнут выводиться новые записи.