StepikApiClient 2.2.0

StepikApiClientLibrary

Неофициальная клиентская библиотека для работы со Stepik.org API на .NET.

Содержание

• Описание
• Установка
• Быстрый старт
• Доступные клиенты
• Примеры использования
• Обработка ошибок
• Конфигурация
• LongTask
• Версионирование
• Лицензия

Описание

Библиотека предоставляет типизированный .NET-клиент для Stepik.org API, позволяя работать с курсами, уроками, шагами, решениями, пользователями и другими ресурсами платформы. Аутентификация выполняется через OAuth2 Client Credentials. Библиотека ориентирована на .NET 9 и использует Newtonsoft.Json для сериализации.

Пакет StepikApiClient содержит клиентскую логику и зависит от StepikApiClient.Models, в котором хранятся все модели данных Stepik API.

Установка

Полный клиент (включает модели)

dotnet add package StepikApiClient

Только модели

dotnet add package StepikApiClient.Models

StepikApiClient автоматически подтягивает StepikApiClient.Models как зависимость — устанавливать оба пакета вручную не нужно.

Быстрый старт

1. Получите OAuth2-реквизиты

Создайте приложение на https://stepik.org/oauth2/applications/ и скопируйте Client ID и Client Secret.

2. Зарегистрируйте клиент в DI

// Program.cs
builder.Services.AddStepikApiClient(options =>
{
    options.ClientId = Environment.GetEnvironmentVariable("STEPIK_CLIENT_ID");
    options.ClientSecret = Environment.GetEnvironmentVariable("STEPIK_CLIENT_SECRET");
});

3. Внедрите IApiClient и выполните первый запрос

public class MyService
{
    private readonly IApiClient _client;

    public MyService(IApiClient client)
    {
        _client = client;
    }

    public async Task<Course?> GetCourseAsync(int id)
    {
        return await _client.Courses.GetAsync(id);
    }
}

Доступные клиенты

Все клиенты доступны как свойства интерфейса IApiClient.

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

Курсы

// Получить курс по ID
var course = await _client.Courses.GetAsync(courseId);

// Получить все курсы преподавателя
var courses = await _client.Courses.GetByTeacher(teacherId);

// Обновить курс
await _client.Courses.Update(course);

Разделы и юниты

// Получить разделы курса в виде потока
await foreach (var section in _client.Sections.GetByCourseAsync(course))
{
    Console.WriteLine(section.Title);
}

// Получить юниты раздела
var units = await _client.Units.GetBySectionAsync(section);

Уроки и шаги

// Получить уроки курса
var lessons = await _client.Lessons.GetLessonsAsync(courseId);

// Получить шаги урока по ID
var steps = await _client.Steps.GetByLessonId(lessonId.ToString());

Источники шагов

// Получить источники шагов урока
var stepSources = await _client.StepSources.GetByLessonId(lessonId);

// Обновить источник шага
var updated = await _client.StepSources.Update(stepSource);

// Создать источник шага
var created = await _client.StepSources.Create(stepSource);

Решения (Submissions)

// Загрузить все решения по шагу в виде потока
await foreach (var submission in _client.Submissions.LoadAllByStepAsync(stepId, cancellationToken))
{
    Console.WriteLine($"{submission.UserId}: {submission.Status}");
}

// Получить решения начиная с даты
await foreach (var submission in _client.Submissions.GetAllByStepAsync(stepId, fromDate, cancellationToken))
{
    // ...
}

Пользователи

// Получить пользователя по ID
var user = await _client.Users.GetAsync(userId);

// Получить всех пользователей группы
var users = await _client.Users.GetAllFromGroup(groupId, cancellationToken);

// Получить пользователей по списку ID в виде потока
await foreach (var user in _client.Users.GetUsersByIdsAsync(ids, cancellationToken))
{
    // ...
}

Комментарии

// Получить все комментарии к шагу
await foreach (var comment in _client.Comments.GetAllByStep(stepId, cancellationToken))
{
    Console.WriteLine(comment.Text);
}

