Для авторов микросервисов

В Tomoru существует такое понятие, как "микросервис". Микросервис — это сторонний сервис, который работает отдельно от Tomoru и выполняет какую-то специфичную для него работу.

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

Взаимодействие с микросервисами осуществляется при помощи вызова методов микросервиса и получения от микросервиса команд.

Создание REST API для микросервиса

Микросервис представляет из себя обычный HTTP-сервис. Tomoru не накладывает жестких ограничений на структуру HTTP-сервиса, формат запросов к нему и ответов от него. Робот Tomoru подстроится под HTTP-сервис и будет вызывать его методы согласно описанию OpenAPI микросервиса.

Например, микросервис может выглядеть как большой HTTP-сервис, который будет среди множеств других методов три следующие метода REST API:

Ищет клиента по имени

GET /client/find?name=:name HTTP/1.1

RESPONSE 200 (application/json)
# Клиен найден

{
  // Уникальный идентификатор клиента
  "id": 1,
  // Имя клиента
  "name": "Ivan Ivanov",
  // Адресс клиента
  "address": "Moskov, Kremlin",
  // Телефон клиента
  "phone": "+79999999999"
}

RESPONSE 404
# Клиент не найден

Изменяет данные клиента

POST /client/:id/update HTTP/1.1

{
  // Имя клиента
  "name": "Ivan Ivanov",
  // Адресс клиента
  "address": "Moskov, Kremlin",
  // Телефон клиента
  "phone": "+79999999999"
}

RESPONSE 200
# Данные изменены

RESPONSE 403
# Данные для клиент менять запрещено

RESPONSE 404
# Клиент не найден

Создать заказ для клиента

POST /order/create HTTP/1.1

{
  // ID Клиента
  "client_id": 1,
  // Описание заказа
  "order_description": "Ботинки и футболка"
}

RESPONSE 200 (application/json)
# Заказ создан

{
  // ID Заказа
  "order_id": 12
}


RESPONSE 404
# Клиент не найден

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

Для того чтоб движок Tomoru распознал REST API микросервиса, необходимо описать API в формате OpenAPI v3.

Tomoru полностью поддерживает формат OpenAPI v3, но есть ограничение: Tomoru в данный момент может работать только с запросами и ответами в формате JSON. Это значит, что любые requestBody.content или responses.CODE.content отличные от application/json поддерживаться не будут.

Общие данные микросервиса

Tomoru поддерживает описание микросервиса в соответствии со спецификацией OpenAPI. Общие данные описываются в разделе info.

Помимо стандартных полей Tomoru позволяет указать URL к изображению с логотипом микросервиса. Для этого URL изображения надо указать в поле x-logo раздела info.

Tomoru позволяет описать конфигурацию, которую должен настроить Администратор робота, для использования микросервиса. Часто возникает ситуация, что для работы каких-то методов микросервиса нужны те или иные данные. Tomoru позволяет гибко указать какие именно данные нужны для работы микросервиса. Для этого нужно использовать поле x-config раздела info. В данном поле должен содержаться объект JSON Schema, описывающий конфигурацию микросервиса. Tomoru обработает этот объект и создаст в интерфейсе поля для конфигурирования микросервиса.

Конфигурация микросервиса обязательно должна быть в виде JSON Schema, которая будет описывать 1-уровневый объект с любым количеством полей. Многоуровневые объекты в данный момент не поддерживаются.

Если в спецификаии микросервиса будет найдено описание конфигурации, то Tomoru при подключении микросервиса к роботу, будет отображать в интерфейсе поля для конфигурирования этого микросервиса. Получить конфигурацию внутри какого-то метода микросервиса можно при помощи внедрения стандартного объекта TomoruConfig.

Конфигурация микросервиса будет для каждого робота своя

Пример описания общих данных микросервиса:

openapi: 3.0.3

info:
  version: 1.0.0
  # Заголовок будет отображаться в списке микросервисов, 
  # а так же в конструкторе, поэтому рекомендуется использовать
  # заголовок не больше 2-3 слов в длину
  title: Шаблонизатор
  # Данная картинка будет использоваться как логотип микросервиса
  x-logo: https://cdn.rawgit.com/pugjs/pug-logo/eec436cee8fd9d1726d7839cbe99d1f694692c0c/SVG/pug-final-logo-_-colour-128.svg
  # Описание может быть любой длины
  #
  # Первая строка из описания будет использована как краткое описание,
  # поэтому рекомендуется делать ее максимально емкой.
  #
  # Остальные строки будут использоваться как полное описание.
  # В них поддерживается Markdown-форматирование, включая изображения.
  description: |
    Шаблонизатор, использующий синтаксис Pug

    [Pug](https://pugjs.org/api/getting-started.html) - это высокопроизводительный 
    шаблонизатор вдохновленный шаблонизатором [Haml](http://haml.info/), позволяющий 
    быстро верстать HTLM-страницы.
  # Данное поле позволяет описать конфигурацию микросервиса,
  # которую пользователь должен заполнить, чтоб микросервис работал правильно.
  #
  # В данном примере пользователь должен будет заполнить поле
  # "Язык шаблонизатора", которые будет отправлено в метод микросервиса в виде
  # объекта `{language: "..."}`.
  x-config:
    # Конфигурация должна быть обязательно объектом JSON Schema
    schema:
      # Tomoru поддерживает конфигурацию только в виде 1-уровнего объекта
      type: object
      properties:
        # Например, тут для работы микросервиса нужно обязательно указать язык
        language:
          # Также поддерживаются типы number, integer и boolean
          type: string
          # Описание делайте в несколько слов, т.к. оно будет использоваться в качестве лейбла поля
          description: Язык шаблонизатора
          # Для строкового типа можно указать варианты значения
          enum:
            - ru-RU
            - en-US
            - pt-BR
          # Для любого типа можно указать значение по умолчанию
          default: en-US
      required:
        - language

Видимость метода микросервиса в Tomoru

В описании OpenAPI может быть огромное количество путей и операций к ним, но что бы Tomoru среди всех операций, описанных в вашей OpenAPI конфигурации, понимал какие нужно ему использовать, существует несколько поддерживаемых тегов операций:

tomoru/call

Методы, помеченные данным тегом, будут видны в конструкторе Tomoru и доступны для прямого вызова роботом.

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

tomoru/action

Методы, помеченные данным тегом, будут доступны для вызова "напрямую" из списка микросервисов. Обычно данным тегом удобно помечать служебные методы, которые должен вызывать Администратор робота, например, метод "Позвонить".

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

tomoru/bot_connected

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

В данный метод можно передать при необходимости только следующие параметры:

tomoru/bot_disconnected

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

В данный метод можно передать при необходимости только следующие параметры:

tomoru/config_updated

Методы, вызываемые при обновлении конфигурации микросервиса в роботе Tomoru.

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

tomoru/chat_activated

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

В данный метод можно передать при необходимости только следующие параметры:

tomoru/chat_deactivated

Методы, помеченные данным тегом, будут вызываться роботом Tomoru, когда робот закончит диалог с клиентом.

В данный метод можно передать при необходимости только следующие параметры:

tomoru/new_message

Методы, помеченные данным тегом, будут вызываться роботом Tomoru при каждом новом сообщение в чате.

В данный метод можно передать при необходимости только следующие параметры:

tomoru/event_status_changed

Методы, помеченные данным тегом, будут вызываться роботом Tomoru при изменении статуса события, отправленного в Tomoru.

В данный метод можно передать при необходимости только следующие параметры:

Внедрение стандартных данных и параметров Tomoru в запрос метода микросервиса

Tomoru позволяет вставлять в запрос метода микросервиса определенные стандартные данные различных объектов Tomoru. Для этого необходимо в запросе вставить OpenAPI ссылку ($ref) на определенный объект или параметр Tomoru.

В любой запрос метода микросервиса, где это разрешено, можно в поле parameters вставить ссылку на объект параметры, который будет добавлен к запросу. Так же в любой запрос метода микросервиса, где это разрешено, можно в поле requestBody.content['application/json'].schema.parameters вставить ссылку на стандартные объекты Tomoru, которые будут добавлены к запросу.

Все ссылки имеют формат https://api.tomoru.ru/openapi#/components/schemas/{ТИП_ОБЪЕКТА}.

Тэг, для которого вызван микросервис tag

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

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

Пример использования:

/call/setValue:
  tags:
    - tomoru/call
    - tomoru/chat_activated
  post:
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              botId:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/tag'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  tag: 'tomoru/call',
  // ...
}

Уникальный идентификатор робота botId

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлена строка, содержащая ID робота, для которого вызван микросервис.

Пример использования:

/call/setValue:
  post:
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              botId:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/botId'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  botId: '10ra0Z66C4oBdLykQ6kd',
  // ...
}

