Version: 13.x

Harici API

Harici API, programların bir HTTP çağrısıyla UMS işlevlerine erişmesini veya bunları tetiklemesini sağlar.

Harici API nasıl etkinleştirilir

UMS.conf dosyasını düzenleyin ve şunun gibi bir api_anahtarı yapılandırın

api_anahtarı = gizli_parola

gizli_parola en az 12 karakterden oluşmak zorundadır.

API kullanımı

Eğer harici API etkinleştirildiyse, API’ye /api/KOMUT olarak yapılan bir POST çağrısıyla erişilebilir.

Klasör Tarama

rescan

Niyet	Tüm kütüphaneyi yeniden tarar
URI	`/api/folderscanner/rescan`
POST BODY	YOK
POST BODY örnek / açıklama	Bu komutun gövde içeriğine ihtiyacı yoktur
Şu sürümden beri mevcut	10.4.2

bilgi

Bu, büyük kütüphaneler için yavaş olabilir

Örnek:

curl -w "%{http_code}\n" -H "api-key: gizli_parola" http://localhost:5001/api/folderscanner/rescan

rescanFileOrFolder

Niyet	Dosya sisteminin kısmi bir alt ağacını yeniden tarar.
URI	`/api/folderscanner/rescanFileOrFolder`
POST BODY	TARANACAK_YOL
POST BODY örnek / açıklama	örnek: "/music/pop/Madonna". Yol, paylaşılan bir yolun kök veya alt klasörü olmak zorundadır.
Şu sürümden beri mevcut	10.4.2

Örnek:

curl -d "TARANACAK_YOL" -w "%{http_code}\n" -H "api-key: gizli_parola" -X POST http://localhost:5001/api/folderscanner/rescanFileOrFolder

Müzik Beğenme (albümler ve şarkılar)

like song

Şarkı beğenildi olarak işaretlenecektir.

Niyet	musicBrainz trackId ile tanımlanan bir şarkıyı beğenir
URI	`<span class="s1">/api/like/likesong</span>`
POST BODY	`musicBrainz_trackID`
POST BODY örnek / açıklama	b8695995-45e9-405d-b4aa-e50e8760fe25
Şu sürümden beri mevcut	10.20

Örnek:

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

dislike song

Şarkı beğenilmeyecektir

Niyet	musicBrainz trackId ile tanımlanan bir şarkıyı beğenmez
URI	`<span class="s1">/api/like/</span>dislikesong`
POST BODY	`musicBrainz_trackID`
POST BODY örnek / açıklama	b8695995-45e9-405d-b4aa-e50e8760fe25
Şu sürümden beri mevcut	10.20

Örnek:

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

is song liked

Şarkının beğenilip beğenilmediğini denetleyin.

Niyet	musicBrainz trackId ile tanımlanan şarkının beğenilip beğenilmediğini denetler
URI	`<span class="s1">/api/like/</span><span class="s1">issongliked</span>`
POST BODY	`musicBrainz_trackID`
POST BODY örnek / açıklama	b8695995-45e9-405d-b4aa-e50e8760fe25
RESPONSE BODY	`TRUE` veya `FALSE`
Şu sürümden beri mevcut	10.20

Örnek:

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

Bu çağrı, musicbrainz yayım kimliği 1e0eee38-a9f6-49bf-84d0-45d0647799af ile tanımlanan albümün beğenildi özniteliğini ekler.

like album

Albüm beğenme durumunu true olarak ayarlayın.

Niyet	musicBrainz releaseID ile tanımlanan bir albümü beğenir
URI	`<span class="s1">/api/like/</span>likealbum`
POST BODY	`musicBrainz_releaseID`
POST BODY örnek / açıklama	1e0eee38-a9f6-49bf-84d0-45d0647799af
Şu sürümden beri mevcut	10.20

Örnek:

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

dislike album

Albüm beğenme durumunu kaldırın.

Niyet	musicBrainz releaseID ile tanımlanan bir şarkıyı beğenmez
URI	`<span class="s1">/api/like/</span>dislikealbum`
POST BODY	`musicBrainz_releaseID`
POST BODY örnek / açıklama	1e0eee38-a9f6-49bf-84d0-45d0647799af
Şu sürümden beri mevcut	10.20

Örnek:

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

