API Externa
A API externa permite que programas acedam ou acionem funcionalidades UMS com um pedido HTTP.
Como ativar a API externa
Editar UMS.conf e configurar uma api_key como esta
api_key = palavra_passe
A secret_password deve ter no mínimo 12 caracteres.
Utilização da API
Se a API externa estiver ativada, a API estará acessível através de um pedido POST para /api/COMMAND
Procurar em Pastas
Pesquisar novamente
| Intenção | Verificar toda a biblioteca. |
|---|---|
| URI | /api/folderscanner/rescan |
| CAIXA DE PUBLICAÇÃO | NENHUM |
| POST BODY exemplo / descrição | Este comando não precisa de corpo no pedido |
| Disponível desde | 10.4.2 |
Isto pode ser lento para bibliotecas grandes
Exemplo:
curl -w "%{http_code}\n" -H "api-key: secret_password" http://localhost:5001/api/folderscanner/rescan
Pesquisar novamente ficheiro ou pasta
| Intenção | Verificar parte do sistema de ficheiros. |
|---|---|
| URI | /api/folderscanner/rescanFileOrFolder |
| CAIXA DE PUBLICAÇÃO | CAMINHO_PARA_PESQUISA |
| POST BODY examplo / descrição | exemplo: "/music/pop/Madonna". O caminho deve ser a raiz ou uma subpasta de um caminho partilhado. |
| Disponível desde | 10.4.2 |
Exemplo:
Gostos em Músicas (Álbuns e Canções)
Gostar da música
A música será marcada com Gosto.
| Intenção | Colocar gosto numa música identificada pelo trackId da musicBrainz. |
|---|---|
| URI | <span class="s1">/api/like/likesong</span> |
| CAIXA DE PUBLICAÇÃO | musicBrainz_trackID |
| POST BODY examplo / descrição | b8695995-45e9-405d-b4aa-e50e8760fe25 |
| Disponível desde | 10.20 |
Exemplo:
curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/likesong
Não gostar a música
Música deixará de estar marcada com Gosto.
| Intenção | Retirar gosto numa música identificada pelo trackId da musicBrainz. |
|---|---|
| URI | <span class="s1">/api/like/</span>dislikesong |
| CAIXA DE PUBLICAÇÃO | musicBrainz_trackID |
| POST BODY examplo / descrição | b8695995-45e9-405d-b4aa-e50e8760fe25 |
| Disponível desde | 10.20 |
Exemplo:
curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/dislikesong
Gostaram da música
Verificar se gostaram da música.
| Intenção | Verificar se gostaram da música identificada por musicBrainz trackId |
|---|---|
| URI | <span class="s1">/api/like/</span><span class="s1">issongliked</span> |
| CAIXA DE PUBLICAÇÃO | musicBrainz_trackID |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | b8695995-45e9-405d-b4aa-e50e8760fe25 |
| CAIXA DE RESPOSTA | TRUE or FALSE |
| Disponível desde | 10.20 |
Exemplo:
curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/issongliked
Esta escolha adiciona o atributo gostado do álbum identificado por musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799af.
Gostar do álbum
Define o estado do álbum como true.
| Intenção | Colocar gosto num álbum identificado pelo trackId da musicBrainz. |
|---|---|
| URI | <span class="s1">/api/like/</span>likealbum |
| CAIXA DE PUBLICAÇÃO | musicBrainz_releaseID |
| 1e0eee38-a9f6-49bf-84d0-45d0647799af | |
| 10.20 |
Exemplo:
curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/likealbum
Não gostar do álbum
Remover gostar do estado do álbum.
| Intenção | Remover gosto numa música identificada pelo trackId da musicBrainz. |
|---|---|
| URI | <span class="s1">/api/like/</span>dislikealbum |
| CAIXA DE PUBLICAÇÃO | musicBrainz_releaseID |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | 1e0eee38-a9f6-49bf-84d0-45d0647799af |
| Disponível desde | 10.20 |
Exemplo:
curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/dislikealbum
Esta escolha adiciona o atributo gostado do álbum identificado por musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799af.
é um álbum com gosto
Verificar o estado de gosto do álbum
| Intenção | Verificar se o álbum tem gosto identificado por musicBrainz trackId |
|---|---|
| URI | <span class="s1">/api/like/</span>isalbumliked |
| CAIXA DE PUBLICAÇÃO | musicBrainz_releaseID |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | 1e0eee38-a9f6-49bf-84d0-45d0647799af |
| CAIXA DE RESPOSTA | "TRUE" or "FALSE" |
| Disponível desde | 10.20 |
Exemplo:
curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/isalbumliked
Esta opção verifica se o álbum identificado por musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799afestá com gosto.
Classificação
A API de avaliação é responsável pela avaliação de músicas. Informações de avaliação são guardadas no base de dados interna (cache habilitado) e, opcionalmente, no próprio arquivo. Se oaudio_update_rating_tag = true estiver definido no UMS. o campo de classificação conf IDv3 também está a ser actualizado no arquivo de música (se o formato do arquivo de músicas for suportado).
Ao navegar pelo servidor de directório de conteúdo, MusicBrainzTrackID (se disponível) e audiotrackID são disponibilizados como metadados desc dentro do elemento DIDL.
Defina a classificação
| Intenção | Classificar com estrelas (0 - 5) uma música identificada pelo trackId do musicBrainz |
|---|---|
| URI | <span class="s1">/api/</span><span class="s1">rating/setrating</span> |
| CAIXA DE PUBLICAÇÃO | musicbrainzTrackId /stars |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | b8695995-45e9-405d-b4aa-e50e8760fe25/3 |
| Disponível desde | 10.20 |
Exemplo:
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
Esta opção define a classificação do utilizador de todas as músicas identificadas pelo track-id de música b8695995-45e9-405d-b4aa-e50e8760fe25 para 3.
Aceda à classificação
Lê avaliação de músicas na base de dados
| Intenção | Obtenha a classificação da música em estrelas (0 - 5) pela musicBrainz trackID. A caixa de resposta contém as informações da classificação. |
|---|---|
| URI | <span class="s1">/api/</span><span class="s1">rating/getrating </span> |
| CAIXA DE PUBLICAÇÃO | musicbrainzTrackId |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | b8695995-45e9-405d-b4aa-e50e8760fe25 |
| CAIXA DE RESPOSTA exemplo | 3 |
| Disponível desde | 10.20 |
Exemplo:
curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/getrating
Esta opção define a classificação do utilizador de todas as músicas identificadas pelo track-id de música b8695995-45e9-405d-b4aa-e50e8760fe25 .
Definir avaliação por id da faixa de áudio
| Intenção | Classificar com estrelas (0 - 5) uma música identificada pelo audiotrackID interno do UMS |
|---|---|
| URI | <span class="s1">/api/</span><span class="s1">rating/setRatingByAudiotrackId </span> |
| CAIXA DE PUBLICAÇÃO | trackID /stars |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | 32 |
| Disponível desde | 11.0 |
Exemplo:
curl -d "32/3" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/setrating
Esta opção define a classificação das músicas identificadas pelo id da faixa de áudio32 para 3.
Definir avaliação por id da faixa de áudio
Lê avaliação de músicas na base de dados
| Obtenha a classificação da música em estrelas (0 - 5) pela ID da faixa de áudio interna do UMS. A caixa de resposta contém informações da classificação. | |
|---|---|
<span class="s1">/api/</span><span class="s1">rating/getRatingByAudiotrackId</span> | |
| Id da faixa | |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | 32 |
| CAIXA DE RESPOSTA exemplo | 3 |
| 11.0 |
curl -d "32" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/getRatingByAudiotrackId
Esta opção lê a classificação do utilizador de uma música identificada pelo audiotrack-id UMS 32.
Cópia de segurança / Restauro
Entradas marcadas pelo utilizador como "álbum que gosto" podem ser guardadas numa sub-pasta de diretórios chamada database_backup. O nome de arquivo é MUSIC_BRAINZ_RELEASE_LIKE. No caso em que o banco de dados UMS seja apagado, basta escolher "Restaurar".
Cópia de segurança de álbuns que gosto
Cópia de segurança da tabela MUSIC_BRAINZ_RELEASE_LIKE no sistema de arquivos
| Intenção | Fazer cópia de segurança das músicas com gosto para o sistema de arquivos |
|---|---|
| URI | <span class="s1"><span class="s1">/api/like/</span></span>backupLikedAlbums |
| SOLICITAR TIPO | GET |
| CAIXA DE RESPOSTA | OK ou mensagem de erro |
| Disponível desde | 10.20 |
Exemplo:
curl -w "%{http_code}\n" -H "api-key: secret_password" -X GET http://localhost:5001/api/like/backupLikedAlbums
Esta opção cria um arquivo da cópia de segurança contendo álbuns com gosto.
restaurar álbuns com gosto
Restaura tabela MUSIC_BRAINZ_RELEASE_LIKE a partir do sistema de ficheiros
| Intenção | Restaurar músicas com gosto do arquivo da cópia de segurança |
|---|---|
| URI | <span class="s1"><span class="s1"><span class="s1">/api/like/</span></span></span>restoreLikedAlbums |
| SOLICITAR TIPO | GET |
| CAIXA DE RESPOSTA | OK ou mensagem de erro |
| Disponível desde | 10.20 |
Exemplo:
curl -w "%{http_code}\n" -H "api-chave: palavra-passe" -X GET http://localhost:5001/api/gosto/restaurar álbuns com gosto
Esta opção restaura o arquivo da cópia de segurança.
Lista de reprodução
Habilitar serviço
Edite o UMS.conf e configure uma pasta da lista de reprodução gerida pela configuração
<span class="s1">managed_playlist_folder</span> = PATH_TO_PLAYLIST_FOLDER
Por habilitar este serviço. Este serviço está desativado por padrão O caminho da pasta da lista de reprodução, deverá estar localizado debaixo de um caminho partilhado <span class="s1">pastas</span> configurado para a lista de reprodução, criado por esta API para ficar visível pelo UMS
Listar todas as listas de reprodução
Ler listas de reprodução disponíveis Estes nomes de listas de reprodução devem ser usados para subsequentes acções de remoção ou adição de músicas
| Intenção | Entrega todos os (m3u, m3u8 e pls) suportados e listas de reprodução disponíveis a partir da pasta configurada. Ao lado do nome da lista de reprodução, as listas de reprodução playlistId são |
|---|---|
| URI | <span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">getAllPlaylists</span> |
| GET | |
| Variedade JSON de nomes de listas de reprodução | |
<span class="s1">["Pop","Jazz","Classic"]</span> | |
| Disponível desde | 11.0 |
Exemplo:
curl -w "%{http_code}\n" -H "api-chave: palavra-passe" -X GET http://localhost:5001/api/lista de reprodução/aceder a todas as listas de reprodução
Este comando listará todas as listas de reprodução disponíveis.
Enumera as listas de reprodução acessíveis no servidor
Estas são todas as listas de reprodução conhecidas pelo UMS (base de dados/cache habilitado). Estes nomes de listas de reprodução devem ser usados para subsequentes acções de remoção ou adição de músicas O ID da playlist pode ser usado para navegar directamente para a lista de reprodução navegando pelo objectId $DBID$PLAYLIST$ concat databaseId.
| Intenção | Entrega todos os (m3u, m3u8 e pls) suportados e listas de reprodução disponíveis a partir da pasta configurada. |
|---|---|
| URI | <span class="s1">`/api/</span><span class="s1">playlist</span><span class="s1">/</span>getserverplaylists` `` |
| SOLICITAR TIPO | GET |
| CAIXA DE RESPOSTA | Variedade JSON de nomes de listas de reprodução |
| CAIXA DE RESPOSTA exemplo | [{"playlistName":"Jazz","playlistId":5},{"playlistName":"Tabelas","playlistId":343}] |
| Disponível desde | filial de desenvolvimento |
Exemplo:
curl -w "%{http_code}\n" -H "api-chave: palavra-passe" -X GET http://localhost:5001/api/lista de reprodução/aceder a todas as listas de reprodução
Esta opção listará todas as listas de reprodução disponíveis acessíveis pelo UMS.
adicionar músicas às playlists
A faixa de áudio necessária é entregue durante solicitações de navegação UPnP e pode ser extraída do atributo de resposta DIDL descMetadata
<ums-tags>
[...]
<audiotrackid>ID</audiotrackid>
[...]
</ums-tags>
| Intenção | Adicionar música à lista de reprodução |
|---|---|
| URI | <span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">addSongToPlaylist</span> |
| SOLICITAR TIPO | POST |
| CAIXA DE PUBLICAÇÃO | audiotrackid<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">/PLAYLIST</span> |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | 123/Pop |
| CAIXA DE RESPOSTA | NENHUM |
| Disponível desde | 11.0 |
Exemplo:
curl -w "%{http_code}\n" -H "api-chave: palavra-passe" -X GET http://localhost:5001/api/lista de reprodução/aceder a todas as listas de reprodução
Esta opção adiciona a música com o ID 123à lista de reprodução Pop.
Remover faixas da lista de reprodução
A faixa de áudio necessária é entregue durante solicitações de navegação UPnP e pode ser extraída do atributo de resposta DIDL descMetadata
<ums-tags>
[...]
<audiotrackid>ID</audiotrackid>
[...]
</ums-tags>
``
| Intenção | Remover faixa da lista de reprodução |
|---|---|
| URI | <span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">removeSongFromPlaylist</span> |
| SOLICITAR TIPO | POST |
| CAIXA DE PUBLICAÇÃO | audiotrackid<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">/PLAYLIST</span> |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | 123/Pop |
| CAIXA DE RESPOSTA | NENHUM |
| Disponível desde | 11.0 |
Exemplo:
curl -w "%{http_code}\n" -H "api-chave: palavra-passe" -X PUBLICAÇÃO http://localhost:5001/api/lista de reprodução/remover música da lista de reprodução
Esta opção remove a música com o ID 123da lista de reprodução Pop.
Criar nova lista de reprodução
O nome da lista de reprodução deve ser fornecido sem qualquer caminho e sem extensões de arquivo.
| Intenção | Criar novas listas de reprodução na pasta gerida de listas de reprodução |
|---|---|
| URI | <span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">createPlaylist</span> |
| SOLICITAR TIPO | POST |
| CAIXA DE PUBLICAÇÃO | NOME_LISTA DE REPRODUÇÃO |
| CAIXA DE PUBLICAÇÃO exemplo/descrição | Contemporâneo |
| CAIXA DE RESPOSTA | NENHUM |
| Disponível desde | 11.0 |
Exemplo:
curl -w "%{http_code}\n" -H "api-chave: palavra-passe" -X PUBLICAÇÃO http://localhost:5001/api/lista de reprodução/criarListadereprodução
Esta opção cria um novo arquivo de lista de reprodução chamado Contemporâneo.m3u8 na pasta de listas geridas.
Exemplo de código Java
Este código snippet mostra como usar a API com biblioteca 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();
}
Códigos de retorno HTTP
| 200 | OK | | 204 | sucesso se nenhum conteúdo for retornado | | 401 | chave api inválida | | 404 | objeto pedido não foi encontrado | | 417 | Pedido de API falhou | | 503 | api externa não está habilitado. Defina uma api_key no UMS.conf com comprimento de 12 ou mais caracteres |