Перейти к основному содержимому
Версия: 14.x

Внешний API

Внешний API позволяет программам получать доступ к функциям UMS или запускать их с помощью HTTP-вызова.

Как включить внешний API

Отредактируйте UMS.conf и настройте api_key следующим образом

api_key = секретный_пароль

секретный_пароль должен содержать не менее 12 символов.

Использование API

Если внешний API включён, API доступен с помощью POST-вызова в /api/COMMAND

Сканирование папок

повторное сканирование

НамерениеПересканирование всей библиотеки
URI/api/сканер папок/повторное сканирование
Содержание сообщенияНикто
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описаниеЭта команда не нуждается в содержании сообщения
Доступно с10.4.2

Может быть медленно для больших библиотек :::

Пример:

curl -w "%{http_code}\n" -H "api-ключ: секретный_пароль" http://localhost:5001/api/сканируемые папки/повторное сканирование

повторное сканирование файла или папки

НамерениеЧастичное пересканирование дерева файловой системы.
URI/api/сканируемые папки/повторно сканировать файл или папку
Содержание сообщенияПУТЬ_ К_СКАНИРОВАНИЮ
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описаниепример: "/music/pop/Madonna". Путь должен быть к корневой папке или к вложенной папке общего доступа.
Доступно с10.4.2

Пример:

curl -d "ПУТЬ_ К_СКАНИРОВАНИЮ" -w "%{http_code}\n" -H "api-key: секретный_пароль" -X СООБЩЕНИЕ http://localhost:5001/api/сканируемые папки/Повторно просканировать файл или папку

Нравится музыка (альбомы и песни)

нравится песня

Песня будет отмечена как понравившаяся.

НамерениеНравится песня, идентифицированная с помощью MusicBrainz TrackID
URI<span class="s1">/api/нравится/lпонравившаяся песня</span>
Содержание сообщенияmusicBrainz_trackID
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описаниеb8695995-45e9-405d-b4aa-e50e8760fe25
Доступно с10.20

Пример:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-ключ: секретный_пароль" -X СООБЩЕНИЕ http://localhost:5001/api/нравится/понравившаяся песня

не нравится песня

Песня не нравится

НамерениеНе нравится песня, идентифицированная MusicBrainz TrackID
URI<span class="s1">/api/нравится/</span>песня не нравится
Содержание сообщенияmusicBrainz_trackID
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описаниеb8695995-45e9-405d-b4aa-e50e8760fe25
Доступно с10.20

Пример:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-ключ: секретный_пароль" -X POST http://localhost:5001/api/нравится/песня не нравится

песня понравилась

Отметьте, если песня нравится.

НамерениеОтметьте, если понравилась песня, идентифицированная с помощью MusicBrainz TrackID
URI<span class="s1">/api/нравится/</span><span class="s1">песня мне нравится </span>
Содержание сообщенияmusicBrainz_trackID
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описаниеb8695995-45e9-405d-b4aa-e50e8760fe25
СОДЕРЖАНИЕ ОТВЕТАИСТИНА или ЛОЖЬ
Доступно с10.20

Пример:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-ключ: секретный_пароль" -X СООБЩЕНИЕ http://localhost:5001/api/нравится/понравившаяся песня

Этот вызов добавляет связанный атрибут понравившегося альбома, идентифицированный musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799af.

нравится альбом

Установите для состояния album like значение true.

НамерениеПонравившийся альбом, идентифицированный MusicBrainz ReleaseID
URI<span class="s1">/api/нравится/</span>понравившийся альбом
Содержание сообщенияmusicBrainz_releaseID
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описание1e0eee38-a9f6-49bf-84d0-45d0647799af
Доступно с10.20

Пример:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-ключ: секретный_пароль" -X СООБЩЕНИЕ http://localhost:5001/api/нравится/понравившаяся песня

не нравится альбом

Удалить статус альбома, как понравившегося .

НамерениеНе нравится песня, идентифицированная MusicBrainz ReleaseID
URI<span class="s1">/api/нравится/</span>альбом не нравится
Содержание сообщенияmusicBrainz_releaseID
Пример / описание текста сообщения1e0eee38-a9f6-49bf-84d0-45d0647799af
Доступно с10.20

