Готовый REST API Moodle закрывает типовые задачи: записать на курс, получить оценки. Но у собственного плагина есть данные, к которым стандартные функции не имеют отношения: ведомости, статусы документов, записи в служебных таблицах. Чтобы отдать их во внешнюю систему, в Moodle не нужно писать отдельный PHP-скрипт с самодельной авторизацией. Достаточно объявить функцию в External API, и протокол, токены, проверка параметров и документация приложатся сами. Про использование готового API есть отдельная статья, здесь речь о создании своего.
Из чего состоит внешняя функция
Функция веб-сервиса — это класс с тремя статическими методами и запись о нём в db/services.php. Схема работы такая: внешняя система обращается к серверу по протоколу (чаще REST), указывает токен и имя функции; Moodle проверяет токен, проверяет и очищает параметры по описанию, вызывает ваш execute() и приводит результат к описанному в execute_returns().
| Элемент | Где находится | Для чего |
|---|---|---|
execute_parameters() | classes/external/*.php | Описывает входные параметры и их типы |
execute() | тот же класс | Выполняет работу, проверяет права |
execute_returns() | тот же класс | Описывает структуру ответа |
запись в $functions | db/services.php | Регистрирует функцию в системе |
запись в $services | db/services.php | Необязательно: готовый сервис с набором функций |
Спецификация — на странице External functions API.
Пишем функцию
Пример: вернуть по идентификатору слушателя список его документов из таблицы плагина. Пространство имён и базовый класс в Moodle 4.2 и новее — core_external; в более старых версиях тот же набор классов жил в глобальном пространстве имён (external_api, external_value), поэтому для плагина, который должен работать на разных версиях, выбирайте то, что есть в целевых релизах.
namespace local_example\external;
defined('MOODLE_INTERNAL') || die();
use core_external\external_api;
use core_external\external_function_parameters;
use core_external\external_multiple_structure;
use core_external\external_single_structure;
use core_external\external_value;
class get_documents extends external_api {
public static function execute_parameters(): external_function_parameters {
return new external_function_parameters([
'userid' => new external_value(PARAM_INT, 'ID пользователя'),
]);
}
public static function execute(int $userid): array {
global $DB;
$params = self::validate_parameters(self::execute_parameters(), ['userid' => $userid]);
$context = \context_system::instance();
self::validate_context($context);
require_capability('local/example:viewdocuments', $context);
$rows = $DB->get_records('local_example_doc', ['userid' => $params['userid']]);
$result = [];
foreach ($rows as $row) {
$result[] = ['id' => (int)$row->id, 'name' => $row->name, 'status' => $row->status];
}
return $result;
}
public static function execute_returns(): external_multiple_structure {
return new external_multiple_structure(
new external_single_structure([
'id' => new external_value(PARAM_INT, 'ID документа'),
'name' => new external_value(PARAM_TEXT, 'Название'),
'status' => new external_value(PARAM_ALPHANUMEXT, 'Статус'),
])
);
}
}
Три момента, на которых новички чаще всего спотыкаются. Первый: validate_parameters() обязателен, он очищает входные значения по заявленным типам. Второй: validate_context() и require_capability() — это ваша ответственность, ядро не знает, какие права нужны вашим данным. Третий: ответ должен точно соответствовать execute_returns(). Лишние поля отбрасываются, а недостающие обязательные дают ошибку.
Типы параметров
Тип в external_value — это обычные константы PARAM_* Moodle. От выбора зависит очистка значения:
| Тип | Что пропустит | Когда брать |
|---|---|---|
PARAM_INT | Целое число | Идентификаторы, количества |
PARAM_FLOAT | Число с плавающей точкой | Оценки, суммы |
PARAM_BOOL | Логическое | Флаги |
PARAM_TEXT | Текст без HTML-тегов, кроме разрешённых для многоязычности | Названия, имена |
PARAM_RAW | Без очистки | Только когда очистка невозможна; проверяйте сами |
PARAM_ALPHANUMEXT | Буквы, цифры, подчёркивание и дефис | Коды, статусы, шорт-имена |
PARAM_EMAIL | Адрес электронной почты | Почта |
PARAM_URL | Адрес сайта | Ссылки |
Обязательность задаёт четвёртый аргумент: VALUE_REQUIRED, VALUE_OPTIONAL или VALUE_DEFAULT (с значением по умолчанию). Для массивов объектов используют external_multiple_structure с вложенным external_single_structure, как в примере. Правило: чем уже тип, тем меньше работы по защите. Тип PARAM_RAW без собственной проверки на входе в SQL или вывод — дыра.
Регистрация в db/services.php
defined('MOODLE_INTERNAL') || die();
$functions = [
'local_example_get_documents' => [
'classname' => \local_example\external\get_documents::class,
'description' => 'Список документов пользователя',
'type' => 'read',
'ajax' => false,
'capabilities' => 'local/example:viewdocuments',
],
];
$services = [
'Example integration' => [
'functions' => ['local_example_get_documents'],
'restrictedusers' => 1,
'enabled' => 1,
'shortname' => 'example_integration',
],
];
Имя функции принято начинать с имени компонента, чтобы не пересечься с другими. Поле type различает чтение и запись (read, write): от него зависят некоторые клиенты и режимы только для чтения. Параметр ajax разрешает вызывать функцию из браузера интерфейса Moodle, для чисто серверной интеграции он не нужен. restrictedusers означает, что сервисом смогут пользоваться только пользователи, которым администратор его разрешил явно. Для интеграций это правильный режим.
Поменяли services.php: поднимите версию в version.php и пройдите обновление, иначе Moodle продолжит работать со старым списком функций.
Включение, токен и вызов
- В «Дополнительные возможности» включите веб-службы, затем в «Сервер → Веб-службы → Управление протоколами» включите REST.
- Создайте отдельного пользователя для интеграции и роль с минимумом прав: использование протокола и права, нужные вашей функции.
- В «Внешние службы» откройте свой сервис, добавьте в «Авторизованные пользователи» созданного пользователя.
- В «Управление токенами» создайте токен на этого пользователя и сервис, укажите срок и разрешённые IP-адреса.
- Вызовите функцию:
curl -X POST "https://sdo.example.ru/webservice/rest/server.php" \
-d "wstoken=ТОКЕН" \
-d "wsfunction=local_example_get_documents" \
-d "moodlewsformat=json" \
-d "userid=42"
Вызывайте по POST: токен в строке запроса GET оседает в логах веб-сервера и прокси. Если токен «утёк», его удаляют на странице управления, и интеграция перестаёт работать немедленно, а остальные сервисы не затронуты.
Ошибки и безопасность
- «Invalid parameter value detected». Передан параметр неверного типа или отсутствует обязательный. Сверяйте имена с
execute_parameters(). - «Access control exception». У пользователя токена нет права, которое проверяет
require_capability(), или он не добавлен в авторизованные пользователи сервиса. - Функция не найдена. Не пройдено обновление после правки
services.php. - Лишние данные в ответе. Не отдавайте то, что внешней системе знать не нужно: почту, телефоны, паспортные данные. Это персональные данные, а значит, речь идёт и о соответствии 152-ФЗ.
Не принимайте массовых операций без ограничения числа записей, а для изменяющих функций ведите журнал: событие в Events API даёт его почти бесплатно.
Ошибки, постраничная выдача и версии
Если что-то пошло не так, бросайте \moodle_exception с кодом ошибки из языкового файла плагина: клиент получит ответ с полями exception, errorcode и message. Не возвращайте в ответе текст ошибки вместо данных: интеграционному коду проще различить исключение и пустой результат. Для необязательных значений укажите в описании поля VALUE_OPTIONAL или допустите NULL_ALLOWED, иначе пустое значение даст ошибку проверки ответа.
Функции, возвращающие списки, делайте с ограничением: параметры limit и offset и жёсткий потолок на сервере. Внешняя система без ограничения однажды запросит все записи за пять лет, и PHP упрётся в память. Записывающие функции должны быть идемпотентными: повторный вызов с тем же внешним идентификатором не создаёт дубль. Сеть ненадёжна, клиент повторит запрос, и защита от этого лежит на вас.
Менять сигнатуру уже работающей функции не нужно: у внешней системы есть код, который на неё опирается. Добавляйте необязательные параметры или новую функцию с другим именем. На странице «Сервер → Веб-службы → Документация API» Moodle автоматически показывает описание всех включённых функций из ваших execute_parameters() и execute_returns(), и это готовая спецификация для разработчика на другой стороне: пишите описания полей внятно.
Тестировать функцию удобно без HTTP. В PHPUnit вызывайте get_documents::execute() от имени тестового пользователя, а результат пропускайте через external_api::clean_returnvalue() с вашим execute_returns(): так проверяется и логика, и соответствие описанию ответа.
Защита: угроза и мера
| Угроза | Мера |
|---|---|
| Утечка токена | Передача по POST и только по HTTPS, срок действия, ограничение по IP, быстрый отзыв в управлении токенами |
| Избыточные права интеграции | Отдельный пользователь с узкой ролью, а не администратор |
| Выдача лишних данных | Возвращать только поля, нужные внешней системе, по описанию в execute_returns() |
| Подбор идентификаторов | Проверять не только право роли, но и принадлежность записи, с которой работают |
| Перегрузка выборкой | Параметры limit/offset и потолок размера страницы на сервере |
| Повторы запросов | Идемпотентные функции записи с внешним идентификатором |
Когда без собственной функции не обойтись
Типовая картина в интеграциях с сайтами колледжей, 1С или Битрикс24: стандартные функции Moodle умеют записать пользователя и вернуть оценки по курсу, но не знают о ваших таблицах. Внешней системе нужен, например, статус проверки документа слушателя или признак «ведомость закрыта». Пытаться вытащить это через сочетание стандартных вызовов хрупко и медленно, а прямой доступ к базе Moodle из внешней системы закрывает любая политика безопасности. Своя функция делает ровно один понятный вызов и возвращает ровно то, что нужно. Заодно вы получаете единое место, где проверяются права, и единое место, где можно отключить интеграцию.
Если за функцию отвечает не тот, кто её писал, сразу договоритесь о двух вещах: кто отзывает токен при подозрении на утечку и кто смотрит на ошибки вызовов в журнале. Иначе интеграция работает, пока не сломается, а потом выясняется, что никто не знает, какой системе принадлежит токен.
Когда это проще, чем писать отдельный скрипт
Свой PHP-файл с токеном «в коде» кажется быстрее, но придётся самостоятельно решать, как хранить ключ, как его отозвать, как ограничить права и как проверять входные данные. External API делает всё это стандартными средствами и показывается в списке сервисов, что облегчает передачу проекта другому специалисту. Разные системы (1С, сайт колледжа, Битрикс24) подключаются одним и тем же способом. Типовые схемы описаны на странице про интеграцию Moodle с 1С, а если нужна функция под вашу задачу, её можно заказать в рамках разработки плагина.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.