moodle-external-api-development

Moodle 外部 API 开发

本技能将指导你为 Moodle LMS 创建自定义外部 Web 服务 API，并遵循 Moodle 的外部 API 框架和编码标准。

详细指南

执行此技能前，请阅读详细指南。该指南保留了完整的流程和参考资料。必须遵守其中的安全要求、前置条件和验证要求。若要处理特定任务，请加载相关章节；若要完成端到端任务，请通读整份指南。

何时使用此技能

• 为 Moodle 插件创建自定义 Web 服务
• 为课程管理实现 REST/AJAX 端点
• 为测验操作、用户跟踪或报告构建 API
• 向外部应用公开 Moodle 功能
• 使用 Moodle 开发移动应用后端

示例实现片段

简单读取 API（获取测验尝试记录）

<?php
namespace local_userlog\external;

defined('MOODLE_INTERNAL') || die();
require_once("$CFG->libdir/externallib.php");

use external_api;
use external_function_parameters;
use external_single_structure;
use external_value;

class get_quiz_attempts extends external_api {
    public static function execute_parameters() {
        return new external_function_parameters([
            'userid' => new external_value(PARAM_INT, 'User ID'),
            'courseid' => new external_value(PARAM_INT, 'Course ID')
        ]);
    }

    public static function execute($userid, $courseid) {
        global $DB;

        $params = self::validate_parameters(self::execute_parameters(), [
            'userid' => $userid,
            'courseid' => $courseid
        ]);

        $context = \context_course::instance($params['courseid']);
        self::validate_context($context);
        require_capability('mod/quiz:viewreports', $context);
        // Instructor-report endpoint; add group/quiz-specific visibility restrictions as needed.

        $sql = "SELECT COUNT(*) AS quiz_attempts
                FROM {quiz_attempts} qa
                JOIN {quiz} q ON qa.quiz = q.id
                WHERE qa.userid = :userid AND q.course = :courseid";

        $attempts = $DB->get_field_sql($sql, [
            'userid' => $params['userid'],
            'courseid' => $params['courseid']
        ]);

        return ['quiz_attempts' => (int)$attempts];
    }

    public static function execute_returns() {
        return new external_single_structure([
            'quiz_attempts' => new external_value(PARAM_INT, 'Total number of quiz attempts')
        ]);
    }
}

复杂写入 API（根据分类创建测验）

文中引用的 create_quiz_from_categories.php 未随附。不得声称已阅读、执行或进行过事务测试。请使用已安装 Moodle 版本的活动和试题 API，并进行上下文和能力检查、群组可见性检查、输入边界限制及回滚测试；指南中的直接插入片段是对历史架构的说明，并非完整的测验构建器。测试时使用遵循最小权限原则的角色和合成的学习者数据，切勿在 shell 参数中使用生产环境管理员令牌。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要输入、权限、安全边界或成功标准，请停止并请求澄清。