// Комментарии к курсу начиная с даты
await foreach (var comment in _client.Comments.GetByCourse(courseId, targetDate, cancellationToken))
{
    // ...
}

Участники групп

// Получить всех участников группы в виде потока
await foreach (var member in _client.Members.GetMembersByGroupIdAsync(groupId, cancellationToken))
{
    Console.WriteLine(member.UserId);
}

// Добавить пользователя в группу
var member = await _client.Members.AssignToGroup(groupId, userId);

// Добавить пользователя в несколько групп
var success = await _client.Members.AssignToGroups(groupIds, userId);

Отзывы на курс

// Загрузить все отзывы в виде потока
await foreach (var review in _client.CourseReviews.GetAllByCourse(courseId, cancellationToken))
{
    Console.WriteLine(review.Text);
}

// Отзывы начиная с даты
await foreach (var review in _client.CourseReviews.GetLastByCourse(courseId, startDate, cancellationToken))
{
    // ...
}

Сертификаты

// Получить сертификаты курса в виде потока страниц
await foreach (var page in _client.Certificates.GetByCourse(courseId, cancellationToken))
{
    foreach (var cert in page)
        Console.WriteLine(cert.UserId);
}

// Найти сертификат конкретного пользователя по курсу
var cert = await _client.Certificates.GetByUserAndCourse(userId, courseId, cancellationToken);

Промокоды

// Получить промокоды курса
var codes = await _client.PromoCodes.GetPromoCodes(courseId);

// Создать промокод
var created = await _client.PromoCodes.Create(new CreatePromoCode { ... });

Выплаты (CourseBenefits)

// Выплаты начиная с даты
await foreach (var page in _client.CourseBenefits.GetByCourseAsync(courseId, startDate, cancellationToken))
{
    foreach (var benefit in page)
        Console.WriteLine(benefit.Amount);
}

// Выплаты по месяцам
await foreach (var page in _client.CourseBenefits.GetCourseBenefitByMonths(courseId, cancellationToken))
{
    // ...
}

История шагов (StepSnapshots)

// Получить историю изменений шага
await foreach (var snapshot in _client.StepSnapshots.GetSnapshots(stepId, cancellationToken))
{
    Console.WriteLine(snapshot.CreateDate);
}

Обработка ошибок

try
{
    var course = await _client.Courses.GetAsync(courseId);
}
catch (NotFoundException ex)
{
    Console.WriteLine($"Не найден: {ex.ObjectType.Name} id={ex.Id}");
}
catch (BadRequestException ex)
{
    Console.WriteLine($"Ошибка API [{(int)ex.StatusCode}]: {ex.ResponseMessage}");
    Console.WriteLine($"Эндпоинт: {ex.Endpoint}");
}

Конфигурация

Конфигурация передаётся через StepikApiConfiguration при регистрации сервиса.

builder.Services.AddStepikApiClient(options =>
{
    options.ClientId = Environment.GetEnvironmentVariable("STEPIK_CLIENT_ID");
    options.ClientSecret = Environment.GetEnvironmentVariable("STEPIK_CLIENT_SECRET");
});

Значения рекомендуется хранить в переменных окружения или в secrets.json — не в исходном коде.

LongTask

Некоторые операции Stepik API (например, генерация отчётов) выполняются асинхронно на стороне сервера и возвращают объект LongTask. Клиент LongTasks позволяет отправить запрос и дождаться его завершения.

// Отправить запрос на выполнение задачи
var task = await _client.LongTasks.SendRequest(courseId, "submissions_report");

if (task is not null)
{
    // Ожидать завершения с тайм-аутом и токеном отмены
    var result = await _client.LongTasks.GetAsync(
        task.Id,
        timeout: TimeSpan.FromMinutes(2),
        cancellationToken: cts.Token
    );

    if (result?.Status == "ready")
    {
        Console.WriteLine(result.Tag); // URL или идентификатор результата
    }
}

Если задача не завершается за время timeout, выбрасывается OperationCanceledException.

Версионирование

Пакеты StepikApiClient и StepikApiClient.Models версионируются независимо и следуют Semantic Versioning.

Лицензия

Распространяется под лицензией MIT.