Пример:

curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: секретный_пароль" -X POST http://localhost:5001/api/нравится/альбом не нравится

Этот вызов удалил связанный атрибут альбома, идентифицированный musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799af.

нравится альбом

Проверьте статус понравившегося альбома

ЗамыселПроверьте, понравился ли альбом, указанный в MusicBrainz ReleaseID
URI<span class="s1">/api/нравится/</span>понравившийся альбом
Содержание сообщенияmusicBrainz_releaseID
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описание1e0eee38-a9f6-49bf-84d0-45d0647799af
СОДЕРЖАНИЕ ОТВЕТА"ИСТИНА" или "ЛОЖЬ"
Доступно с10.20

Пример:

curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/isalbumliked

Этот вызов проверяет, идентифицирован ли альбом с помощью musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799af нравится.

Рейтинг

Rating API отвечает за рейтинг песен. Информация о рейтинге сохраняется во внутренней базе данных (кэш включен) и, при необходимости, в самом файле. Если в UMS.conf задано значение audio_update_rating_tag = true, поле оценки IDv3 также обновляется в файле песни (если поддерживается формат файла песни).

При просмотре сервера каталогов содержимого MusicBrainzTrackID (если доступно) и audiotrackID передаются как метаданные desc в элементе DIDL.

установить рейтинг

ЗамыселУстановите рейтинг в звездах (0 - 5) для песни, идентифицированной с помощью MusicBrainz TrackID
URI<span class="s1">/api/</span><span class="s1">rating/setrating</span>
Содержание сообщенияmusicbrainzTrackId /stars
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описаниеb8695995-45e9-405d-b4aa-e50e8760fe25/3
Доступно с10.20

Пример:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25/3" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/setrating

Этот вызов устанавливает рейтинг пользователей всех песен, идентифицированных musicbrainz track-id b8695995-45e9-405d-b4aa-e50e8760fe25 до 3.

установить рейтинг

Считывает рейтинг песни из базы данных

НамерениеПолучите рейтинг песни в звездах (0 - 5) с помощью внутреннего audiotrackID UMS. Текст ответа содержит информацию о рейтинге.
URI<span class="s1">/api/</span><span class="s1">rating/getrating </span>
Содержание сообщенияmusicbrainzTrackId
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описаниеb8695995-45e9-405d-b4aa-e50e8760fe25
Пример ОТВЕТА3
Доступно с10.20

Пример:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/getrating

Этот вызов считывает пользовательский рейтинг песни, идентифицированной по идентификатору трека musicbrainz b8695995-45e9-405d-b4aa-e50e8760fe25.

установите рейтинг по идентификатору audiotrack id

НамерениеУстановите оценку в звездах (0 - 5) для песни, идентифицированной с помощью внутреннего audiotrackID UMS
URI<span class="s1">/api/</span><span class="s1">rating/setRatingByAudiotrackId </span>
Содержание сообщенияtrackID /stars
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описание32
Доступно с11.0

Пример:

curl -d "32/3" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/setrating

Этот вызов устанавливает пользовательский рейтинг песен, определенный по audiotrackid 32, на 3.

получить рейтинг по ID аудиотрека

Считывает рейтинг песни из базы данных

ЗамыселПолучите рейтинг песни в звездах (0 - 5) по MusicBrainz TrackID. Текст ответа содержит информацию о рейтинге.
URI<span class="s1">/api/</span><span class="s1">rating/getRatingByAudiotrackId</span>
Содержание сообщенияидентификатор трека
Пример / описание текста сообщения32
Пример ОТВЕТА3
Доступно с11.0

Пример:

curl -d "32" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/getRatingByAudiotrackId

Этот вызов считывает пользовательский рейтинг песни, идентифицированной UMS audiotrack-id 32.

Резервное копирование / восстановление

Управляемые пользователем записи "понравившегося альбома" могут быть скопированы в подпапку каталога профиля с именем database_backup. Имя файла MUSIC_BRAINZ_RELEASE_LIKE. В случае, если база данных UMS будет удалена, просто вызовите функцию восстановления.

резервное копирование любимых альбомов

Таблица резервного копирования MUSIC_BRAINZ_RELEASE_LIKE в файловую систему

