Методы

Методы сайта https://dict.orfogrammka.ru/

Запрос

POST https://dict.orfogrammka.ru/api/customer/dictInfo

GET https://dict.orfogrammka.ru/api/customer/dictInfo

Параметры:

id — идентификатор диктовки;
customer-id — идентификатор клиента;
time — текущее время в формате Unix time. Если в момент обработки на сервере время отличается более, чем на 6 часов, то в ответе будет 403 ошибка.
signature — подпись ключом клиента вычисляется как md5 от конкатенации параметров + секретный ключ клиента: md5(id + customer-id + time + secretKey).

Ответ

200 OK
{
	/**
	 * Идентификатор диктанта в системе dict.orfogrammka.ru
	 */
	dictId: String,
	/**
	 * Идентификатор диктовки в системе dict.orfogrammka.ru.
	 * Теоретически на один диктант может быть несколько диктовок
	 * от разных дикторов, но пока у нас всегда одна диктовка на диктант.
	 */
	mediaId: String,
	/**
	 * Название диктанта (для словарных и тематических нет названия)
	 */
	title? : String,
	/**
	 * Описание диктанта
	 */
	description: String,
	/**
	 * Автор текста диктанта (может быть не указан)
	 */
	author? : String,
	/**
	 * Имя диктора, который начитывал диктовку
	 */
	dictor: String,
	/**
	 * Количество слов в диктанте
	 */
	wordCount: Long,
	/**
	 * Тип диктанта:
	 * REGULAR (обычный диктант),
	 * THEMATIC (тематический диктант),
	 * WORDS (словарный диктант)
	 */
	kind: String,
	/**
	 * Язык диктанта (RUSSIAN)
	 */
	language: String
}

Возможные коды ошибок: 401, 403, 404.

Запрос

POST https://dict.orfogrammka.ru/api/customer/checkScript

GET https://dict.orfogrammka.ru/api/customer/checkScript

Параметры:

id — идентификатор диктовки;
customer-id — идентификатор клиента;
time — текущее время в формате Unix time. Если в момент обработки на сервере время отличается более, чем на 6 часов, то в ответе будет 403 ошибка.
signature — подпись ключом клиента вычисляется как md5 от конкатенации параметров + секретный ключ клиента: md5(id + customer-id + time + secretKey).

Ответ

200 OK

Content-Type: application/javascript

Тело javascript-файла с функцией проверки диктанта.

В http-заголовках ответа возвращаются данные:

timestamp — время последнего изменения разметки диктанта;
dictId — идентификатор диктанта в системе dict.orfogrammka.ru.

Возможные коды ошибок: 401, 403, 404.

Запрос

POST https://dict.orfogrammka.ru/api/customer/playerScript

GET https://dict.orfogrammka.ru/api/customer/playerScript

Параметры:

id — идентификатор диктовки;
customer-id — Идентификатор клиента;
time — текущее время в формате Unix time. Если в момент обработки на сервере время отличается более, чем на 6 часов, то в ответе будет 403 ошибка.
signature — подпись ключом клиента вычисляется как md5 от конкатенации параметров + секретный ключ клиента: md5(id + customer-id + time + secretKey).

Ответ

200 OK

Content-Type: application/javascript

Тело javascript-файла с функцией управления проигрывателем кусочков аудиофайлов диктовки.

Возможные коды ошибок: 401, 403, 404.

Запрос

POST https://dict.orfogrammka.ru/api/customer/playerVendorScript

GET https://dict.orfogrammka.ru/api/customer/playerVendorScript

Параметры:

id — идентификатор диктовки;
customer-id — Идентификатор клиента;
time — текущее время в формате Unix time. Если в момент обработки на сервере время отличается более, чем на 6 часов, то в ответе будет 403 ошибка.
signature — подпись ключом клиента вычисляется как md5 от конкатенации параметров + секретный ключ клиента: md5(id + customer-id + time + secretKey).

Ответ

200 OK

Content-Type: application/javascript

Тело javascript-файла вспомогательной библиотеки для скрипта диктовки (она не зависит от диктанта и всегда одинаковая).

Возможные коды ошибок: 401, 403.

Запрос

GET https://dict.orfogrammka.ru/api/media-file/<media_id>/<file_id>.mp3

Параметры только в теле URL'а:

<media_id> — идентификатор диктовки в системе dict.orfogrammka.ru;
<file_id> — идентификатор файла, который запрашивает скрипт диктовки.

Ответ

200 OK Content-Type: audio/mpeg

mp3-файл

Возможные коды ошибок: 404.

Проверка текста с отрисовкой отчёта

js

/** 
 * @param {string} text — проверяемый текст
 * @param {Element} containerDom — элемент типа DOM, куда нужно отрисовать отчёт 
 * @param {function(score: ScoreResult)} onScore — функция обработки оценки
 */