Bu çağrı, musicbrainz yayım kimliği 1e0eee38-a9f6-49bf-84d0-45d0647799af ile tanımlanan albümün beğenildi özniteliğini kaldırır.

is album liked

Albüm beğenme durumunu denetleyin.

Niyet	musicBrainz releaseID ile tanımlanan albümün beğenilip beğenilmediğini denetler
URI	`<span class="s1">/api/like/</span>isalbumliked`
POST BODY	`musicBrainz_releaseID`
POST BODY örnek / açıklama	1e0eee38-a9f6-49bf-84d0-45d0647799af
RESPONSE BODY	"TRUE" veya "FALSE"
Şu sürümden beri mevcut	10.20

Örnek:

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

Bu çağrı, musicbrainz yayım kimliği 1e0eee38-a9f6-49bf-84d0-45d0647799af ile tanımlanan albümün beğenilip beğenilmediğini denetler.

Derecelendirme

Derecelendirme API’si, şarkıları değerlendirmekten sorumludur. Derecelendirme bilgileri dahili veritabanına (önbellek etkin) ve isteğe bağlı olarak dosyanın kendisine kaydedilir. Eğer UMS.conf içinde audio_update_rating_tag = true olarak ayarlanırsa, IDv3 derecelendirme alanı da şarkı dosyasında güncellenir (şarkı dosyası biçimi destekleniyorsa).

İçerik dizini sunucusuna göz atarken, MusicBrainzTrackID (varsa) ve audiotrackID, DIDL öğesi içinde desc üstverisi olarak teslim edilir.

set rating

Niyet	musicBrainz trackId ile tanımlanan bir şarkıda derecelendirmeyi yıldız (0 - 5) olarak ayarlar
URI	`<span class="s1">/api/</span><span class="s1">rating/setrating</span>`
POST BODY	`musicbrainzTrackId` /`stars`
POST BODY örnek / açıklama	b8695995-45e9-405d-b4aa-e50e8760fe25/3
Şu sürümden beri mevcut	10.20

Örnek:

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

Bu çağrı, musicbrainz parça kimliği b8695995-45e9-405d-b4aa-e50e8760fe25 ile tanımlanan tüm şarkıların kullanıcı derecelendirmesini 3 olarak ayarlar.

get rating

Veritabanından şarkı derecelendirmesini okur

Niyet	musicBrainz trackID ile şarkı derecelendirmesini yıldız (0 - 5) olarak alır. Yanıt gövdesi derecelendirme bilgilerini içerir.
URI	`<span class="s1">/api/</span><span class="s1">rating/getrating </span>`
POST BODY	`musicbrainzTrackId`
POST BODY örnek / açıklama	b8695995-45e9-405d-b4aa-e50e8760fe25
RESPONSE BODY örnek	3
Şu sürümden beri mevcut	10.20

Örnek:

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

Bu çağrı, musicbrainz parça kimliği b8695995-45e9-405d-b4aa-e50e8760fe25 ile tanımlanan bir şarkının kullanıcı derecelendirmesini okur.

set rating by audiotrack id

Niyet	UMS dahili audiotrackID ile tanımlanan bir şarkıda derecelendirmeyi yıldız (0 - 5) olarak ayarlar
URI	`<span class="s1">/api/</span><span class="s1">rating/setRatingByAudiotrackId </span>`
POST BODY	`trackID` /`stars`
POST BODY örnek / açıklama	32
Şu sürümden beri mevcut	11.0

Örnek:

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

Bu çağrı, audiotrack kimliği 32 ile tanımlanan şarkıların kullanıcı derecelendirmesini 3 olarak ayarlar.

get rating by audiotrack id

Veritabanından şarkı derecelendirmesini okur

Niyet	UMS dahili audiotrackID ile şarkı derecelendirmesini yıldız (0 - 5) olarak alır. Yanıt gövdesi derecelendirme bilgilerini içerir.
URI	`<span class="s1">/api/</span><span class="s1">rating/getRatingByAudiotrackId</span>`
POST BODY	trackId
POST BODY örnek / açıklama	32
RESPONSE BODY örnek	3
Şu sürümden beri mevcut	11.0

Örnek:

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

Bu çağrı, UMS audiotrack-id 32 ile tanımlanan bir şarkının kullanıcı derecelendirmesini okur.

Yedekleme / Geri yükleme