Замыселрезервное копирование понравившихся песен в файловую систему
URI<span class="s1"><span class="s1">/api/like/</span></span>backupLikedAlbums
ТИП ЗАПРОСАПОЛУЧИТЬ
СОДЕРЖАНИЕ ОТВЕТАOK или сообщение об ошибке
Доступно с10.20

Пример:

curl -w "%{http_code}\n" -H "api-ключ: секретный_пароль" http://localhost:5001/api/понравившиеся/дублированные альбомы

Этот вызов создаст резервную копию файла, содержащего понравившиеся альбомы

восстановить понравившиеся альбомы

Восстановление таблицы MUSIC_BRAINZ_RELEASE_LIKE из файловой системы

Замыселвосстановить понравившиеся песни из файла резервной копии
URI<span class="s1"><span class="s1"><span class="s1">/api/like/</span></span></span>restoreLikedAlbums
ТИП ЗАПРОСАПОЛУЧИТЬ
СОДЕРЖАНИЕ ОТВЕТАOK или сообщение об ошибке
Доступно с10.20

Пример:

curl -w "%{http_code}\n" -H "api-ключ: секретный_пароль" http://localhost:5001/api/понравившиеся/дублированные альбомы

Этот вызов восстанавливает файл резервной копии.

Плейлист

Включить службу

Отредактируйте UMS.conf и настройте папку управляемого списка воспроизведения, установив 

<span class="s1">managed_playlist_folder</span> = PATH_TO_PLAYLIST_FOLDER

для включения этой службы. По умолчанию эта служба отключена. Путь к папке плейлиста должен быть расположен под настроенным общим <span class="s1">каталогом</span> для изменения плейлиста, созданным этим API, который будет виден UMS.

список всех плейлистов

Читать доступные плейлисты Читать доступные плейлисты Читать доступные плейлисты Читать доступные плейлисты Эти имена плейлистов должны использоваться для последующих звонков для добавления или удаления песен.

ЗамыселДоставляет все поддерживаемые (m3u, m3u8 и pls) и доступные плейлисты из настроенной папки. Кроме имени плейлиста плейлист
URI<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">getAllPlaylists</span>
ТИП ЗАПРОСАПОЛУЧИТЬ
СОДЕРЖАНИЕ ОТВЕТАJSON массив имён плейлистов
Пример ОТВЕТА<span class="s1">["Поп","Джаз","Классика"]</span>
Доступно с11.0

Пример:

curl -d "" -w "\n%{http_code}\n" -H "api-key: секретный_пароль" -X GET http://localhost:5001/api/список воспроизведения/получить все списки воспроизведения

В этом вызове будут перечислены все доступные списки воспроизведения.

список доступных на сервере плейлистов

Все эти плейлисты известны UMS (базы данных/кэш включен). Эти имена плейлистов должны использоваться при последующих вызовах для добавления или удаления песен. ID плейлиста может быть использован для перехода непосредственно к плейлисту, просматривая объект $DBID$PLAYLIST$ базы данных.

ЗамыселПредоставляет все поддерживаемые (m3u, m3u8 и pls) и доступные плейлисты из настроенной папки
URI<span class="s1">`/api/</span><span class="s1">playlist</span><span class="s1">/</span>getserverplaylists` ``
ТИП ЗАПРОСАПОЛУЧИТЬ
СОДЕРЖАНИЕ ОТВЕТАМассив имен плейлистов в формате JSON
Пример ОТВЕТА[{"Имя списка воспроизведения":"Джаз","идентификатор плейлиста":5},{"Имя списка воспроизведения":"Списки","идентификатор плейлиста":343}]
Доступно светвь разработки

Пример:

curl -d "" -w "\n%{http_code}\n" -H "api-key: секретный_пароль" -X GET http://localhost:5001/api/список воспроизведения/получение списков воспроизведения сервера

Этот вызов выведет список всех имеющихся плейлистов, доступных UMS.

добавление треков в плейлисты

Требуемый audiotrackid предоставляется во время запросов браузера UPnP и может быть извлечен из атрибута ответа DIDL descMetadata

<ums-tags>
[...]
    <audiotrackid>ID</audiotrackid>
[...]
</ums-tags>
    <audiotrackid>ID</audiotrackid>