function checkTextAndShowReport(text, containerDom, onScore): void

Получение модели результата проверки без отрисовки отчёта

js

/** 
 * @param {string} text — проверяемый текст
 * @param {(checkModel: Model) => void} onResult  
 **/
function checkTextWithoutShowReport(text, onResult): void

js

/**
 * Количественные оценочные данные 
 */
interface ScoreResult {
	/**
	 * количество ошибок
	 */
	errors: {
		/**
		 * орфографических
		 */
		ORFO: number,
		/**
		 * опечаток
		 */
		TYPO: number,
		/**
		 * пунктуационных
		 */
		PUNCT: number   
	},
	/**
	 * количество набранных баллов из 100 (в построении отчета не используется)	 */
	score: number,
	/**
	 * является ли текст похожим на текст диктанта, чтобы можно
	 * было искать ошибки (если значение false, то скорее всего
	 * количество ошибок будет нулевое)
	 */
	isTotalDict: boolean 
}
 
/**
 * Основная модель результата проверки
 */
interface Model {
	/**
	 * Уникальный id проверки, генерируется при каждом вызове алгоритма проверки
	 */
	checkId: string;
	/**
	 * Текст заголовка диктанта, разбитый на параграфы,
	 * если пользователь писал заголовок
	 */
	titles: Paragraph[],
	/**
	 * Текст диктанта, разбитый на параграфы
	 */
	text: Paragraph[],
	/**
	 * key-value объект со всеми допущенными ошибками.
	 * Ключом является поле error из модели Text.
	 */
	errors: Errors,
	/**
	 * Количественные оценки
	 */
	summary: Summary,
	/**
	 * Версия алгоритма проверки
	 */
	version: string,
	/**
	 * Является ли текст, введённый пользователем, похожим на текст диктанта.
	 * Если нет, то поиск ошибок не проводится.
	 */
	isDictantText: boolean,
	/**
	 * Список лексем с ошибками. Для построения отчёта не нужен. Нужен 
	 * для построения тепловой карты ошибок на текстах многих пользователей
	 */
	errorList: LexemeError[]
}
 
/**
 * простой массив "кусочков" текста
 */
type Paragraph = Text[]
/**
 * Модель "кусочка" текста, для построения отчета
 */
interface Text {
	/**
	 * Текст "кусочка" диктанта, написанный пользователем. Если на
	 * этом "кусочке" пользователь не сделал ошибок, то остальных полей нет
	 */
	text: string,
	/**
	 * Уникальный идентификатор ошибки, комбинация позиции и хеша ошибки
	 */
	id?: string,
	/**
	 * Количественные показатели ошибок у данного "кусочка" текста
	 */
	counts?: ErrorCounts,
	/**
	 * Идентификатор комплексной ошибки (может состоять из нескольких ошибок). 
	 * Ключ для key-value модели Errors
	 */
	error?: string,
	/**
	 * Позиция в диктанте (с какой по какую лексему).
	 * Для построения отчета не используется.
	 */
	position?: string | number
}
 
/**
 * Количество ошибок
 */
interface ErrorCounts {
	/**
	 * Орфографических
	 */
	ORFO?: number,
	/**
	 * Пунктуационные
	 */
	PUNCT?: number,
	/**
	 * Опечатки
	 */
	TYPO?: number,
	/**
	 * Неучтенные ошибки (не должно быть таких)
	 */
	UNEXPECTED?: number
}
 
/**
 * key-value контейнер ошибок, где ключом является поле error ошибки из модели Text
 */
interface Errors { 
	/**
	 * На фрагмент текста может быть несколько ошибок. Ошибки разделены по
	 * правилам (и это значит, что  количество элементов этого массива может
	 * не совпадать с суммой ORFO + PUNCT + TYPO)
	 */
	[key: string]: Error[];
}
 
/**
 * Модель, содержащая количественные оценки результата проверки
 */
interface Summary {
	/**
	 * Количество ошибок
	 */
	counts: ErrorCounts,
	/**
	 * Сколько баллов набрано из 100 возможных
	 * (для построения отчёта не используется)
	 */
	score: number
}
 
/**
 * Модель ошибки, с объяснением через правила русского языка
 */
interface Error {
	/**
	 * идентификатор ошибки из модели разметки (для построения отчёта не нужен)
	 */
	id?: string,
	/**
	 * Тип ошибки ORFO, PUNCT или TYPO
	 */
	kind: string,
	/**
	 * html размеченная ошибка (ошибочная часть выделена тегами <i></i>)
	 */
	title: string,
	/**
	 * Html объясенение ошибки, которое показывается в аннотации к ошибке
	 */
	description: string
}
 
/**
 * Модель используется для построения тепловой карты ошибок
 * Для отчёта не нужна.
 */
