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