Kullanıcı tarafından yönetilen "beğenilen albüm" girişleri, database_backup adlı bir profil dizini alt klasörüne yedeklenebilir. Dosya adı MUSIC_BRAINZ_RELEASE_LIKE’dır. UMS veritabanının silinmesi durumunda geri yüklemeyi çağırmanız yeterlidir.

backup liked albums

MUSIC_BRAINZ_RELEASE_LIKE tablosunu dosya sistemine yedekler

Niyet	Beğenilen şarkıları dosya sistemine yedekler
URI	`<span class="s1"><span class="s1">/api/like/</span></span>backupLikedAlbums`
REQUEST TYPE	GET
RESPONSE BODY	`OK` veya hata iletisi
Şu sürümden beri mevcut	10.20

Örnek:

curl -w "%{http_code}\n" -H "api-key: gizli_parola" -X GET http://localhost:5001/api/like/backupLikedAlbums

Bu çağrı, beğenilen albümleri içeren bir yedekleme dosyası oluşturacaktır.

restore liked albums

MUSIC_BRAINZ_RELEASE_LIKE tablosunu dosya sisteminden geri yükler

Niyet	Beğenilen şarkıları yedekleme dosyasından geri yükler
URI	`<span class="s1"><span class="s1"><span class="s1">/api/like/</span></span></span>restoreLikedAlbums`
REQUEST TYPE	GET
RESPONSE BODY	`OK` veya hata iletisi
Şu sürümden beri mevcut	10.20

Örnek:

curl -w "%{http_code}\n" -H "api-key: gizli_parola" -X GET http://localhost:5001/api/like/restoreLikedAlbums

Bu çağrı, yedekleme dosyasını geri yükler.

Çalma listesi

enable service

Bu hizmeti etkinleştirmek için UMS.conf dosyasını düzenleyin ve

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

parametresini ayarlayarak yönetilen bir çalma listesi klasörü yapılandırın. Varsayılan olarak bu hizmet etkisizleştirilmiştir. Çalma listesi klasörü yolu, UMS tarafından görünür olması için bu API tarafından yapılan değiştirilmiş çalma listesi için yapılandırılmış bir paylaşılan <span class="s1">klasörler</span> yolunun altında bulunmalıdır.

list all playlists

Mevcut çalma listelerini okur. Bu çalma listesi adları, sonraki çağrılarda şarkı eklemek veya kaldırmak için kullanılmak zorundadır.

Niyet	Tüm desteklenen (`m3u`, `m3u8` ve `pls`) ve yapılandırılmış klasördeki mevcut çalma listelerini sunar. Çalma listesi adının yanı sıra `playlistId` oynatma listeleri
URI	`<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">getAllPlaylists</span>`
REQUEST TYPE	GET
RESPONSE BODY	Çalma listesi adlarının JSON dizilimi
RESPONSE BODY örnek	`<span class="s1">["Pop","Jazz","Classic"]</span>`
Şu sürümden beri mevcut	11.0

Örnek:

curl -d "" -w "\n%{http_code}\n" -H "api-key: gizli_parola" -X GET http://localhost:5001/api/playlist/getAllPlaylists

Bu çağrı, tüm mevcut çalma listelerini listeleyecek.

list server accessible playlists

Bunların tümü UMS tarafından bilinen çalma listeleridir (veritabanı/önbellek etkin). Bu çalma listesi adları, sonraki çağrılarda şarkı eklemek veya kaldırmak için kullanılmak zorundadır. Çalma listesi kimliği, objectId $DBID$PLAYLIST$ concat databaseId’ye göz atarak doğrudan çalma listesine gitmek için kullanılabilir.

Niyet	Tüm desteklenen (`m3u`, `m3u8` ve `pls`) ve yapılandırılmış klasördeki mevcut çalma listelerini sunar
URI	<span class="s1">`/api/</span><span class="s1">playlist</span><span class="s1">/</span>getserverplaylists` ``
REQUEST TYPE	GET
RESPONSE BODY	Çalma listesi adlarının JSON dizilimi
RESPONSE BODY örnek	`[{"playlistName":"Jazz","playlistId":5},{"playlistName":"Charts","playlistId":343}]`
Şu sürümden beri mevcut	dev dalı

Örnek:

curl -d "" -w "\n%{http_code}\n" -H "api-key: gizli_parola" -X GET http://localhost:5001/api/playlist/getserverplaylists

Bu çağrı, UMS tarafından erişilebilen tüm mevcut çalma listelerini listeleyecek.

