Регистрация ученика в кабинете и открытие доступа к курсам
1. grantAccess — универсальный метод, который позволяет:
- регистрировать учеников
- изменять доступы к курсам существующим ученикам
- одновременно регистрировать учеников и задавать им доступы к курсам
Перед выполнением запроса рекомендуем сначала получить список id курсов с помощью запроса getlist
Запрос: POST
Тип: application/json
Адрес: https://online.bizon365.ru/api/v2/XXXX/student/grantAccess, где XXXX - номер проекта
Тело запроса должно быть JSON-структурой, образец:
{
students: [ {...}, {...}, ... ],
autoCreate: true|false,
script: [ { "cmd": ... }, { "cmd": .... } ],
callback: "http://my.site/api-webhook"
}, где
- students
массив объектов — "students": [ {...}, {...} ]
Каждый объект может содержать поля*:
- email
валидный e-mail ученика - username
ФИО ученика - phone
номер телефона - city
город
* если ученик с данным e-mail уже зарегистрирован в ваших курсах или курсах другого автора и в его профиле заполнены поля ФИО, номер телефона и город, то при выполнении запроса они не будут заменены новым значением.
Поля username, phone, city имеет смысл указывать, только если нужно создать ученика (включен параметр autoCreate: true ). В противном случае их можно опустить.
- autoCreate
флаг, предписывающий (если true) создавать учеников, если они не существуют. - script
массив команд cmd с обязательным параметром id (id курса) — [ { "cmd": ... }, { "cmd": .... } ]
Значения cmd:
- on
включить доступ к курсу id — { "cmd": "on", "id": "...." }
Дополнительные параметры:
— class — номер потока (начиная с 1)
— fl (first lessons) — кол-во доступных первых уроков — “fl”: “0” - доступ ко всем урокам
— starts — открытие доступа в указанную дату. Дата задается в формате ISO: например, 2021-05-10T10:00:00 (по умолчанию будет UTC+3).
— starts_in_days — открытие доступа через указанное количество дней относительно текущего момента.
Время в обоих случаях отложенного доступа будет округляться до ближайшего начала часа, пропуская время с 19:00 до 21:00 мск.
- ma (manual access)
изменить срок окончания доступа к курсу id на значение expires —
{ "cmd": "ma", "id": "....", "expires": "ISODate" }
Значение expires задается в формате ISO. Например, 2021-05-05T21:00:00 - что соответствует 21:00 мск 05.05.21.
Пустое значение expires установит бессрочный доступ — { "cmd": "ma", "id": "....", "expires": "" }
Дополнительные параметры*:
— class — номер потока (начиная с 1)
— fl — количество доступных первых уроков (“fl”: “0” - доступ ко всем урокам)
* применять данные параметры в команде ma нужно с осторожностью. Вы должны быть уверены, что учеником / учениками к этому моменту не пройдено большее количество уроков, чем будет задано в команде. Также обратите внимание, что смена потока может сделать недоступными предыдущие комментарии, оставленные учеником в предыдущем потоке.
- freeze
заморозить доступ к курсу id — { "cmd": "freeze", "id": "...."}
Доступ будет заморожен бессрочно.
Заморозка на определенное количество часов или дней задается параметром hours или days, соответственно. - unfreeze
разморозить доступ к курсу id — { "cmd": "unfreeze", "id": "...." } - off
выключить доступ к курсу id — { "cmd": "off", "id": "...." } - off!
убрать окончательно доступ к курсу id — { "cmd": "off!", "id": "...." }
В одной команде cmd указывается id одного курса. В массиве script может быть любое количество команд cmd.
Пустой script ("script": "") используется только если в теле запроса включен параметр autoCreate (ссылка на описание параметра) - добавляет учеников без открытия доступов к курсу.
Параметр script может использоваться как для всего массива students - “глобальный script”, так и для каждого из объектов массива в отдельности - “индивидуальный script”.
Пример:
{
students: [{"email": "student1@.com", "script": [{"cmd": "on", "id": "kurs1"}]},
{"email": "student2@.com"}, {"email": "student3@.com"}],
script: [{ "cmd": "on", "id": "kurs2" }]
}
Доступ к kurs2 будет открыт всем трем ученикам, указанным в массиве students, а доступ к kurs1 - только первому ученику.
- callback
параметр задаётся, если требуется webhook о завершении выполнения задачи — "callback": "http://…."
Должен быть указан валидный URL, начинающийся на http. На указанный адрес будет сделан POST-запрос с содержимым:
{
errors: [],
}
Массив errors будет пустым, если ошибок не возникло.
Если же ошибки возникли, то массив errors будет содержать объекты вида:
{ email: "abc@xyz", error: "текст ошибки" }.
Метод grantAccess только ставит задачу в очередь, а непосредственное управление доступами будет происходить в фоновом режиме.
Сервер возвращает ответ в виде JSON следующего формата:
{
"status": "queued",
"message": "Задача добавлена в очередь.",
"task_id": "id задачи"
}, где
- status
статус задачи со значением "queued" - message
сообщение о статусе задачи "Задача добавлена в очередь" - task_id
id задачи - присваивается системой в момент выполнения запроса.
Время выполнения задачи будет зависеть от состояния системы - общей нагрузки и количества различных отправляемых запросов в системе. Чтобы узнать, в каком состоянии находится задача, используется следующий запрос.
2. checkTaskStatus - проверка состояния запроса task_id метода grantAccess
Запрос: GET
Адрес: https://online.bizon365.ru/api/v2/XXXX/student/checkTaskStatus?task_id=..., где XXXX - номер проекта
Запрос в ответ возвращает объект с полем status: {"status": "..."}
Возможные значения status:
- not_found
задача не найдена. Если id указан верно, то обычно это значит что задача успешно выполнена и удалена из очереди - running
задача в процессе выполнения - in_queue
задача еще в очереди - failed
завершено с ошибкой. Задача еще в очереди, возможно повторение попытки.