interface LexemeError {
	/**
	 * id ошибки позиция в диктанте + hash от написанного текста,
	 * для группировки одинаковых ошибок у разных пользователей
	 */
	id: string,
	/**
	 * Текст пользователя
	 */
	text: string,
	/**
	 * Ссылка на ошибку изначальной модель разметки в Учительской диктантов
	 */
	errorId: string,
	/**
	 * Тип ошибки ORFO, PUNCT или TYPO
	 */
	kind: string,
	/**
	 * Идентификатор начальной лексемы в модели разметки
	 */
	lexemeStartId: string,
	/**
	 * Идентификатор конечной лексемы в модели разметки
	 */
	lexemeEndId: string,
	/**
	 * Ошибка не в лексемах, а вставлена между лексем диктанта
	 */
	betweenStartEnd: boolean
}

Фабричный метод для создания проигрывателя диктанта

js

/**
 *  @param options ISimpleDictPlayerOptions настройки
 */
function createDictPlayer(options: ISimpleDictPlayerOptions): IDictScriptAudioPlayer;

js

/**
 * Возможности проигрывателя диктанта
 */
interface IDictScriptAudioPlayerCan {
	/**
	 * Можно включать проигрывание
	 */
	play: boolean;
	/**
	 * Можно останавливать проигрывание
	 */
	pause: boolean;
	/**
	 * Можно проигрывать предыдущее предложение
	 */
	playPrevSentence: boolean;
	/**
	 * Можно проигрывать предыдущий фрагмент
	 */
	playPrevFragment: boolean;
	/**
	 * Можно проигрывать текущий фрагмент повторно
	 */
	replayFragment: boolean;
	/**
	 * Можно проигрывать следующий фрагмент
	 */
	playNextFragment: boolean;
	/**
	 * Можно проигрывать следующее предложение
	 */
	playNextSentence: boolean;
}
 
/**
 * Текущее состояние проигрывателя диктанта
 */
interface IDictScriptAudioPlayerState {
	/**
	 * Продолжительность оставшейся диктовки
	 */
	dictationTime: number;
	/**
	 * Общее количество фрагментов диктовки
	 */
	fragmentsCount: number;
	/**
	 * Текущее положение в диктовке
	 */
	currentFragment: number;
	/**
	 * Текущая скорость набора
	 */
	typingSpeed: number;
	/**
	 * включен ли режим короткой диктовки
	 */
	shortMode: boolean;
	/**
	 * Субтитры для показа
	 */
	subtitles: string;
	/**
	 * Разрешённые действия с проигрывателем
	 */
	can: IDictScriptAudioPlayerCan;
}
 
/**
 * Проигрыватель диктанта
 */
interface IDictScriptAudioPlayer {
	/**
	 * Устанавливает текущий фрагмент для проигрывания
	 * @param value
	 */
	setPosition: (value: number) => void;
	/**
	 * Задаёт текущую скорость набора текста пользователем
	 * @param value
	 */
	setSpeed: (value: number) => void;
	/**
	 * Задаёт (или выключает) режим короткой диктовки (short mode)
	 * @param value
	 */
	setShortMode: (value: boolean) => void;
	/**
	 * Проигрывает диктант начиная с текущей позиции
	 */
	play: () => void;
	/**
	 * Приостанавливает проигрывание диктанта
	 */
	pause: () => void;
	/**
	 * Проигрывает диктант с начала предыдущего предложения
	 */
	playPrevSentence: () => void;
	/**
	 * Проигрывает диктант с начала предыдущего фрагмента диктовки
	 */
	playPrevFragment: () => void;
	/**
	 * Проигрывает повторно текущий фрагмент диктанта
	 */
	replayCurrentFragment: () => void;
	/**
	 * Проигрывает диктант с начала следующего фрагмента диктовки
	 */
	playNextFragment: () => void;
	/**
	 * Проигрывает диктант с начала следующего предложения
	 */
	playNextSentence: () => void;
}
 
/**
 * Настройки проигрывателя диктантов
 */
interface ISimpleDictPlayerOptions {
	/**
	 * Полный базовый путь URL'а для библиотеки медиафайлов этого диктанта
	 * (каталога media с медиаресурсами диктовки, размещённого на хостинге)
	 * @example https://totaldict.ru/d23/media
	 */
	mediaLibraryUrl: string;
	/**
	 * Скорость набора текста в знаках в минуту
	 */
	typingSpeed?: number;
	/**
	 * Функция обработчик изменений внутреннего состояния проигрывателя.
	 * Этот метод будет вызван при любых изменениях внутреннего
	 * состояния проигрывателя, чтобы пользовательский интерфейс мог
	 * отобразить эти изменения
	 * @param state IDictScriptAudioPlayerState
	 */
	onUpdateState?: (state: IDictScriptAudioPlayerState) => void;
}