Использование объектов интеграцииBETA

При выполнении пользовательской интеграции код блоков и подключений работает с тремя основными объектами: bundle, context и service. Их правильное использование позволяет настраивать запросы, обрабатывать пагинацию и сохранять состояние между вызовами блока.

Объект bundle

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

• bundle.authData
• bundle.inputData

bundle.authData

Содержит данные для аутентификации, которые вы настраиваете в разделе Подключения. Все поля подключения становятся доступными через bundle.authData и используются для выполнения запросов к API или другим внешним сервисам.

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

(service, bundle) => {
    var response = service.request({
        url: bundle.authData.api_url + '/data',
        method: 'GET',
        headers: {
            Authorization: 'Bearer ' + bundle.authData.api_key
        }
    });

    if (response.status !== 200) {
        service.stringError('Ошибка запроса: ' + response.status);
    }
    return {
        output: () => ({
            data: response.json
        })
    };
}

bundle.inputData

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

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

(service, bundle) => {
    var response = service.request({
        url: bundle.inputData.api_endpoint,
        method: 'GET',
        headers: {
            Authorization: 'Bearer ' + bundle.inputData.access_token
        }
    });
    if (response.status !== 200) {
        service.stringError('Ошибка запроса: ' + response.status);
    }
    return {
        output: () => ({
            data: response.json
        })
    };
}

Объект context

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

Основные применения context:

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

Пример использования context в блоке с пагинацией:

var state;
if (context === undefined) {
  state = 1; // Начинаем с первой страницы
} else {
  state = context + 1; // Переходим на следующую страницу
}
var hasNext = state < limit; // Проверяем, есть ли следующая страница

Где:

• state — текущая страница, которая хранится в контексте
• hasNext — проверка, которая указывает нужно ли делать еще один запрос для следующей страницы

Объект service

Объект service — это набор вспомогательных методов, которые используются внутри блоков и подключений интеграции. С его помощью выполняются HTTP-запросы к внешним API, обрабатываются ошибки, реализуются OAuth-сценарии и вспомогательные операции с данными.

Методы объекта service доступны в функциях execute, executePagination, redirect, saveFields и других обработчиках интеграции.

Использование hook для OAuth-авторизации

Метод hook применяется в подключениях для реализации OAuth-сценариев. Он позволяет:

• Выполнить редирект пользователя на страницу авторизации
• Обработать возврат с authorization code
• Сохранить токены доступа
• Проверить корректность авторизации

Пример описания хука авторизации:

{
  key: "authorize",
  type: "button",
  label: "Авторизоваться",
  executeWithRedirect: (service, bundle) => {
    return `https://gitlab.com/oauth/authorize?...`;
  },
  executeWithSaveFields: (service, bundle) => {
    /* обмен code → token */
  },
  executeWithMessage: (service, bundle) => {
    /* проверка авторизации */
  }
}

Передача файлов в HTTP-запросах

Интеграции поддерживают загрузку и передачу файлов с использованием параметра multipartBody. Этот механизм применяется для отправки файлов в формате multipart/form-data при выполнении HTTP-запросов.

Пример передачи файла через service.request

Ниже приведен пример отправки файла во внешний API с использованием multipartBody:

var resp = service.request({
    url: 'https://api.example.com/upload',
    method: 'POST',
    headers: {
        Authorization: 'Bearer ' + bundle.authData.api_key,
        'Content-Type': 'multipart/form-data'
    },
    multipartBody: [
        {
            key: 'file',
            fileValue: bundle.inputData.file_content,
            fileName: bundle.inputData.file_name,
            contentType: 'application/octet-stream'
        }
    ]
});
if (resp.status !== 200) {
    service.error.stringError('Ошибка запроса: ' + resp.status);
}