Блок: API запрос

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

Вы можете обращаться к данному блоку неоднократно во время работы в разных блоках создаваемого вами бизнес-процесса.

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

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

Создание API сценария

Для добавления нового сценария, нажимаем кнопку "Добавить"

В момент создания первого сценария мы переходим к меню добавления вебхука для взаимодействия с API внешних сервисов.

• Название - название вебхука

• URL - предназначен для указания адреса, куда будет отправляться вебхук.

• Запрос - тип запрос

  • GET — используется для получения данных. Например, вы заходите на сайт и видите список товаров. Это как спросить у продавца: "Что у вас есть?".

  • POST — отправляет данные на сервер. Например, вы заполняете форму на сайте и отправляете её. Это как дать продавцу записку: "Хочу заказать этот товар".

  • PUT — обновляет или заменяет данные. Например, вы изменяете адрес доставки. Это как сказать продавцу: "Исправьте мой адрес на новый".

  • DELETE — удаляет данные. Например, вы удаляете ненужный товар из корзины. Это как попросить: "Уберите это из моего заказа".

• Типы контента

  • application/json — данные передаются в формате JSON (например, список или структура, как в рецепте: "ингредиенты: мука, сахар, яйца"). Это удобно, когда нужно передать сложные данные, например, информацию о заказе.

    Пример:

    jsonКопировать код{
      "name": "Иван",
      "age": 25
    }

  • application/x-www-form-urlencoded — данные передаются в виде строки (например, "name=Иван&age=25"). Этот способ подходит для простых форм, как анкета в поликлинике.

    Пример:

    makefileКопировать кодname=Иван&age=25

Заголовки

• Заголовки HTTP запроса - они используются для передачи метаинформации серверу о запросе.

  • Content-Type — это заголовок, который сообщает серверу, в каком формате передаются данные. В данном случае указано application/json, что означает, что данные будут передаваться в формате JSON.

  • Пример:

    Если вы отправляете данные о заказе:

    json
    {
      "order_id": 123,
      "item": "Торт",
      "quantity": 1
    }

    Заголовок Content-Type: application/json сообщает серверу, что он должен ожидать данные именно в формате JSON.

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

Куки

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

  Поля:

  1. Название — имя cookie. Например, это может быть идентификатор сессии, который сервер использует для распознавания пользователя.

     • Пример: session_id

  2. Значение — значение cookie. Обычно это уникальный код или данные, связанные с пользователем или его действиями.

     • Пример: abc123xyz

  Зачем нужны Cookies?

  • Чтобы сервер мог "запомнить" пользователя.

  • Для авторизации, хранения предпочтений или отслеживания сеанса.

  Пример:

  Если вы авторизуетесь на сайте, сервер отправляет cookie с вашей сессией:

  • Название: user_token

  • Значение: xyz789secure

Тело

• Тело (Body) для вебхука. Используется для передачи данных в теле HTTP-запроса.

  Что это?

  Тело запроса — это основное содержимое, которое передается на сервер. Оно применяется для методов, таких как POST или PUT, когда требуется отправить данные (например, заполненную форму или информацию о новом объекте).

  Поля:

  1. Название — ключ (имя параметра), описывающий данные.

     • Пример: username

  2. Значение — данные, которые передаются под этим ключом.

     • Пример: ivanov

  Пример:

  Если вы хотите зарегистрировать пользователя, тело запроса может выглядеть так:

  json
  {
    "username": "ivanov",
    "email": "[e-mail]"
  }

  • Название: username, значение: ivanov

  • Название: email, значение: [e-mail]

  Когда используется:

  • Для передачи данных формы.

  • Для создания/обновления объектов в базе данных.

  • Для отправки сложных структурированных данных (например, JSON).

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

Параметры

• Параметры для настройки вебхука. Параметры используются для передачи данных в URL запроса, особенно для метода GET.

  Что это?

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

  Поля:

  1. Название — имя параметра, которое идентифицирует передаваемые данные.

     • Пример: user_id

  2. Значение — данные, связанные с этим параметром.

     • Пример: 123

  Пример:

  Если вы хотите запросить информацию о пользователе с ID 123, ваш URL с параметрами будет выглядеть так:

  https://example.com/api?user_id=123

  • Название: user_id, значение: 123.

  Когда используется:

  • Для фильтрации или поиска данных.

  • Для передачи информации, влияющей на результат запроса (например, язык интерфейса, сортировка).

  Важно: Параметры хорошо подходят для GET-запросов, но для передачи больших объемов данных лучше использовать тело запроса.

Записи

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

  Поля:

  1. Тип данных (например, Параметры) — откуда берутся данные:

     • Параметры — извлекаются из переданных параметров.

     • Заголовки — извлекаются из заголовков запроса.

     • Тело — извлекаются из содержимого тела запроса/ответа.

  2. Исходное значение — конкретное значение или поле, которое нужно сохранить.

     • Пример: user_id.

  3. Значение для сохранения — формат или тип данных, которые будут сохранены.

     • Например, String (строка) или Integer (число).

  4. Нулевое (Null) — отмечается, если значение может быть пустым.

  Пример:

  Допустим, вы отправляете запрос с параметром user_id=123, и хотите сохранить это значение:

  • Тип данных: Параметры.

  • Исходное значение: user_id.

  • Значение для сохранения: String.

  Когда используется:

  • Для сохранения идентификаторов (например, user_id) для последующих запросов.

  • Для обработки данных ответа и передачи их дальше в цепочке действий.

  • Для проверки значений или их хранения.

  Важно: Убедитесь, что вы корректно извлекаете данные из нужного источника (параметров, тела или заголовков).

Схема ответов

• Схема ответа позволяет задать формат данных, которые сервер должен вернуть в ответе на запрос. Определяет ожидаемую структуру ответа от сервера. Она используется для проверки, что ответ соответствует заданному формату, и помогает обработать данные.

  Поля:

  1. type — тип данных, который должен возвращать сервер.

     • Пример: object (объект, как JSON), array (массив), string (строка), boolean (логическое значение).

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

     • Пример: ["result"] указывает, что поле result обязательно.

  3. properties — описание структуры ответа, где задаются ожидаемые поля и их типы.

     • Пример:

       json
       {
         "result": { "type": "boolean" }
       }

       Это означает, что в ответе должно быть поле result с типом boolean (истина или ложь).

  Пример:

  Если сервер возвращает:

  json
  {
    "result": true
  }

  И схема ответа задана так:

  json
  {
    "type": "object",
    "required": ["result"],
    "properties": {
      "result": { "type": "boolean" }
    }
  }

  Запрос будет считаться успешным, так как ответ соответствует схеме.

  Когда используется:

  • Чтобы убедиться, что сервер возвращает данные в правильном формате.

  • Для упрощения обработки ответа, исключая неожиданные ошибки.

  • Для интеграций, где важно строгое соответствие данных.

  Итог: Схема ответа — это способ зафиксировать, какой формат и тип данных вы ожидаете от сервера. Это помогает сделать взаимодействие более надёжным.

Сохранение

• Сохранение переменной, позволяет сохранять данные для последующего использования. Это полезно для передачи значений между запросами или сохранения результатов ответа.

  Поля:

  1. Исходное значение — здесь указывается, откуда берётся значение (например, параметр, заголовок или поле из ответа). Это источник данных.

  2. Тип данных (String, Number, Array, Object) — задаётся формат данных, которые вы сохраняете:

     • String — текстовая строка (например, имя пользователя).

     • Number — числовое значение (например, идентификатор или цена).

     • Array — массив данных (список значений, например, список товаров).

     • Object — объект (структура данных, содержащая ключи и значения, например, профиль пользователя).

  3. Значение для сохранения — конечное значение, которое будет сохранено (определяется исходным значением и типом данных).

  Пример:

  Если вы хотите сохранить идентификатор пользователя из ответа API:

  • Исходное значение: user_id (из поля ответа).

  • Тип данных: Number.

  • Значение для сохранения: ID, например, 123.

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

  • Для передачи данных в последующих запросах.

  • Для анализа или логирования данных.

  • Для динамического изменения запроса на основе ответа.

  Когда используется:

  • В интеграциях, где данные из одного шага нужно использовать в другом.

  • В автоматизации процессов, где важно сохранять промежуточные результаты.

  Итог: Этот раздел позволяет извлечь и сохранить данные в удобном формате, чтобы использовать их в дальнейшем.

Условия

• Интерфейс для добавления условия срабатывания вебхука. Это позволяет задавать логику выполнения вебхука на основе определённых правил и данных.

  Элементы интерфейса:

  1. Название — имя условия, чтобы вы могли легко его идентифицировать. Например, "Обновление заголовка авторизации".

  2. Вебхук — выбор вебхука, для которого задаётся это условие. Это связывает условие с конкретным запросом.

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

  4. Тип условия — задаёт логику срабатывания. Например, проверка определённого заголовка или значения в запросе.

Типы условий

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

  Описание типов условий:

  1. update_auth_header

     • Проверяет или обновляет заголовок авторизации (Authorization) в запросе.

     • Используется для управления авторизацией, например, добавления токена.

  2. update_auth_query

     • Проверяет или обновляет параметры авторизации, передаваемые через строку запроса (query parameters).

     • Полезно, если авторизация передаётся как параметр URL, например, ?auth_token=abc123.

  3. header

     • Проверяет значения в заголовках запроса.

     • Применяется для проверки любых заголовков, например, Content-Type, Authorization или пользовательских заголовков.

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

  • Тип: update_auth_header Цель: Убедиться, что в заголовке Authorization есть корректный токен.

  • Тип: update_auth_query Цель: Проверить, что в URL есть параметр auth_token, и он соответствует заданному значению.

  • Тип: header Цель: Убедиться, что заголовок Content-Type равен application/json.

  Когда использовать:

  • update_auth_header — для работы с токенами в заголовках.

  • update_auth_query — когда токены или ключи передаются через параметры URL.

  • header — для проверки любых других заголовков в запросе.

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

Правила отображения

• Правило— определяет конкретное условие:

  • Нулевое — отмечается, если значение может быть пустым (null).

  • Исходное значение — откуда берётся проверяемое значение (например, заголовок, параметр или тело).

  • Тип данных (String, Number, Array, Object) — указывает, как интерпретировать данные (строка, число, массив, объект).

  • Значение для сравнения — значение, с которым будет сравниваться исходное.

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

  Если вы хотите проверить, что заголовок Authorization содержит определённый токен:

  • Тип условия: update_auth_header

  • Исходное значение: Authorization

  • Тип данных: String

  • Значение для сравнения: Bearer abc123.

  Если условие выполняется, вебхук отправляется или переключается на указанный условный вебхук.

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

  • Для динамической обработки запросов.

  • Чтобы проверять авторизацию или корректность данных перед выполнением действия.

  • Для создания гибкой логики в интеграциях.

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

Действие

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

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

    • Описание: "Обновление данных пользователя после успешной авторизации".

      • Шаги:

        1. Отправить вебхук с запросом авторизации.

        2. Проверить условия (например, токен возвращён и валиден).

        3. Выполнить действие — обновить данные пользователя через другой вебхук.

    Когда использовать:

    • Для автоматизации процессов, таких как синхронизация данных между системами.

    • Для выполнения цепочек действий на основе внешних событий (например, авторизации, отправки данных, получения статусов).

Примеры

Вариант 1

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

---

Предыдущий шаг:

Перед блоком "API сценарий" выполняется настройка веб-хука. В веб-хуке указаны:

1. URL: https://test.com/test/files/cars.js — ссылка на API для получения списка машин.

2. Тип запроса: GET — используется для получения данных.

3. Заголовки:

   • Content-Type: application/json — указывает, что данные возвращаются в формате JSON.

После настройки веб-хука он добавляется в сценарий как действие.

---

Текущая конфигурация блока:

1. Название блока: "Получение списка машин".

2. Вкладка "Вебхуки":

   • Используется настроенный веб-хук под названием "Список".

3. Вкладка "Условия":

   • В текущем кейсе условия отсутствуют. Блок запускается автоматически, как только сценарий доходит до этого этапа.

4. Вкладка "Действия":

   • В действие добавлен веб-хук "Список", который выполняет API-запрос.

---

Что происходит в блоке:

1. При выполнении блока происходит вызов веб-хука с запросом на указанный URL.

2. Запрос возвращает данные о машинах (например, цвет, модель, цена, местоположение) в формате JSON.

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

Вариант 2

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

---

Применение API-запросов:

1. Получение токена (аутентификация):

   • Запрос отправляется для проверки идентификации клиента. Если пользователь не авторизован, система возвращает результат с требованием авторизации.

2. Получение идентификатора клуба:

   • Определяет, в каком клубе клиент зарегистрирован. Это важно, если сеть фитнес-клубов большая и у каждого свои занятия.

3. Получение списка занятий:

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

4. Запись на занятие:

   • POST-запрос, передающий appointment_id (идентификатор занятия) и данные пользователя. После успешного выполнения возвращает подтверждение записи.

5. Получение списка записанных уроков:

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

6. Отмена занятия:

   • DELETE-запрос, который отменяет ранее сделанную запись на занятие по его уникальному идентификатору (appointment_id).

Блок №1

1. Получение токена (аутентификация)

Название блока: Запуск API – Получение токена URL: http://test:[e-mail]/hs/api/v3/au Тип запроса: POST Тип контента: application/json

Заголовки:

• Content-Type: application/json

• apikey: test

Тело:

json
{
  "username": "${username}",
  "password": "${password}"
}

Описание: Данный блок используется для аутентификации клиента в системе. Клиент передает свой логин и пароль, на основе которых система выдает токен (usertoken). Этот токен используется для идентификации клиента при выполнении последующих запросов.

Назначение:

• Обеспечить безопасный доступ к API.

• Проверить права доступа клиента.

---

2. Получение идентификатора клуба

Название блока: Запуск API – Получение идентификатора клуба URL: http://test:[e-mail]/hs/api/v3/club Тип запроса: GET Тип контента: application/json

Заголовки:

• Content-Type: application/json

• apikey: test

• usertoken: ${usertoken}

Описание: Запрос выполняется для получения информации о клубе, к которому принадлежит клиент. Это важно, чтобы определить доступные занятия, привязанные к конкретному клубу.

Назначение:

• Идентификация клуба для фильтрации занятий.

• Персонализация списка услуг и занятий для клиента.

---

3. Получение списка занятий

Название блока: Запуск API – Получение списка занятий URL: http://test:[e-mail]/hs/api/v3/classes Тип запроса: GET Тип контента: application/json

Заголовки:

• Content-Type: application/json

• apikey: test

• usertoken: ${usertoken}

Параметры:

• start_date: ${tomorrow:00:00}

• end_date: ${after2Months:23:59}

• club_id: ${club_id}

Описание: Запрос возвращает список доступных занятий для клиента в указанном временном интервале. Параметры запроса позволяют фильтровать занятия по дате и клубу.

Назначение:

• Предоставить клиенту актуальный список занятий.

• Позволить клиенту выбрать удобное время и место для тренировки.

---

4. Запись на занятие

Название блока: Запуск API – Запись на занятие URL: http://test:[e-mail]/hs/api/v3/book Тип запроса: POST Тип контента: application/json

Заголовки:

• Content-Type: application/json

• apikey: test

• usertoken: ${usertoken}

Тело:

jsonКопироватьРедактировать{
  "appointment_id": "${lessonId}"
}

Описание: Запрос используется для бронирования клиентом места на занятии. Указывается идентификатор занятия (appointment_id), который клиент выбрал из списка доступных.

Назначение:

• Подтвердить участие клиента в тренировке.

• Зарезервировать место на выбранном занятии.

---

5. Получение списка записанных уроков

Название блока: Запуск API – Получить список записанных уроков URL: http://test:[e-mail]/hs/api/v3/booked Тип запроса: GET Тип контента: application/json

Заголовки:

• Content-Type: application/json

• apikey: test

• usertoken: ${usertoken}

Описание: Запрос возвращает список всех занятий, на которые клиент уже записан. Это позволяет клиенту управлять своими бронированиями (например, отменять или проверять статус).

Назначение:

• Отображение текущих записей клиента.

• Упрощение управления занятиями.

---

6. Отмена занятия

Название блока: Запуск API – Отмена занятия URL: http://test:[e-mail]/hs/api/v3/cancel Тип запроса: DELETE Тип контента: application/json

Заголовки:

• Content-Type: application/json

• apikey: test

• usertoken: ${usertoken}

Параметры:

• appointment_id: ${lessonId}

Описание: Запрос отменяет ранее сделанную клиентом запись на занятие. Для этого необходимо указать идентификатор занятия (appointment_id).

Назначение:

• Позволить клиенту отменить участие в тренировке.

• Освободить место на занятии для других клиентов.

---

Взаимосвязь всех блоков:

1. Клиент начинает с авторизации через блок "Получение токена".

2. После успешной аутентификации выполняется запрос "Получение идентификатора клуба".

3. На основании полученного идентификатора и указанных временных параметров выполняется запрос "Получение списка занятий".

4. Клиент выбирает занятие и отправляет запрос через блок "Запись на занятие".

5. Для проверки текущих бронирований клиент использует блок "Получение списка записанных уроков".

6. Если клиенту нужно отменить запись, используется блок "Отмена занятия".