adding songs to playlists

Gerekli audiotrackid, UPnP tarama istekleri sırasında teslim edilir ve descMetadata DIDL yanıt özniteliğinden çıkarılabilir

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

Niyet	Çalma listesine şarkı ekler
URI	`<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">addSongToPlaylist</span>`
REQUEST TYPE	POST
POST BODY	`audiotrackid<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">/PLAYLIST</span>`
POST BODY örnek / açıklama	123/Pop
RESPONSE BODY	YOK
Şu sürümden beri mevcut	11.0

Örnek:

curl -d "123/Pop" -w "\n%{http_code}\n" -H "api-key: gizli_parola" -X POST http://localhost:5001/api/playlist/addSongToPlaylist

Bu, kimliği 123 olan şarkıyı Pop çalma listesine ekler.

removing songs from playlists

Gerekli audiotrackid, UPnP tarama istekleri sırasında teslim edilir ve descMetadata DIDL yanıt özniteliğinden çıkarılabilir

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

Niyet	Şarkıyı çalma listesinden kaldırır
URI	`<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">removeSongFromPlaylist</span>`
REQUEST TYPE	POST
POST BODY	`audiotrackid<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">/PLAYLIST</span>`
POST BODY örnek / açıklama	123/Pop
RESPONSE BODY	YOK
Şu sürümden beri mevcut	11.0

Örnek:

curl -d "123/Pop" -w "\n%{http_code}\n" -H "api-key: gizli_parola" -X POST http://localhost:5001/api/playlist/removeSongFromPlaylist

Bu, kimliği 123 olan şarkıyı Pop çalma listesinden kaldırır.

create new playlists

Çalma listesi adı herhangi bir yol ve dosya uzantısı olmadan sağlanmalıdır.

Niyet	Yönetilen çalma listesi klasöründe yeni çalma listeleri oluşturma
URI	`<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">createPlaylist</span>`
REQUEST TYPE	POST
POST BODY	`<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">ÇALMALİSTESİ_ADI</span>`
POST BODY örnek / açıklama	Modern
RESPONSE BODY	YOK
Şu sürümden beri mevcut	11.0

Örnek:

curl -d "Modern" -w "\n%{http_code}\n" -H "api-key: gizli_parola" -X POST http://localhost:5001/api/playlist/createPlaylist

Bu çağrı, yönetilen çalma listesi klasöründe Contemporary.m3u8 adlı yeni bir çalma listesi dosyası oluşturur.

Java kodu örneği

Bu kod parçacığı, API’nin okhttp3 kütüphanesi ile nasıl kullanılacağını gösterir.

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();
    }

HTTP dönüş kodları

| 200 | TAMAM | | 204 | hiçbir içeriğin döndürülmemesi gerekiyorsa başarılı | | 401 | geçersiz API anahtarı | | 404 | istenen nesne bulunamadı | | 417 | API isteği başarısız oldu | | 503 | harici api etkin değil. UMS.conf dosyasında 12 veya daha fazla karakter uzunluğunda bir api_anahtarı ayarlayın |

Harici API nasıl etkinleştirilir​

API kullanımı​

Klasör Tarama​

rescan​

rescanFileOrFolder​

Müzik Beğenme (albümler ve şarkılar)​

like song​

dislike song​

is song liked​

like album​

dislike album​

is album liked​

Derecelendirme​

set rating​

get rating​

set rating by audiotrack id​

get rating by audiotrack id​

Yedekleme / Geri yükleme​

backup liked albums​

restore liked albums​

Çalma listesi​

enable service​

list all playlists​

list server accessible playlists​

adding songs to playlists​

removing songs from playlists​

create new playlists​

Java kodu örneği​

HTTP dönüş kodları​

Harici API nasıl etkinleştirilir

API kullanımı

Klasör Tarama

rescan

rescanFileOrFolder

Müzik Beğenme (albümler ve şarkılar)

like song

dislike song

is song liked

like album

dislike album

is album liked

Derecelendirme

set rating

get rating

set rating by audiotrack id

get rating by audiotrack id

Yedekleme / Geri yükleme

backup liked albums

restore liked albums

Çalma listesi

enable service

list all playlists

list server accessible playlists

adding songs to playlists

removing songs from playlists

create new playlists

Java kodu örneği

HTTP dönüş kodları