Уникальный идентификатор чата chatId

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

Пример использования:

/call/setValue:
  post:
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              chatId:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/chatId'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  chatId: 'p3tltHC8rfsfoaDWLoC8',
  // ...
}

Данные конфигурации микросервиса TomoruConfig

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий настройки микросервиса для робота, в контексте которого вызван метод микросервиса.

Содержит следующие поля:

  • config (объект) - Объект, содержащий конфигурацию микросервиса для текущего робота

Пример использования:

/call/setValue:
  post:
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              config:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruConfig'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  config: {
    // Данные конфигурации
  },
  // ...
}

Данные робота TomoruBot

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

Содержит следующие поля:

  • id (строка) - ID робота
  • title (строка) - Название робота

Пример использования:

/call/setValue:
  post:
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              bot:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruBot'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  bot: {
    id: '10ra0Z66C4oBdLykQ6kd',
    title: 'My mega bot',
  },
  // ...
}

Данные чата TomoruChat

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий данные чата.

Содержит следующие поля:

  • id (строка) - ID чата
  • uri (строка) - URI чата, может быть:
    • id://... - Уникальный идентификатор чата
    • tel://... - Телефонный номер чата
    • https://vk.com/... - URI чата в мессенджерах

Пример использования:

/call/setValue:
  post:
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              chat:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruChat'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  chat: {
    id: 'p3tltHC8rfsfoaDWLoC8',
    title: 'Ivan Petrov',
  },
  // ...
}

Данные интеграции, для которой создан чат TomoruChatIntegration

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий данные чата.

Содержит следующие поля:

  • id (строка) - ID интеграции чата
  • title (строка) - Название интеграции
  • type (строка) - Тип интеграции, возможные значения:
    • vk - Интеграция с Вконтакте
    • telegram - Интеграция с Telegram
    • helpdeskeddy - Интеграция с HelpDeskEddy
    • viber - Интеграция с Viber
    • webchat - Интеграция в виджетом "Веб-чат на сайт"
    • phone - Телефонная интеграция
    • bitrix24 - Интеграция с Bitrix24
    • wazzup - Интеграция с Wazzup
  • config (объект) - Конфиг интеграции чата

Пример использования:

/call/setValue:
  post:
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              chatIntegration:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruChatIntegration'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  chatIntegration: {
    id: '1471UsiDySF9QyWIRePl',
    title: 'Incomming phone',
    type: 'phone',
    config: { language: 'ru-RU' },
  },
  // ...
}

Сообщение чата TomoruMessage

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий текущее сообщение чата.

Может использоваться только в методах, помеченных тегом tomoru/new_message

Содержит следующие поля:

  • id (строка) - ID сообщения
  • date (строка) - Дата сообщения в формате RFC 3339, секция 5.6
  • direction (строка) - Направление сообщения. Может быть одним из значений:
    • incoming - Входящее сообщение (фраза клиента)
    • outgoing - Исходящее сообщение (ответ робота или оператора)
  • text (строка, может отсутствовать) - Текст сообщения, если сообщение содержит текст
  • attachmentUrl (строка, может отсутствовать) - URL для загрузки вложения в сообщении, если сообщение содержит вложение. URL будет действителен 30 минут с момента отправки. Используйте его только для загрузки вложения.

Пример использования:

/onNewMessage:
  post:
    tags:
      - tomoru/new_message
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruMessage'

Будет вызван метод: https://api.acme.com/onNewMessage с телом, которое будет содержать объект:

{
  // ...
  message: {
    id: '10ra0Z66C4oBdLykQ6kd',
    date: '2020-05-07T10:16:29',
    direction: 'incoming',
    text: 'Hello!',
  }
  // ...
}

Список сообщений чата TomoruMessages

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен массив, содержащий сообщения чата.

Может использоваться только в методах, помеченных тегом tomoru/chat_deactivated

Структура элеметнов массива совпадает с TomoruMessage.

Пример использования:

/onDeactivate:
  post:
    tags:
      - tomoru/chat_deactivated
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              messages:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruMessages'

Будет вызван метод: https://api.acme.com/onDeactivate с телом, которое будет содержать объект:

{
  // ...
  messages: [
    {
      id: '10ra0Z66C4oBdLykQ6kd',
      date: '2020-05-07T10:16:29',
      direction: 'incoming',
      text: 'Hello!',
    },
    {
      id: '20rs0Z66C4oBGLy7Q6kz',
      date: '2020-05-07T10:17:10',
      direction: 'outgoing',
      text: 'How are you?',
    },
  ]
  // ...
}

Статус события TomoruEventStatus

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

Может использоваться только в методах, помеченных тегом tomoru/event_status_changed

Содержит следующие поля:

  • trackingId (строка) - ID отслеживания события, которое установил микросервис, вызывая событие
  • event (строка) - Название события. которое установил микросервис, вызывая событие
  • status (строка) - Новый статус события, может быть одним из:
    • sent_to_bot - Событие отправлено на обработку роботом
    • processed - Событие обработано роботом
    • rejected - Событие НЕ обработано роботом

Пример использования:

/eventChanged:
  post:
    tags:
      - tomoru/event_status_changed
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              eventStatus:
                $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruEventStatus'

Будет вызван метод: https://api.acme.com/call/eventChanged с телом, которое будет содержать объект:

{
  // ...
  eventStatus: {
    trackindId: '100',
    event: 'cold_call',
    status: 'sent_to_bot',
  },
  // ...
}

Результаты работы микросервисов

Каждый response пути paths, описанного в OpenAPI, будет представлен как результат выполнения метода микросервиса. Tomoru никак не ограничивает выбор статуса для ответа.

Будьте внимательны со стандартными HTTP-статусами, т.к. некоторые из них (например, 204 No Content) не предусматривают тела ответа, поэтому многие библиотеки для работы с HTTP могут не отправить в ответе данные, даже если вы их укажите.

Пример описание микросервиса при помощи OpenAPI

Для приведенного выше микросервиса описание будет выглядеть так:

openapi: 3.0.3

info:
  version: 1.0.0
  title: Клиентская база
  # Рекомендуется писать развернутую документацию по сервису
  # для того, чтоб пользователи микросервиса могли понять зачем он нужен
  description: Сервис для работы с нашей внутренней клиентской базой

servers:
  - url: https://api.acme.com

paths:
  /client/find:
    get:
      # Рекомендуем для каждой операции указывать уникальный operationId,
      # для того, чтоб в будущем можно было для операции поменять путь или
      # метод вызова без необходимости исправлять логику работы роботов Tomoru
      operationId: findClient
      summary: Ищет клиента по имени
      tags:
        # Тег tomoru/call показывает, что данный метод должен быть доступен для
        # вызова роботом Tomoru. Если в вашей OpenAPI конфигурации присутствуют
        # ваши внутренние методы, то их помечать данным тегом не нужно
        - tomoru/call
      parameters:
        - in: query
          name: name
          # Для всех параметров и полей запросов желательно делать описание в
          # одно, два слова, т.к. это описание будет отображено в конструкторе
          # и длинное описание будет обрезано. Т.е. тут очень емко в 2 словах.
          description: Имя клиента
          schema:
            type: string
          required: true
      responses:
        200:
          description: Клиент найден
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID клиента
                  name:
                    type: string
                    description: Имя клиента
                  address:
                    type: string
                    description: Адрес клиента
                  phone:
                    type: string
                    description: Телефон клиента
                required:
                  - id
                  - name
                  - phone

        404:
          description: Клиент не найден

  /client/{id}/update:
    post:
      operationId: updateClient
      summary: Обновляет информацию о клиенте
      tags:
        - tomoru/call
      parameters:
        - in: path
          name: id
          description: ID клиента
          schema:
            type: integer
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Имя клиента
                address:
                  type: string
                  description: Адрес клиента
                phone:
                  type: string
                  description: Телефон клиента
              required:
                - name
                - phone
      responses:
        200:
          description: Данные обновлены
        403:
          description: Обновление запрещено
        404:
          description: Клиент не найден

  /order/create:
    post:
      operationId: createOrder
      summary: Создает заказ
      tags:
        - tomoru/call
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: integer
                  description: ID клиента
                order_description:
                  type: string
                  description: Содержимое заказа
              required:
                - client_id
                - order_description
      responses:
        200:
          description: Заказ создан
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id:
                    type: integer
                    description: ID заказа
                required:
                  - order_id
        404:
          description: Клиент не найден

Добавление действия микросервиса

Tomoru позволяет добавлять кнопки с произвольными действиями в список микросервисов робота. Данные кнопки удобны для выполнения разовых операций Администратором робота над микросервисом. Ярким примером такого действиям может быть действие "Позвонить по списку клиентов", которое будет вызывать Администратор робота для того, чтоб обзвонить список клиентов, сохраненный в микросервисе. При нажатии на кнопку действия, Tomoru вызовет соответствующей ей метод микросервиса.

Для того, чтобы Tomoru добавило кнопку с действием в список микросервисов рядом с микросервисом, нужно создать метод и поменить его тегом tomoru/action. В действия как и в другие методы микросервиса можно добавлять стандартные данные Tomoru.

Действие должно вернуть 1 или более результатов, если будет возвращен результат с кодом отличным от 2хх, то Tomoru будет считать, что действие не выполнено.

Пример описание спецификации OpenAPI для добавления действия

Ниже приведен пример микросервиса, который добавит действие "Позвонить"

openapi: 3.0.3

info:
  version: 1.0.0
  title: Клиентская база
  # Рекомендуется писать развернутую документацию по сервису
  # для того, чтоб пользователи микросервиса могли понять зачем он нужен
  description: Сервис для работы с нашей внутренней клиентской базой

servers:
  - url: https://api.acme.com

paths:
  /action/call:
    get:
      # Рекомендуем для каждой операции указывать уникальный operationId,
      # для того, чтоб в будущем можно было для операции поменять путь или
      # метод вызова без необходимости исправлять логику работы роботов Tomoru
      operationId: call
      # Данное поле будет отображено как лебл кнопки
      summary: Позвонить
      # Данное поле будет отображено во всплывающей подсказки для действия
      description: Инициирует звонок по списку всех клиентов нашей БД
      tags:
        # Тег tomoru/action показывает, что данный метод должен быть доступен в 
        # в качестве действия микросервиса
        - tomoru/action
      parameters:
        # Добавим в запрос ID робота, для которого будет вызвано действие
        - in: query
          name: botId
          schema:
            $ref: 'https://api.tomoru.ru/openapi#/components/schemas/botId'
          required: true
        # Добавим в запрос ID чата, для которого будет вызвано действие
        - in: query
          name: chatId
          schema:
            $ref: 'https://api.tomoru.ru/openapi#/components/schemas/chatId'
          required: true
      responses:
        200:
          description: Звонок пошел

Отправка микросервисом событий в Tomoru

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

  1. Создать веб-хук микросервиса с тегом tomoru/subscribe, который Tomoru будет вызывать для того, чтоб подписаться на события микросервиса.
  2. Прописать OpenAPI-коллбеки в этом веб-хуке, которые будут описывать события робота.

Создание веб-хука tomoru/subscribe

Необходимо создать веб-хук с тэгом tomoru/subscribe, который будет принимать от Tomoru POST-запрос со следующими данными в формате JSON:

{
  tomoruCallbackUrl: 'https://europe-west1-hypercalls.cloudfunctions.net/microserviceEvent/{JWT_token}',
}

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

Описание OpenAPI-коллбеков

Для того, чтобы Tomoru мог понять какие именно события микросервис планирует отправлять, их нужно описать. Делается это при помощи OpenAPIv3 возможность - коллбеков. Необходимо в методе, помеченном тегом tomoru/subscribe, в поле callbacks описать все события, которые будет отсылать микросервис. Обязательное условие — это формат записи callback URL в поле callbacks - оно должно быть всегда {$request.body#/tomoruCallbackUrl}.

Все события должны отсылаться обязательно POST запросом.

На тело событий Tomoru накладывает ограничение по формату, он должен быть вида:

{
  // Имя события, которое совпадает с ключем объекта `callbacks` OpenAPI спецификации 
  // микросервиса
  event: '<ИМЯ_СОБЫТИЯ>',
  // Уникальный идентификатор события, который используется в трекенге статуса события в методах,
  // помеченных тегом `tomoru/event_status_changed`. См. "Отслеживание изменения статуса событий".
  //
  // Может быть любой строкой. Генерируется на стороне микросервиса.
  //
  // Не обязательно поле, если не указано, то статусы события трекаться не будут.
  trackingId: '<ID_СОБЫТИЯ>',
  // ID робота, в который надо отправить событие
  botId: '<ID_РОБОТА>',
  // URI для идентификации чата, в который нужно отправить событие
  chatUri: '<URI_ЧАТА>',
  data: {
    // Не обязательный объект, содержащий произвольные данные, которые будут
    // доставлены в Tomoru вместе с событием
  }
}

Поле event должно содержать имя события. "Имя события" - это то, как называется параметр, описывающий событие, в поле callbacks OpenAPI конфигурации.

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

  • id://<ИД_ЧАТА> (например, id://lwfw6HpLC1kOslgPREhh) - чат будет найден по его ID. Лучше всего использовать именно поиск по ID чата, т.к. этот способ гарантирует то, что событие будет доставлено именно в тот чат, в который нужно
  • tel://<ТЕЛЕФОН_ЧАТА> (например, tel://+79999999999) - чат будет найден по номеру телефона
  • https://vk.com/<ИД_АККАУНТА> (например, https://vk.com/1) - чат будет найден по ID пользователя во вконтакте
  • tg://<ИД_АККАУНТА> (например, tg://1) - чат будет найден по ID пользователя в Telegram
  • viber://<ИД_АККАУНТА> (например, viber://1) - чат будет найден по ID пользователя в Viber

Tomoru позволяет отслаживать статус события, если передать вместе с событием его уникальный идентификатор в поле trackingId.

Отслеживание статусов событий

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

Для начала в микросервисе надо реализовать метод, который будет помечен тегом tomoru/event_status_changed. На данный метод не накладываются никакие специальные ограничения, но внутри него помимо других стандартных объектов Томору, можно использовать стандартный объект TomoruEventStatus.

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

Пример описания OpenAPI конфигурации микросервиса, работающего с событиями

Микросервис ниже описывает метод /subscribe для получения URL веб-хука, используемого для отправки события, и два события: "Холодный звонок" и "Проверка качества".

openapi: 3.0.3

info:
  version: 1.0.0
  title: Демо микросервис
  description: Сервис, демонстрирующий возможности обработки событий роботом

servers:
  - url: https://api.acme.com/demoMicroservice

paths:
  /subscribe:
    post:
      operationId: subscribe
      summary: Подписывается на события
      tags:
        # Тэг, показывающий, что данный метод Tomoru должен использовать для
        # того, чтоб подписаться на события микросервиса
        - tomoru/subscribe
      requestBody:
        content:
          # POST-запрос https://api.acme.com/demoMicroservice/subscirbe прийдет
          # объект, содержащий tomoruCallbackUrl, который нужно сохранить где-то
          application/json:
            schema:
              type: object
              properties:
                tomoruCallbackUrl:
                  type: string
              required:
                - tomoruCallbackUrl
      callbacks:
        # При отправке этого события в толе `event` POST-запроса должно быть 'coldCall'
        coldCall:
          # Callback URL всгде должен быть такого вида
          '{$request.body#/tomoruCallbackUrl}':
            # Все коллбеки должны вызываться только при помощи POST-запросов
            post:
              # Тут лучше использовать описание в несколько слов, чтоб событие 
              # хорошо выглядело в конструкторе Tomoru
              summary: Холодный звонок
              # Тут можно использовать сколь угодно длинное описание того как работает
              # событие
              description: Звонок новым клиентам
              requestBody:
                content:
                  application/json:
                    schema:
                      # Для удобства можно использовать OpenAPI функцию allOf
                      # и готовое описание обязательных полей тела события
                      # 'https://api.tomoru.ru/openapi#/components/schemas/TomoruEvent'
                      allOf:
                        - $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruEvent'
                        - type: object
                          properties:
                            # В свойстве data можно описать произвольный набор данных,
                            # которые Tomoru получит вместе с событием.
                            data:
                              type: object
                              properties:
                                userName:
                                  type: string
                                  # Описание полей должно быть в несколько строк для удобства работы
                                  # с ними в констукторе Tomoru
                                  description: Имя пользователя
                                  example: Ivan
                              required:
                                - userName
              responses:
                200:
                  description: Все ок
        qualityControlCall:
          '{$request.body#/tomoruCallbackUrl}':
            post:
              summary: Проверка качества
              description: Звонок клиентам с целью проверки качества
              requestBody:
                content:
                  application/json:
                    schema:
                      allOf:
                        - $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruEvent'
                        - type: object
                          properties:
                            data:
                              type: object
                              properties:
                                userName:
                                  type: string
                                  description: Имя пользователя
                                  example: Ivan
                                visitDate:
                                  type: string
                                  description: Дата визита
                                  example: 11.12.2020 11:22
                              required:
                                - userName
                                - visitDate
              responses:
                200:
                  description: Все ок

      responses:
        200:
          description: Успешно подписались на события

Добавление микросервиса в Tomoru

Добавить микросервис в Tomoru можно при помощи утилиты командной строки @tomoru/cli. Для работы данной утилиты требуется node.js версии 10 или выше.

Установить утилиту можно так:

npm install -g @tomoru/cli

После установки утилиты, будет доступна консольная команда tomoru.

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

tomoru microservice set <уникальный_ид_микросервиса> <путь_к_файлу_конфигурации> --bot-id=<уникальный_идентификатор_робота>

# Например:
tomoru microservice set my_back_api ./api.yaml --bot-id=4jTGH3iO4sWEMLC4Y148

Best Practice

Используйте "подходящие" типы HTTP-запросов

Старайтесь использовать "подходящие" типы HTTP-запросов для методов. Например, если предполагается, что метод не меняет никаких данных, и результат его при вызове с одними и теми же параметрами всегда будет одинаковый, то лучше использовать GET-запрос, т.к. Tomoru сможет закешировать результат запроса и использовать его повторно, из-за чего скорость работы робота будет выше, а нагрузка на микросервис - ниже.

Возвращайте в результатах те данные, которые описали в спецификации OpenAPI

Tomoru контролирует то, что возвращает метод микросервиса в результате своего выполнения, и, если результат работы метода, будет отличаться от того, что заявлено в спецификции, то Tomoru может отвергнуть результат работы.

Предусматривайте результат метод "Что-то пошло не так" (500 ошибка)

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

Давайте подробные и понятные описания для микросервиса

Давайте полное и понятное описание микросервиса (поле description в info), для того, чтоб пользователи вашего микросервиса могли понять, что он делает. Tomoru в данном поле поддерживает описание в формате Markdown (включая изображения), поэтому в описание можно использовать Markdown - форматирование.

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

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

Старайтесь в описании метода микросервиса (поле description в пути) объяснить, что именно будет делать метод микросервиса, как он будет вести себя при различных входящих параметрах, и какие результаты будут ожидаемыми и в каких случаях.

Давайте подробное описание для параметров метода или результата микросервиса

Давайте понятное название для параметров методов и результатов микросервисов (поле description параметра).

Первая строка из описания будет отображена как название параметра, поэтому делайте ее не больше 1-2 слов