Версия: 13.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.

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

<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 или более символов |

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

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

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

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

Пересканировать файл или папку​

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

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

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

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

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

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

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

Рейтинг​

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

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

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

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

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

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

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

Плейлист​

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

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

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

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

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

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

Пример кода Java​

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

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

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

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

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

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

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

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

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

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

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

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

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

Рейтинг

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

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

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

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

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

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

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

Плейлист

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

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

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

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

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

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

Пример кода Java

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