[...]
</ums-tags>
ЗамыселДобавить песню в плейлист
URI<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">addSongToPlaylist</span>
ТИП ЗАПРОСАСООБЩЕНИЕ
Содержание сообщенияaudiotrackid<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">/PLAYLIST</span>
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описание123/Поп
СОДЕРЖАНИЕ ОТВЕТАОТСУТСТВУЕТ
Доступно с11.0

Пример:

curl -d "123/Pop" -w "\n%{http_code}\n" -H "api-key: секретный_пароль" -X POST http://localhost:5001/api/список воспроизведения/добавить песню в список воспроизведения

Это добавляет песню с ID 123 в плейлист Pop.

Удалить песни из плейлиста

Требуемый audiotrackid предоставляется во время запросов браузера UPnP и может быть извлечен из атрибута ответа DIDL descMetadata

<ums-tags>
[...]
    <audiotrackid>ID</audiotrackid>
[...]
</ums-tags>
    <audiotrackid>ID</audiotrackid>
[...]
</ums-tags>

``

ЗамыселУдалить песню из плейлиста
URI<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">removeSongFromPlaylist</span>
ТИП ЗАПРОСАСООБЩЕНИЕ
Содержание сообщенияaudiotrackid<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">/PLAYLIST</span>
Пример / описание текста сообщения123/Поп
СОДЕРЖАНИЕ ОТВЕТАОТСУТСТВУЕТ
Доступно с11.0

Пример:

curl -d "123/Pop" -w "\n%{http_code}\n" -H "api-key: секретный_пароль" -X POST http://localhost:5001/api/список воспроизведения/удалить песню из списка воспроизведения

Это удаляет песню с ID 123 из плейлиста Pop.

создать новые плейлисты

Имя плейлиста должно быть предоставлено без пути и без расширения файлов. 

ЗамыселСоздание новых плейлистов в управляемой папке плейлиста
URI<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">createPlaylist</span>
ТИП ЗАПРОСАСООБЩЕНИЕ
Содержание сообщения<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">Название списка воспроизведения</span>
Пример СОДЕРЖАНИЯ СООБЩЕНИЯ/описаниеСовременный
СОДЕРЖАНИЕ ОТВЕТАОТСУТСТВУЕТ
Доступно с11.0

Пример:

curl -d "Современный" -w "\n%{http_code}\n" -H "api-key: секретный_пароль" -X POST http://localhost:5001/api/список воспроизведения/создать список воспроизведения

Этот вызов создает новый файл списка воспроизведения с именем Contemporary.m3u8 в папке управляемого списка воспроизведения.

Пример кода Java

Этот фрагмент кода показывает, как использовать API с библиотекой okhttp3.

import nextcp.dto.Config;
import nextcp.dto.UmsServerApiKey;
import okhttp3.Call;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

[...]

    public String executeCall() throws IOException
    {
        String postBody = "1e0eee38-a9f6-49bf-84d0-45d0647799af";
        String apiKey = "secret_password";
        RequestBody body = RequestBody.create(postBody, MediaType.parse("application/text"));
        String requestUrl = "http://127.0.0.1:5001/api/like/likealbum";
        Request request = new Request.Builder().url(requestUrl).addHeader("api-key", apiKey).post(body).build();
        Call call = okClient.newCall(request);
        Response response = call.execute();
        return response.body().string();
    }

    public String executeCall() throws IOException
    {
        String postBody = "1e0eee38-a9f6-49bf-84d0-45d0647799af";
        String apiKey = "secret_password";
        RequestBody body = RequestBody.create(postBody, MediaType.parse("application/text"));
        String requestUrl = "http://127.0.0.1:5001/api/like/likealbum";
        Request request = new Request.Builder().url(requestUrl).addHeader("api-key", apiKey).post(body).build();
        Call call = okClient.newCall(request);
        Response response = call.execute();
        return response.body().string();
    }

HTTP коды возврата

| 200 | OK | | 204 | успех, если предполагается, что содержимое не будет возвращено | | 401 | недопустимый ключ api | | 404 | запрошенный объект не найден | | 417 | сбой запроса API | | 503 | внешний api не включен. Установите api_key в UMS.conf с длиной 12 или более символов |