Создание коннектора webservice

Пример создание собственного коннектора вебсервиса

В качестве примера мы создадим простой коннектор вебсервис для получения сообщений от VIber. Данный коннектор будет автоматически подписываться на обновления Viber и передавать данные полученного сообщения следующим коннекторам.

Для начала создайте новый процесс для отладки нашего будующего коннектора

После этого откройте Библиотеку коннекторов нажав на ссылку Add connector в правом углу редактора процесса. После этого откроется библиотека доступных коннекторов.

Библиотека коннекторов

Далле выберите пункт Upload connector в правом верхнем углу для загрузки нового коннектора, после нажатия которого откроется редактор нового коннектора

Редактор нового коннектора

В редакторе коннектора доступны следующие основные секции:

• General - общая информация о коннекторе, такая, как: название, описание, тип, версия и подробная информация. В этой секции также можно загрузить изображение для нашего коннектора.

• Schema - раздел, где необходимо описать все методы нашего коннектора, а также входные и исходящие схемы данных для каждого метода.

• Code - раздел где редактируется основной код бизнес-логики коннектора.

• Install handler - раздел где задается обработчик коннектора, который будет выполнен при инициализации коннектора в процессе.

• NPM modules - раздел, где добавляются NPM модули коннектора, которые будут необходимы для его работы.

Шаг 1. Заполнение общей информации о коннекторе

На вкладке General заполните название, описание, версию создаваемого коннектора, а также загрузите картинку.

Так как мы создаем коннектор вебсервис, который будет принимать запросы от Viber, то параметр Type должен быть со значением Webservice.

Шаг 2. Описание методов и схемы коннектора

Вкладка Schema имеет 3 основных поля для описания схем данных коннектора

• Methods - методы коннектора

• Input schema - описание входной схемы данных в зависимости от метода

• Output schema - описание исходящей схемы данных в зависимости от метода

Описание методов коннектора

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

Methods

[
    {
        "title": "Default",
        "value": "viber_default_method",
        "http_methods": ["POST", "GET"]
    }
]

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

Описание схемы для входных данных

Коннекторы вебсервисы не имеют коннекторов перед собой и запускаются только если поступил соответствующий HTTP запрос. Поэтому схема входных данных может содержать только те данные, которые пользователь может заполнить в настройках коннектора с помощью UI компонентов.

Для работы с Viber нам необходимо предоставить пользователю возможность заполнить в настройках коннектора следующие параметры:

• Токен (X-Viber-Auth-Token)

• Endpoint (action) - параметр, формирующий полный URL нашего вебхука

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

Input Schema

{
  "viber_default_method": {
    "type": "object",
    "properties": {
      "X-Viber-Auth-Token": {
        "type": "string",
        "required": false,
        "presenter": {
          "title": "Viber auth token",
          "desc": "X-Viber-Auth-Token, ypu can get it on partners.viber.com. Just create a bot",
          "component": "string",
          "order": 0
        }
      },
      "action": {
        "type": "string",
        "required": true,
        "min": 4,
        "presenter": {
          "title": "Endpoint",
          "component": "string",
          "order": 0
        }
      }
    }
  }
}

Описание схемы для исходящих данных

Предварительно ознакомившись с API Viber мы знаем, что будет получать следующий формат данных:

Viber

{
   "event":"message",
   "timestamp":1457764197627,
   "message_token":4912661846655238145,
   "sender":{
      "id":"01234567890A=",
      "name":"John McClane",
      "avatar":"http://avatar.example.com",
      "country":"UK",
      "language":"en",
      "api_version":1
   },
   "message":{
      "type":"text",
      "text":"a message to the service",
      "media":"http://example.com",
      "location":{
         "lat":50.76891,
         "lon":6.11499
      },
      "tracking_data":"tracking data"
   }
}

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

{
    "result": {
        "id": "01234567890A=",
        "name": "John McClane",
        "avatar": "http://avatar.example.com",
        "text": "a message to the service"
    }
}

С учетом оптимизированной схемы, опишем схему исходящих данных для нашего коннектора

Output schema

{
    "viber_default_method": {
        "type": "object",
        "properties": {
            "result": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "avatar": {
                        "type": "string"    
                    },
                    "text": {
                        "type": "string"
                    }                
                }
            }
        }
    }
}

Шаг 3. Основной код коннектора

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

const https = require('https');

if (ctx.connector.method !== "viber_default_method") {
    console.error("Unknown connector method", ctx.connector.method);
    ctx.reject(false);
    ctx.response.json({error: false});
    return Promise.resolve();
}

// Функция для парсинга тела запроса от Viber
const parseContent = (request) => {
    return new Promise((resolve, reject) => {
        var body = '';
        request.on('data', (data) => {
            body += data;
        });
        request.on('end', () => {
            let data;
            try {
                data = JSON.parse(body);
            } catch (err) {
                console.error(err);
                return reject('Bad request');
            }
            resolve(data);
        });
    });
};

return (async () => {
    var body = {};
    try {
        if (ctx.request.method == 'POST') {
            body = await parseContent(ctx.request);
        }
    } catch (err) {
        ctx.reject(false);
        return Promise.resolve();
    }
    
    // Передаем данные в контекст с учетом описанной нами схемы
    ctx.setData({
        result: {
            id: body.sender.id,
            name: body.sender.name,
            avatar: body.sender.avatar || '',
            text: body.message.text
        }
    });
    ctx.response.json({error: false});
    return Promise.resolve();
})();

Шаг 4. Установка предобработчика installHandler

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

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

InstallHandler

const https = require('https');
return (async () => {
  const { connector, workplace, processID } = ctx;
  const opts = {
    host: 'chatapi.viber.com',
    port: 443,
    path: '/pa/set_webhook',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Viber-Auth-Token': connector.params['X-Viber-Auth-Token']
    }
  }

  const requestData = JSON.stringify({
    url: `https://api.mixapp.io/webhooks/${workplace}/${processID}/${connector.params.action}`,
    event_types: ["receive_message_from_user"],
    send_name: true,
    send_photo: true
  });
  
  return new Promise((resolve, reject) => {
    const req = https.request(opts, resolve);
    req.on('error', reject);
    req.write(requestData);
    req.end();
  }).catch(err => console.error);
})();

Шаг 5. Сохраняем коннектор и тестируем

После того, как мы описали весь функционал нового коннектора, необходимо его сохранить, после чего он появится в Библиотеке коннектов и можно приступать к его тестированию.

Для тестирования мы добавим в процесс наш новый коннектор и коннектор Expression, в котором напишем вывод поступающих через контекст данных от нашего коннектора к Viber с помощью кода: console.log(ctx.data.data);

Отладочный процесс

В настройках коннектора к Viber заполним Endpoint и токен

Настройки коннектора Viber

После чего запустим процесс и отправим сообщение через Viber нашему пользователю. В свою очередь Viber это сообщение отправит на наш созданный вебсервис и в консоле процесса мы сможем увидеть информацию о нем: