Инструменты WEB API в СЭО 3КL. Возможности и примеры
Если вы используете более раннюю версию системы — обратитесь с заявкой на проведение обновления в службу технической поддержки ООО «Открытые технологии».
1. Общая информация
2. Возможности
2.1. Документация API СЭО 3КL
2.2. Использование API на примере создания нового пользователя
3. Предварительная настройка СЭО 3КL
3.1. Включение веб-служб и протоколов
3.2. Создание пользователя для веб-службы
3.3. Создание веб-службы
3.4. Создание ключа безопасности (токена)
4. Решения
4.1. С
1. Общая информация
Одним из вариантом взаимодействия внешних систем с СЭО 3КL является программный интерфейс приложений (API) - набор определенных способов и правил, позволяющий различным программным продуктам обмениваться данными по стандартизированным протоколам. API СЭО 3КL поддерживает обмен данными по протоколам REST, SOAP и XML-RPC.
Клиент API (непосредственно внешняя система или пользователь API через веб-браузер/консоль) обращается с запросом к серверу СЭО 3КL на выполнение функции (метода) API (Рис. 1.1). В зависимости от исполняемой функции, результатом запроса будет получение от сервера ответа с информацией из СЭО 3КL или какое-либо действие в системе.
Перед обработкой запроса выполняется аутентификация клиента API — сервер должен знать, кто делает запросы и имеет ли он на это право. Для этого запрос отправляется вместе с ключом безопасности (токеном), который сгенерирован с использованием информации учетной записи пользователя API. Если запрос содержит валидный ключ, то сервер выполнит его обработку.
Инструкции о том, как правильно использовать API (формировать запрос), информация о классах и типах возвращаемых значений, примеры запроса и сообщения об ошибке, как правило, доступны в документации API.
Общий алгоритм использования метода API может выглядеть следующим образом:
- настройка СЭО 3КL:
- подготовка веб-службы;
- подготовка пользователя для веб-службы;
- генерация ключа безопасности.
- создание запроса;
- отправка запроса;
- получение и обработка ответа.
2. Возможности
2.1. Документация API СЭО 3КL
Полный перечень функций (методов), которые могут быть использованы при интеграции по API доступны в интерфейсе СЭО 3КL на странице «Документация API» (Администрирование->Сервер->Веб-службы->Документация API) (Рис. 2.2.1).
Перечень методов выводится в алфавитном порядке. Название методов стандартизировано и формируется как
компонент_имя_метода (например, core_user_create_users), где
компонент — область применения метода (core_user),
имя_метода — выполняемое действие (create_users).
При клике на выбранном методе раскроется документация по нему, которая содержит (Рис. 2.2.2):
- Краткое описание метода (см. поз. 1 Рис. 2.2.2).
- Требуемые для функции аргументы (см. поз. 2 Рис. 2.2.2).
- Описание структуры с указанием переменных, их типов и передаваемых данных (параметров) (см. поз. 3 Рис. 2.2.2).
- Вид ответа на запрос (см. поз. 4 Рис. 2.2.2).
- Вид сообщения об ошибке (см. поз. 5 Рис. 2.2.2).
- Дополнительная информация (см. поз. 6 Рис. 2.2.2).
2.2. Использвание API на примере создания нового пользователя
Администратор настраивает СЭО 3КL для работы с веб-службами.
Администратор использует метод API core_user_create_users и, следуя документации API, формирует запрос (Рис. 2.2.1) к серверу СЭО 3КL, в котором указывает следующие данные для создаваемого пользователя:
Логин: testtestuser
Генерация пароля: да
Имя: Иван
Фамилия: Иванов
Email: testtestuser@test.dev
Дополнительное поле профиля типа mentor: 195
В СЭО СЭО 3КL создается пользователь с указанным в запросе логином, именем и фамилией. При этом, в соответствии с параметрами запроса, пароль для входа был автоматически сгенерирован системой и отправлен ему на электронную почту.
3. Предварительная настройка СЭО 3КLтребуются права администратора
Важно! Неосторожные действия полного администратора могут повредить систему и контент таким образом, что исправление последствий вмешательства выйдет за рамки гарантийной технической поддержки. В случае внесения правок в глобальные настройки рекомендуем вам полностью убедиться в том, что вы понимаете, за что отвечают данные настройки. Если у вас возникают сомнения в назначении глобальных настроек, обратитесь за помощью в техническую поддержку.
Подробная информация в статье «Полный административный доступ».
Для использования методов API, необходимо создать и настроить в СЭО 3КL веб-службу. Общая последовательность действий и ссылки на соответствующие интерфейсы настроек доступны на странице «Обзор» (Администрирование->Сервер->Веб-службы->Обзор) (Рис. 3.1).
3.1. Включение веб-служб и протоколов
Функционал веб-служб включается на странице администрирования «Расширенные возможности» (Рис. 3.1.1).
После того, как были включены веб-службы, необходимо убедиться, что на странице «Управление протоколами» (Администрирование->Сервер->Веб-службы->Управление протоколами) включены только те протоколы API, которые будут использоваться (Рис. 3.1.2). Те протоколы, которые не планируется использовать, рекомендуется отключить.
3.2. Создание пользователя для веб-службы
В СЭО 3КL должен быть создан специальный пользователь (далее - пользователь интеграции), от имени которого будет происходить взаимодействие со внешней системой (Администрирование->Пользователи->Учетные записи->Добавить пользователя->). Затем пользователю выдаются необходимые права — шаги 3, 4, 7 процедуры настройки (см. Рис. 2.1).
3.3. Создание веб-службы
В CЭО 3КL создается новая веб-служба (Администрирование->Сервер->Веб-службы->Внешние службы->кнопка «Добавить»), в которую включаются все необходимые для планируемой интеграции функции (Рис. 2.4) — шаги 5, 6 процедуры настройки (см. Рис. 2.1).
3.4. Создание ключа безопасности (токена)
Для ранее созданного пользователя интеграции на странице «Создать ключ» (Администрирование->Сервер->Веб-службы->Управление ключами->кнопка «Создать ключ») генерируется ключ безопасности (токен), при помощи которого скрипт интеграции будет получать доступ к веб-службе (Рис. 2.5, Рис. 2.6).
4. Решения
4.1. С
Теги: API