home

Интеграция 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

Рекомендации по написанию ПО[править]

Вначале надо разобраться с OAI-PMH и написать коннектор, который выгрузит вам метаданные и каталог (иерархию коллекций) или использовать OPDS, если не нужна синхронизация и надо выгрузить отдельную ветвь каталога.

Если вам метаданных по OAI-PMH недостаточно, использовать node/$nid/info для прямого доступа к объектам в формате JSON.

Дальше вам надо решить принципиальный вопрос с навигацией. Какая она будет, подходит ли та, что есть в ELiS. Здесь вопрос не технического характера, возможно вам потребуется писать какой-то маппинг навигации из ELiS во внешнюю систему.

Затем во внешней системе создаются записи, где надо в качестве URL ресурса указать либо node/$nid/embed либо получить код вставки по oEmbed.

Если вы хотите, чтобы ваши пользователи были в ELiS авторизованы (например для сбора статистики), вам надо попросить владельца ELiS создать в ELiS вашу организацию, привязать к ней секретный ключ, IP-адреса и сообщить вам orgId и секретный ключ для возможности генерации логинящих ссылок.

Во внешней информационной системе встраивается iframe плеера. А если необходимо чтобы пользователь был авторизован, то iframe с логинящей ссылкой, которая затем перенаправит на плеер.

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