Инструменты WEB API в СЭО 3КL. Возможности и примеры
Если вы используете более раннюю версию системы — обратитесь с заявкой на проведение обновления в службу технической поддержки ООО «Открытые технологии».
1. Общая информация
2. Возможности
2.1. Создание
2.2. Документация API
2.3. П
3. Основные этапы предварительной настройки СЭО 3КL
3.1. С
3.2. С
3.3. П
4. Решения
1. Общая информация
Одним из вариантом взаимодействия внешних систем с СЭО 3КL является программный интерфейс приложений (API) - набор определенных способов и правил, позволяющий различным программным продуктам обмениваться данными по стандартизированным протоколам. API СЭО 3КL поддерживает обмен данными по протоколам REST, SOAP и XML-RPC.
Клиент API (непосредственно внешняя система или пользователь API через веб-браузер) обращается с запросом к серверу СЭО 3КL на выполнение функции API (Рис. 1.1). В зависимости от исполняемой функции, результатом запроса будет получение от сервера ответа с информацией из СЭО 3КL или какое-либо действие в системе.
Перед обработкой запроса выполняется аутентификация клиента API — сервер должен знать, кто делает запросы и имеет ли он на это право. Для этого запрос отправляется вместе с секретным ключом (токеном), который сгененрирован с использованием информации учетной записи пользователя API. Если запрос содержит валидный ключ, то сервер выполнит его обработку.
2. Возможности
2.1. Создание
Лучшие документации API представляют самостоятельную справку, которая сжато и точно объясняет, что возможно, а что нет, и с чего начать. Она также служит местом, к которому пользователи могут обращаться с вопросами о синтаксисе и функциональности. Несмотря на то, что от сайта к сайту она может отличаться, структура у всех документаций будет одинакова.
2.2. Документация API
Полный перечень функций (методов), которые могут быть использованы при интеграции по API доступны в интерфейсе СЭО 3КL на странице «Документация API» (Администрирование->Сервер->Веб-службы->Документация API).
3. Основные этапы предварительной настройки СЭО 3КLтребуются права администратора
Важно! Неосторожные действия полного администратора могут повредить систему и контент таким образом, что исправление последствий вмешательства выйдет за рамки гарантийной технической поддержки. В случае внесения правок в глобальные настройки рекомендуем вам полностью убедиться в том, что вы понимаете, за что отвечают данные настройки. Если у вас возникают сомнения в назначении глобальных настроек, обратитесь за помощью в техническую поддержку.
Подробная информация в статье «Полный административный доступ».
Для применения описанных ниже методов API, необходимо создать и настроить в СЭО 3КL веб-службу. Последовательность действий и ссылки на соответствующие интерфейсы настроек доступны на странице «Обзор» (Администрирование->Сервер->Веб-службы->Обзор) (Рис. 2.1).
Общий алгоритм действий следующий:
1) В СЭО 3КL включается функционал веб-служб (Рис. 2.2) и необходимые протоколы API (Рис. 2.3) — шаги 1, 2 процедуры настройки (см. Рис. 2.1).
2) В СЭО 3КL создается специальный пользователь (далее - пользователь интеграции), от имени которого будет происходить взаимодействие со внешней системой (Администрирование->Пользователи->Учетные записи->Добавить пользователя->). Пользователю выдаются необходимые права — шаги 3, 4, 7 процедуры настройки (см. Рис. 2.1).
3) В CЭО 3КL создается новая веб-служба (Администрирование->Сервер->Веб-службы->Внешние службы->кнопка «Добавить»), в которую включаются все необходимые для планируемой интеграции функции (Рис. 2.4) — шаги 5, 6 процедуры настройки (см. Рис. 2.1).
4) Для ранее созданного пользователя интеграции на странице «Создать ключ» (Администрирование->Сервер->Веб-службы->Управление ключами->кнопка «Создать ключ») генерируется ключ безопасности (токен), при помощи которого скрипт интеграции будет получать доступ к веб-службе (Рис. 2.5, Рис. 2.6)— шаги 8 процедуры настройки (см. Рис. 2.1).
3.1. С
3.2. С
4. Решения
3.1. Создание и редактирование настроек критериев завершения курса
Название функции: local_opentechnololgy_edit_completion_criteria
Протокол: REST
Структура и параметры:
list of (
object {
id int //Идентификатор курса, обязательный параметр
overall_aggregation int //Общее условие завершения курса, 1 - все условия должны быть завершены, 2 - любое условие должно быть завершено, обязательный параметр
settingsunlock int По умолчанию - «0» //Флаг разблокировки текущих настроек критериев выполнения (0 или 1, при передаче значения 1 будут удалены текущие настройки и очищены текущие данные пользователей по выполнению курса, если передан 0 и настройки заблокированы, никаких изменений не произойдёт, переданные данные будут проигнорированы)
clearcriteria int По умолчанию - «0» //Флаг удаления текущих настроек критериев выполнения (0 или 1, при передаче значения 1 текущие настройки завершения курса будут полностью заменены на переданные, если передан 0, будут заменены или добавлены только переданные данные)
criteria_activity Необязательно //Список модулей курса
list of (
object {
cmid int //Идентификатор модуля курса
value int По умолчанию - «0» //Значение 0 или 1
}
)activity_aggregation int Необязательно //Условие для критерия завершения элементов курсов, 1 - все элементы курса должны быть завершены, 2 - любой элемент курса должен быть завершён
criteria_course Необязательно //Список курсов
list of (
object {
courseid int //Идентификатор курса
}
)course_aggregation int Необязательно //Условие для критерия завершения других курсов, 1 - все курсы должны быть завершены, 2 - любой курс должен быть завершён
criteria_date int Необязательно //Флаг включения критерия завершения курса по дате
criteria_date_value int По умолчанию - «1704966463» //Значение даты (timestamp) критерия завершения курса по дате
criteria_duration int Необязательно //Флаг включения критерия завершения курса по продолжительности зачисления
criteria_duration_days int По умолчанию - «86400» //Значение периода зачисления в секундах
criteria_grade int Необязательно //Флаг включения критерия завершения курса по оценке за курс
criteria_grade_value double По умолчанию - «0» //Оценка типа float с учётом локали
criteria_role Необязательно //Список ролей для завершения курса за другого
list of (
object {
roleid int //Идентификатор роли
}
)role_aggregation int Необязательно //Условие для критерия завершения курса за другого, 1 - все роли должны поставить отметку о выполнении, 2 - любая роль должна поставить отметку о выполнении
criteria_self int Необязательно //Флаг включения критерия завершения курса по самостоятельной отметке
criteria_unenrol int Необязательно //Флаг включения критерия завершения курса по исключению из курса
}
)
Пример: completion_criteria.php
Приведенный в примере код очищает существующие условия завершения в курсе с id=81 и определяет, что курс будет считаться завершенным, когда любое из нижеперечисленных условий будет выполнено:
- выполнен элемент курса с id=1392 (финальный тест в курсе);
- курс с id=16 отмечен как завершенный;
- курс отмечен как завершенный через 10 дней с момента запуска скрипта;
- слушатель остается зачисленным на курс на протяжении 10 дней;
- слушатель исключен из курса;
- оценка слушателя более 50 баллов;
- слушатель самостоятельно завершил курс (для реализации этой возможности в курсе должен быть настроен блок «Самостоятельное отслеживание завершения»);
- пользователь с ролью id=3 (в нашем примере — преподаватель) завершил курс за слушателя.
3.2. Создание достижений по шаблону типа «Настраиваемый»
Название функции: block_dof_storage_achievementins_create
Протокол: REST
Структура и параметры:
list of (
object {
achievementid int //Идентификатор шаблона достижений, обязательный параметр
personid int //Идентификатор персоны деканата, для которой создаётся достижение, обязательный параметр
goaldeadline int Необязательно //Дата дедлайна цели (timestamp) (по умолчанию null)
data //Значения критериев достижения, обязательный параметр
list of (
object {
criterianum int //Номер критерия достижения (0, 1, 2, ...)
criteriavalue string //Значение критерия
criteriaoptions Необязательно //Дополнительные опции критерия
list of (
object {
optionnum int //Номер опции критерия (0, 1, 2, ...)
optionname string //Значение опции критерия
optionvalue string //Имя опции критерия
}
)}
)options Необязательно //Дополнительные опции создания достижений
object {
create_goal int Необязательно //Флаг необходимости создания цели (0 или 1)
}
}
)
Пример:
3.3. Получение персоны деканата по идентификатору пользователя системы
Название функции: block_dof_storage_persons_get_bu
Протокол: REST
Структура и параметры:
Пример:
Возможности - с помощью веб апи вы сможете то-то и то-то
Настройка -создание ключей, пользователей - выделить в подразделы, чтобы можно было быстро перейти из оглавления
быстрый старт - объяснение и примеры, как это работает в целом, простые примеры.
Возможно нужен раздел, как читать документацию по апи - там разъяснить, как находить и сейчас мы на примере разберем, что вы там увидите и как этим пользоваться
возможно (если наберется информация) - заметки по отдельным функциям - если есть инфа, сверх того, что есть в документации
примеры и решения - с кодом, которые сделали программисты для наших функций
Теги: API