Интеграция ELiS со сторонними информационными системами средствами API ELiS

Бывают задачи, когда ресурсы в ELiS надо собрать и встроить в сторонних системах.

В ELiS для этого есть поддержка протоколов и собственное API. Далее рассказывается как именно можно программным путем собрать ресурсы в ELiS и встроить в сторонние сайты.

Задача разделяется на:

извлечение метаданных;
полнотекстовый поиск;
скачивание ресурсов;
встраивание ресурсов;
создание аккаунтов и авторизация пользователей;
сбор статистики.

Извлечение метаданных[править]

OAI-PMH[править]

Метаданные в ELiS можно получить по протоколу OAI-PMH.

Документация: https://elibsystem.ru/docs/oai-pmh

OAI-PMH позволяет получить в XML все добавленные ресурсы за определенный промежуток времени в формате метаданных Dublin Core.

OAI-PMH можно использовать для извлечения изменений и, например, раз в сутки ходить в ELiS и получать список добавленных ресурсов для автоматического экспорта.

Все ресурсы ELiS имеют шаблон https?://elis.example.com/node/\d+. Т.е. содержат в URI идентификатор ноды (ресурса). Например https://elis.example.com/node/12345.

Если вам нужны еще какие-то метаданные, получить их можно добавлением /info к URI ресурса, т.е. по шаблону https://elis.example.com/node/\d+/info вы получите доступ к служебному отображению ресурса в Drupal7 и всем связанным полям.

Endpoint: https://elis.example.com/elis/oai.

OPDS[править]

Вы можете последовательно извлечь все ноды главного каталога по протоколу OPDS.

Документация: https://elibsystem.ru/docs/opds

Endpoint: https://elis.example.com/opds.

Обложки[править]

Обложки есть не у всех ресурсов ELiS. Но если обложка есть, её можно получить по URI node/\d+/cover.

По-умолчанию ширина 280 пикселей, а высота - какая получится.

Но по URL может сработать перенаправление на файл изображения, а может быть выдано непосредственно изображение.

Пример: http://demo.elibsystem.ru/node/35856/cover

Полнотекстовый поиск[править]

В ELiS есть поддержка OpenSearch.

Откройте https://elis.example.com/elis/opensearch.xml для просмотра шаблонов, по которым можно получить результаты поиска в виде ссылок на ресурсы в HTML и в ATOM.

Пример: https://demo.elibsystem.ru/elis/opensearch?query=%D0%98%D0%B2%D0%B0%D0%BD%D0%BE%D0%B2

Скачивание ресурса[править]

Возможность скачивания ресурса может ограничиваться правами доступа. В некоторых случаях ссылка для скачивания дается по OAI-PMH.

Встраивание ресурсов[править]

Есть два способа:

добавление /embed к идентификатору ноды;
использование протокола oEmbed.

Встраивание добавлением /embed к URL[править]

Для встраивания с помощью /embed надо просто к любому URL добавить /embed и указать получившийся URL в iframe. Частая проблема при встраивании в iframe - не известна оптимальная высота ресурсов. Здесь следует обращать внимание на тип ноды. Ноды типа презентации, видео и трансляций имеют соотношение сторон контента 16/9 + высота панели и именно так можно попытаться рассчитать высоту iframe зная тип ресурса. Для большинства остальных ресурсов можно выбрать любую высоту.

Тип ресурса можно извлечь во время сканирования метаданных. Откройте плеер нужного типа и посмотрите код вставки как пример, который вам можно реализовать во внешней системе.

Встраивание с помощью oEmbed[править]

Протокол oEmbed позволяет отправить запросы на специальный endpoint и попросить код вставки для ресурса по некоторому URL.

В ELiS oEmbed endpoint является '/oembedder', а в качестве URL надо запрашивать ресурс в виде https://elis.example.com/node/12345.

Endpoint: https://elis.example.com/oembedder

Пример запроса:

https://elis.psu.ru/oembedder?maxwidth=616px&format=jsonp&callback=generatedcallback&url=https%3A%2F%2Felis.psu.ru%2Fnode%2F510014

Создание аккаунта и авторизация пользователя[править]

Есть API для создания ассоциированного с некоторой организацией пользователя и перенаправления его на некоторый ресурс. Воспользуйтесь им.

https://elibsystem.ru/docs/admin/autologin.html

Используйте параметр redirect для перенаправления пользователя на плеер после успешной авторизации.

Если вы хотите встроить ресурсы и чтобы ваши пользователи смотрели ресурс в авторизованном виде, укажите в iframe логинящую ссылку, которая сперва создаст пользователя и авторизует пользователя и затем перенаправит его на плеер с ресурсом.

Сбор статистики[править]

В связи со сбором "цифровых следов" организациям интересней получить статистику в виде сырых логов воспроизведения ресурсов.

Пример URL: https://elis.example.com/reports/elis/playlog.tsv?start=2020-01-01&end=2020-12-31&orgId=12345

Здесь:

start - дата с начала дня которой нужны логи.
end - дата на конец дня которой нужны логи.
orgId - идентификатор организации в ELiS (выдается владельцем ELiS, тот же самый, что участвует при генерации ссылки входа).

Владелец ELiS может ограничить доступ к статистике и, скорее всего, для сбора статистики не в обезличенном виде требовать авторизации пользователя.

Если для получения статистики требуется авторизация, используйте авторизацию по ссылке, указав в перенаправлении URL с 'reports/elis/playlog.tsv?...'.

Темизация[править]

При встраивании можно добавить GET-параметры chromeColor и textColor с указанием цвета в шестнадцатеричном формате без начального '#'.

Пример:

https://demo.elibsystem.ru/node/27545/embed?chromeColor=323232&textColor=FFFFFF